buninu-linux 0.4.0 → 0.6.0

package/README.md

@@ -5,18 +5,21 @@
   * a prebuilt kernel from Alpine
   * a prebuilt systemd EFI stub from Alpine
   * initramfs JavaScript components:
-  * `/init.js` and other modules
+  * `/init.js`, Buninu userspace, and other modules
   * initramfs Native components:
-  * Official `bun-linux-x64-musl` and its dependencies
-    + ld-musl-x86_64.so.1
-    + libc.musl-x86_64.so.1 (intentional copy)
+  * Official `bun-linux-x64-musl` (or `bun-linux-aarch64-musl`) and its dependencies
+    + ld-musl-x86_64.so.1 (ld-musl-aarch64.so.1)
+    + libc.musl-x86_64.so.1 (libc.musl-aarch64.so.1; intentional copy)
     + libgcc_s.so.1
     + libstdc++.so.6
+- Boots on real x86-64 UEFI hardware; QEMU system testing supports both x86_64
+  and aarch64 guests.
 - The kernel runs `bun` as PID 1
   * Everything an init would normally do — mounting filesystems, loading modules, configuring the network, reaping children
   * happens in JavaScript through `bun:ffi`
   * There is no BusyBox and no C bootstrap.
 
+- Homepage: <https://buninu.org>
 - Souce: [github.com/jjtseng93/buninu-linux](https://github.com/jjtseng93/buninu-linux)
 - Buninu userspace source: [github.com/jjtseng93/buninu](https://github.com/jjtseng93/buninu)
   + **BUNinu Is Not Unix** 🐮
@@ -37,6 +40,10 @@
   * IP addresses and routes are configured manually because the image does not yet include a DHCP client.
   * The bundled `jmi` editor, jsmdcui editor/terminal multitasking, and local JavaScript execution also work.
   * The graphical terminal `bunterm` draws on the framebuffer with CJK, colour emoji and kitty images; see [Showing images](#showing-images)
+    + Also has mouse click, wheel, and cursor drawing
+    + Simplified browser works: @sanohiro/casty in chroot debian
+    + (Use at your own risk: We haven't fully examined its code)
+    + See [Commands inside `/bin`](#commands-inside-bin) for browser usage instructions
 
 ---
 
@@ -45,6 +52,11 @@
 
 ## Quick start
 
+> [!IMPORTANT]
+> This section builds an image for real x86-64 UEFI hardware. To build and
+> test either an x86_64 or aarch64 guest with `qemu-system` instead, see
+> [Build and test with QEMU on macOS or Linux](#build-and-test-with-qemu-on-macos-or-linux).
+
 - This guide builds a bootable `buninu-linux-<version>.img`
 - The documented build environment is Debian 13 under Termux PRoot
 - A regular Debian installation works as well.
@@ -74,9 +86,11 @@ apt install binutils-mingw-w64-x86-64 cpio curl dosfstools fakeroot mtools parte
 mkdir -p /data/data/com.termux/files/home/buninu-build
 cd /data/data/com.termux/files/home/buninu-build
 
-$HOME/.bun/bin/bun x buninu-linux --version
+export PATH=$HOME/.bun/bin:$PATH
+
+bun x buninu-linux --version
 
-$HOME/.bun/bin/bun x buninu-linux -fb --real --export
+bun x buninu-linux -fb --real --export
 ```
 
 `--export` copies the completed `vda.img` out of bunx's package directory and
@@ -112,6 +126,10 @@ this overwrites it completely.
 sudo dd if='buninu-linux-<version>.img' of=/dev/sdX bs=4M conv=fsync status=progress
 ```
 
+Alternatively, copy the exported `.img` file to a
+[Ventoy](https://www.ventoy.net/en/index.html) USB drive and select it from
+Ventoy's boot menu.
+
 #### Booting from the USB drive
 
 Boot that drive as x86-64 UEFI media. The UKI is unsigned, so disable Secure
@@ -145,6 +163,110 @@ described under [Basic configuration](#basic-configuration). Run `poweroff` for
 shutdown. After editing the initramfs, `bun ./index.js -b --real --export` rebuilds the
 image; `-h` lists all flags.
 
+### Build and test with QEMU on macOS or Linux
+
+> [!IMPORTANT]
+> This section covers guests built and run with `qemu-system` only. To build
+> an image for real x86-64 UEFI hardware, follow [Quick start](#quick-start)
+> above and use `-fb --real --export`.
+
+The same `index.js` builds and boots Buninu Linux in QEMU on a Mac or Linux
+host. `--arch` picks the guest:
+
+| host | `--arch x86_64` (default) | `--arch aarch64` (alias `arm64`) |
+| --- | --- | --- |
+| Apple Silicon Mac | q35, emulated (TCG) | `virt`, hardware-accelerated (Hypervisor.framework) |
+| Intel Mac | q35, hardware-accelerated (Hypervisor.framework) | `virt`, emulated (TCG) |
+| x86-64 Linux | q35, hardware-accelerated (KVM) when `/dev/kvm` is usable | `virt`, emulated (TCG) |
+| arm64 Linux | q35, emulated (TCG) | `virt`, hardware-accelerated (KVM) when `/dev/kvm` is usable |
+| Android Termux | q35, emulated (TCG) | `virt`, KVM when `/dev/kvm` is usable, otherwise TCG |
+
+`run-qemu.sh` chooses the accelerator itself; `ACCEL=tcg` forces emulation.
+
+#### macOS
+
+This project does not currently support a native macOS build toolchain (GNU
+cpio and tar, `fakeroot`, `parted`, PE-aware binutils), so on a Mac `index.js`
+always runs the fetch and build stages in a Debian 13 container built from
+[`Dockerfile`](Dockerfile), with the checkout bind-mounted. The image is built
+on first use and tagged with a hash of the Dockerfile. Only the run stage uses
+the Mac itself:
+
+```sh
+# Docker Desktop (running) for -f/-b, QEMU and its UEFI firmware for -r
+brew install qemu
+
+# Apple Silicon: Hypervisor.framework accelerates the aarch64 guest
+bun ./index.js -fbr --arch arm64
+
+# The x86_64 guest works too, emulated
+bun ./index.js -fbr
+```
+
+The first boot line from `run-qemu.sh` names the guest, machine, accelerator
+and firmware it picked. A bare `-r` boots whichever architecture `vda.img`
+was last built for; `-br --arch arm64` is the aarch64 edit-and-boot loop.
+
+#### amd64 Linux
+
+On Debian or Ubuntu the build runs on the host exactly as in PRoot, and QEMU
+uses KVM for the x86_64 guest when the user can open `/dev/kvm`:
+
+```sh
+apt install binutils-mingw-w64-x86-64 cpio curl dosfstools fakeroot mtools parted unzip
+apt install qemu-system-x86 ovmf
+bun ./index.js -fbr
+```
+
+Pass `--docker` to build in the same container as macOS instead of installing
+the build packages; the aarch64 guest additionally needs
+`binutils-aarch64-linux-gnu` for a host build and `qemu-system-arm
+qemu-efi-aarch64` to run.
+
+#### What differs on aarch64
+
+* The image is `vda/EFI/BOOT/BOOTAA64.EFI` on the same GPT disk, built from
+  Alpine's aarch64 packages and `bun-linux-aarch64-musl`.
+* The serial console is `ttyAMA0` (QEMU `virt`'s PL011) instead of `ttyS0`.
+* `--real` is x86_64 only: its module set is PC hardware.
+* The current aarch64 QEMU configuration supplies no framebuffer or PS/2
+  devices, so `bunterm` has nothing to draw on yet; the serial REPL and the
+  Buninu shell work as on x86_64.
+* `--export` writes `buninu-linux-<version>-aarch64.img`.
+* Before the kernel starts, Homebrew's aarch64 EDK2 prints a few
+  `Error: Image at … start failed` lines (its own drivers for hardware `virt`
+  does not have) and `ConvertPages: failed to find range …` (it cannot place
+  the UKI at the stub's preferred address and relocates it). Both are
+  harmless; `BdsDxe: starting Boot0001` follows and the boot continues.
+
+#### Testing on a Linux host in Docker
+
+`test/host/host-test.sh` checks the Linux-host path from any machine with
+Docker: it starts a fresh Debian 13 container of the chosen CPU with the
+build packages above and QEMU, clones the committed `HEAD` of this checkout,
+builds both guests with that toolchain (not `--docker`) and boots each one,
+driving the serial console through `test/host/boot-test.exp`:
+
+```sh
+test/host/host-test.sh arm64     # a Linux arm64 host (native on Apple Silicon)
+test/host/host-test.sh amd64     # a Linux x86-64 host (emulated there)
+```
+
+Every step — REPL, `start()`, `uname`, eth0, PID 1, a tmpfs mount, a fetch
+from the guest, `poweroff` — waits for its expected output, and the run ends
+with `### PASS` and exit status 0 or `### FAIL` and 1. Uncommitted changes to
+the project are not tested; commit first. `GUESTS=aarch64` limits the guests,
+`BUILD_FLAGS=--linux-lts` adds build flags, and `downloads/` is used read-only
+as the download cache. Docker Desktop exposes no `/dev/kvm`, so there both
+guests run under TCG; on a Linux host with KVM the script passes it through
+and the matching guest boots with `accel=kvm`. On macOS the same
+`boot-test.exp` also drives a local boot: `expect test/host/boot-test.exp
+"$PWD" aarch64` after `bun ./index.js -b --arch arm64`.
+
+`ALPINE_MIRROR` swaps the Alpine CDN for a mirror, e.g.
+`ALPINE_MIRROR=https://mirrors.edge.kernel.org/alpine`; every download is still
+checked against its pinned SHA-256.
+
 ## Using Buninu Linux
 
 ### Basic configuration
@@ -212,6 +334,13 @@ bun hlw.js
 If `Enter` is not recognized in a particular terminal, try `Ctrl-J` or
 `Ctrl-M`.
 
+#### jsmdcui
+- `jsmdcui` is the same editor, but by default executes markdown files as interactive Apps
+- Be careful not to run markdown files from strangers
+  * Otherwise it can run any command on your PC
+- `jsmdcui --cdp-maze` runs a self-solving maze game
+  * Run `bunterm` first to show its Emojis
+
 ### Panes, terminals, and tabs
 
 `jmi` and jsmdcui can keep editors and terminal sessions open together. Press
@@ -310,6 +439,9 @@ buninu-help
 # Markdown view with its images in place
 # cfg.net first to show that GitHub image
 jsmdcui --allow-url README.md
+
+# The mouse works in bunterm; --no-mouse leaves /dev/input alone
+bunterm -e jsmdcui --allow-url README.md
 ```
 
 `bunterm` draws with Skia (CanvasKit) and understands the kitty graphics
@@ -333,18 +465,26 @@ needs a kernel with a framebuffer: build with `--linux-lts` or `--real`
 | `poweroff` | sync pending writes and power off through the Linux reboot system call | `poweroff --help` |
 | `reboot` | sync pending writes and restart through the shared Linux reboot logic | `reboot --help` |
 | `tar` | create, extract, or list tar archives with gzip and zstd compression through `Bun.Archive` | `tar --help` |
-| `bunterm` | a graphical terminal on the framebuffer: Skia (CanvasKit) text with CJK, colour emoji, seamless box drawing, kitty graphics images; xterm.js's emulator core over Bun's built-in PTY | `bunterm --help` |
+| `stripansi` | remove ANSI escape sequences from stdin, `-`, or one or more files and concatenate the results | — |
+| `chroot` | `chroot(2)` into another root directory, mounting `/proc`, `/sys`, `/dev`, `/dev/pts`, `/run`, `/tmp` and `/etc/resolv.conf` for you and unmounting them afterwards | `chroot --help` |
+| `bunterm` | a graphical terminal on the framebuffer: Skia (CanvasKit) text with CJK, colour emoji, seamless box drawing, kitty graphics images, with the mouse working, wheel scrollback included (`--no-mouse` turns it off); xterm.js's emulator core over Bun's built-in PTY | `bunterm --help` |
 
-Besides `bun` (and `sh`/`node` pointing at it), `/bin` includes nine commands
+Besides `bun` (and `sh`/`node` pointing at it), `/bin` includes eleven commands
 implemented as Bun scripts.
 
-The small `tar` follows the current `Bun.Archive` boundary: extraction
-restores directories and symbolic links, while hard links are skipped by Bun
-1.4.3. Creation stores regular files but not Unix metadata, links, or empty
-directories, and listing reports regular files only. It supports gzip and
-Bun's built-in zstd, not xz or bzip2.
+The small `tar` reads the archive's own headers for links and listing, so
+extraction restores directories, hard links and every symbolic link —
+including the absolute targets `Bun.Archive` refuses, which is what makes an
+unpacked Alpine root filesystem usable — and `-t` lists every member, not
+only regular files. Creation still follows the `Bun.Archive` boundary: it
+stores regular files but not Unix metadata, links, or empty directories. It
+supports gzip and Bun's built-in zstd, not xz or bzip2.
 
-`--help` renders each Markdown manual in the terminal. Common examples:
+- `--help` renders each Markdown manual in the terminal.
+- The `bun x` examples below require network access: 
+  * `bun x` downloads the requested program from the npm registry and runs it without installing it permanently. 
+  * If they fail the 1st time, try `bun pm cache rm`
+- Common examples:
 
 ```sh
 mount /dev/sda1 /mnt --mkdir
@@ -354,6 +494,65 @@ mount -t ntfs3 -o force /dev/sda3 /mnt/windows
 umount /mnt
 umount -R /mnt
 
+
+# Clone a Git repository through bunproot
+bun x bunproot --git clone https://github.com/jjtseng93/bunproot
+
+# Read bunproot's Git manual without ANSI formatting in jmi
+bunterm
+bun x bunproot --git --readme | stripansi | jmi
+
+
+
+# Download and enter an x64 Debian rootfs
+# Make sure you have run this already:
+#   bunterm --font-size 13
+bun x bunproot --git --yes clone https://github.com/jjtseng93/js-udocker
+cd js-udocker
+bun udocker.js pull --platform=linux/amd64 debian:13
+bun udocker.js create --name db debian:13
+cd ~/.udocker/containers/db/ROOT
+chroot . /bin/bash
+apt update
+apt install curl unzip chromium fonts-noto-cjk fonts-noto-color-emoji npm
+curl -fsSL https://bun.sh/install | bash
+bun x bunmsh
+# We haven't fully reviewed
+# @sanohiro/casty's safety
+# !!!Use at your own risk!!!
+# !!!Use at your own risk!!!
+# !!!Use at your own risk!!!
+# !!!Use at your own risk!!!
+# !!!Use at your own risk!!!
+# !!!Use at your own risk!!!
+# !!!Use at your own risk!!!
+# !!!Use at your own risk!!!
+# !!!Use at your own risk!!!
+# !!!Use at your own risk!!!
+bun i -g @sanohiro/casty
+# When clicking around, don’t release the mouse button immediately after pressing it, to make sure the mouse-down event is triggered
+casty https://github.com/jjtseng93/buninu-linux
+
+
+
+# Download and enter an x64 Alpine minirootfs
+bun x bunproot --download-alpine-x64
+mkdir alpine
+cd alpine
+tar xvf ../alpine-minirootfs-*-x86_64.tar.gz
+cp $(which bun) bin
+chroot .
+apk add libgcc libstdc++
+
+
+# Enter a root filesystem on a disk. /proc, /sys, /dev, /dev/pts, /run, /tmp
+# and /etc/resolv.conf are mounted for you and removed again on exit
+chroot /mnt
+chroot /mnt /bin/bun --version
+chroot -n /mnt /bin/sh        # traditional: mount nothing
+
+
+
 ip link set eth0 up
 ip addr add 192.168.1.50/24 dev eth0
 ip route add default via 192.168.1.1
@@ -498,10 +697,13 @@ it too). Its physical-image stages run as fetch → build:
 | --- | --- | --- |
 | `-f`, `--fetch` | `fetch-alpine.sh`, `fetch-bun.sh` | first clone, or after bumping a pinned version |
 | `-b`, `--build` | `build-uki.sh`, `build-image.sh` | after editing `initramfs/init.js` or the kernel command line |
+| `--arch ARCH` | explicitly selects `x86_64` (default for fetch/build) or `aarch64`; a bare `-r` detects the last built UKI | building or running a particular guest architecture |
+| `--docker` | `-f`/`-b` inside the container from `Dockerfile` (always on macOS) | no Debian toolchain on the host |
 
 `--export` is a post-build option: after `-b` finishes, it copies `vda.img` to
 the directory where the command was invoked as
-`buninu-linux-<version>.img`. It therefore requires `-b`/`--build` and is the
+`buninu-linux-<version>.img` (`buninu-linux-<version>-aarch64.img` for
+`--arch aarch64`). It therefore requires `-b`/`--build` and is the
 recommended way to retain an image produced through npx/bunx:
 
 ```sh
@@ -520,26 +722,33 @@ failing halfway. The shell scripts do the actual work and each still runs on
 its own.
 
 ```text
-index.js                  entry point: -f / -b / --export / --linux-lts / --real
+index.js                  entry point: -f / -b / -r / --arch / --docker / --export / --linux-lts / --real
+Dockerfile                the Debian 13 build toolchain for --docker (and macOS)
 fetch-alpine.sh           [fetch]  kernel, EFI stub, musl, network/input modules
 fetch-bun.sh              [fetch]  Bun, libstdc++, libgcc
 build-uki.sh              [build]  UKI; calls scripts/pack-initramfs.sh
 build-image.sh            [build]  GPT disk image; shared with the hello-world EFI
+run-qemu.sh               [run]    QEMU q35 (x86_64) or virt (aarch64), KVM/HVF/TCG
+scripts/arch.sh           per-architecture pins, hashes and names, sourced by all of the above
 scripts/fetch.sh          hash-checked download helper, sourced by fetch-*.sh
 scripts/pack-initramfs.sh cpio archive with the device nodes
-hello/                    hello-world EFI: hello.c and build-hello.sh
-test/                     the retired C bootstrap and its build script
-initramfs/                init.js and the committed libraries; rest fetched
+hello/                    hello-world EFI: hello.c and build-hello.sh (x86_64 only)
+test/                     the retired C bootstrap and its build script (x86_64 only)
+test/host/                build-and-boot test on a fresh Linux amd64/arm64 host, in Docker
+initramfs/                init.js, commands, userspace: the same for every architecture
+native/<arch>/            musl and the GCC runtime (committed); bun and modules (fetched)
 ```
 
-The `--real` inputs are Alpine v3.24 `linux-lts-6.18.52-r0`, musl `1.2.6-r2`,
+The `--real` inputs are Alpine v3.24 `linux-lts-6.18.53-r0`, musl `1.2.6-r2`,
 `systemd-efistub-260.2-r0`, `libstdc++`/`libgcc` `15.2.0-r5`, and Bun 1.4.2
-`linux-x64-musl-baseline`. There is no BusyBox and no userland beyond Bun
-itself.
+`linux-x64-musl-baseline`. The aarch64 guest uses the same versions from
+Alpine's aarch64 repository and Bun's `linux-aarch64-musl`. There is no BusyBox
+or conventional native userland; Bun and the JavaScript-based Buninu userspace
+provide the commands.
 
 Every step is idempotent and `-f` re-downloads nothing: `scripts/fetch.sh`
-treats each pinned SHA-256 as the cache key, so a file already in `downloads/`
-with the right hash is used as-is, and anything missing, truncated, stale or
+treats each pinned SHA-256 as the cache key, so a file already in
+`downloads/<arch>/` with the right hash is used as-is, and anything missing, truncated, stale or
 tampered with is fetched again and has to pass the same hash before a script
 extracts from it. Bumping a version changes both the file name and the hash, so
 it always refetches.
@@ -554,11 +763,11 @@ and copies the final `vda.img` to the invocation directory.
 
 | script | reads | writes |
 | --- | --- | --- |
-| `fetch-alpine.sh` | Alpine CDN | `kernel/vmlinuz-lts`, `kernel/linuxx64.efi.stub`, musl, and the selected network, storage, input, power and filesystem modules with trimmed module indexes |
-| `fetch-bun.sh` | GitHub, Alpine CDN | `initramfs/bin/bun`, `initramfs/lib/{libc.musl-x86_64.so.1,libstdc++.so.6,libgcc_s.so.1}` |
-| `scripts/pack-initramfs.sh` | `initramfs/` | `build/initramfs.cpio.gz` |
-| `build-uki.sh` | that archive, kernel, stub | `build/cmdline`, `build/os-release`, `vda/EFI/BOOT/BOOTX64.EFI` |
-| `build-image.sh` | `vda/EFI/BOOT/BOOTX64.EFI` | `vda.img` |
+| `fetch-alpine.sh` | Alpine CDN | `kernel/<arch>/vmlinuz-<flavor>`, `kernel/<arch>/linuxx64.efi.stub` (`linuxaa64.efi.stub`), `native/<arch>/lib/ld-musl-<arch>.so.1`, and the selected network, storage, input, power and filesystem modules under `native/<arch>/lib/modules/` with trimmed module indexes |
+| `fetch-bun.sh` | GitHub, Alpine CDN | `native/<arch>/bin/bun`, `native/<arch>/lib/{libc.musl-<arch>.so.1,libstdc++.so.6,libgcc_s.so.1}` |
+| `scripts/pack-initramfs.sh` | `initramfs/`, then `native/<arch>/` over it | `build/initramfs.cpio.gz` |
+| `build-uki.sh` | that archive, kernel, stub | `build/cmdline`, `build/os-release`, `vda/EFI/BOOT/BOOTX64.EFI` (`BOOTAA64.EFI`) |
+| `build-image.sh` | `vda/EFI/BOOT/BOOTX64.EFI` (`BOOTAA64.EFI`) | `vda.img` |
 
 `build-uki.sh` calls `scripts/pack-initramfs.sh` itself, so that one is rarely
 run directly.
@@ -576,8 +785,11 @@ boot.
 
 #### UKI layout
 
-`build-uki.sh` appends sections to systemd's `linuxx64.efi.stub` with
-`objcopy`, at hand-picked VMAs because `objcopy` will not lay them out for you:
+`build-uki.sh` appends sections to systemd's architecture-specific EFI stub
+with `objcopy`, at calculated VMAs because `objcopy` will not lay them out for
+you. The following sizes and offsets describe the current x86_64 `--real`
+image; aarch64 uses `linuxaa64.efi.stub`, whose larger stub moves `.osrel` and
+`.cmdline`, and every build measures the inputs to prevent overlap:
 
 ##### UKI sections
 
@@ -586,11 +798,12 @@ boot.
 | `.text` | +0x0 | the stub itself | 66 KB |
 | `.osrel` | +0x20000 | `build/os-release` | 78 B |
 | `.cmdline` | +0x30000 | `build/cmdline` | 136 B |
-| `.linux` | +0x2000000 | `kernel/vmlinuz-lts` | 14.5 MB |
+| `.linux` | +0x2000000 | `kernel/x86_64/vmlinuz-lts` | 14.5 MB |
 | `.initrd` | +0x3000000 | `build/initramfs.cpio.gz` | 44.6 MB |
 
-The current `--real` result is a single 59.3 MB PE32+ file holding kernel, initramfs and command
-line.
+The current x86_64 `--real` result is a single 59.3 MB PE32+ file holding the
+kernel, initramfs and command line. Other architectures, flavors and source
+revisions can produce different sizes.
 
 #### Disk layout
 
@@ -605,13 +818,15 @@ rejects the volume.
 LBA 0              protective MBR
 LBA 1..33          primary GPT
 LBA 2048..262110   ESP, FAT32 "EFIBOOT", type GUID C12A7328-F81F-11D2-BA4B-00A0C93EC93B
-                     /EFI/BOOT/BOOTX64.EFI     the UKI
+                     /EFI/BOOT/BOOTX64.EFI     x86_64 UKI
+                     /EFI/BOOT/BOOTAA64.EFI    aarch64 UKI (in an aarch64 image)
 LBA 262111..       backup GPT
 ```
 
 128 MiB sparse, 1 MiB-aligned, with 34 sectors reserved at the end for the
-backup GPT. `EFI/BOOT/BOOTX64.EFI` is the removable-media fallback path, so the
-firmware runs it without any NVRAM boot entry.
+backup GPT. `EFI/BOOT/BOOTX64.EFI` and `EFI/BOOT/BOOTAA64.EFI` are the
+architecture-specific removable-media fallback paths, so matching firmware
+runs the one present in the image without any NVRAM boot entry.
 
 #### Real-hardware boot details
 
@@ -621,7 +836,7 @@ The physical boot chain is firmware → the UKI stub → its embedded
 and, with the currently pinned kernel, embeds this complete command line:
 
 ```text
-console=ttyS0,115200 console=tty0 REAL_MACHINE=1 panic=0 PATH=/bin KERNEL_RELEASE=6.18.52-0-lts rdinit=/bin/bun -- -e import('/init.js')
+console=ttyS0,115200 console=tty0 REAL_MACHINE=1 panic=0 PATH=/bin KERNEL_RELEASE=6.18.53-0-lts rdinit=/bin/bun -- -e import('/init.js')
 ```
 
 Serial kernel logging is retained, while the final console makes
@@ -638,12 +853,14 @@ runner separately from the PRoot build dependencies:
 pkg install qemu-system-x86-64
 ```
 
-That package supplies OVMF at `$PREFIX/share/qemu/edk2-x86_64-code.fd`. Build
-without `--real`; this selects Alpine `linux-virt`, omits the physical-hardware
+That package supplies OVMF at `$PREFIX/share/qemu/edk2-x86_64-code.fd`, next to
+QEMU's own binary, which is where `run-qemu.sh` looks after `OVMF_FILE` and
+Debian's `/usr/share/OVMF/OVMF_CODE_4M.fd` (Homebrew's `share/qemu` is found
+the same way). Build without `--real`; this selects Alpine `linux-virt`, omits the physical-hardware
 module set, and puts `ttyS0` last so serial stdio owns `/dev/console`:
 
 ```text
-console=tty0 console=ttyS0,115200 panic=0 PATH=/bin KERNEL_RELEASE=6.18.52-0-virt rdinit=/bin/bun -- -e import('/init.js')
+console=tty0 console=ttyS0,115200 panic=0 PATH=/bin KERNEL_RELEASE=6.18.53-0-virt rdinit=/bin/bun -- -e import('/init.js')
 ```
 
 Build and boot it with:
@@ -652,8 +869,7 @@ Build and boot it with:
 bun ./index.js -fb
 
 # When running inside PRoot with Termux's native qemu-system-x86_64,
-# expose both the native executable and its OVMF path:
-PREFIX=/data/data/com.termux/files/usr \
+# put it on PATH; its OVMF is found next to it:
 PATH="/data/data/com.termux/files/usr/bin:$PATH" \
 bun ./index.js -r
 ```
@@ -661,9 +877,11 @@ bun ./index.js -r
 If QEMU is installed inside the current Debian environment instead, plain
 `bun ./index.js -r` is sufficient; `run-qemu.sh` will use Debian's OVMF path.
 
-`bun ./index.js -r` runs `run-qemu.sh`, which boots `vda.img` on q35 under TCG
-with 512 MiB, a virtio disk, virtio-net user networking, no display, and COM1
-on stdio. Anything after `--` is appended to the QEMU command line. Ctrl-C
+`bun ./index.js -r` runs `run-qemu.sh`, which boots `vda.img` on q35 (the
+aarch64 image on `virt`) with 1 GiB, a virtio disk, virtio-net user
+networking, no display, and the first serial port on stdio. It uses KVM or
+Hypervisor.framework when the guest matches the host CPU and TCG otherwise;
+see [Build and test with QEMU on macOS or Linux](#build-and-test-with-qemu-on-macos-or-linux). Anything after `--` is appended to the QEMU command line. Ctrl-C
 quits QEMU. Leaving the REPL does not end the session: `init.js` restarts it,
 because a PID 1 that exits panics the kernel.
 
@@ -679,7 +897,7 @@ For an even shorter initramfs loop, bypass the UKI and disk image:
 
 ```sh
 qemu-system-x86_64 -machine q35,accel=tcg -cpu max -m 512M \
-    -kernel kernel/vmlinuz-virt -initrd build/initramfs.cpio.gz \
+    -kernel kernel/x86_64/vmlinuz-virt -initrd build/initramfs.cpio.gz \
     -append "console=ttyS0,115200 panic=0 PATH=/bin rdinit=/bin/bun -- -e console.log(1+1)" \
     -nic user,model=virtio-net-pci -display none -serial stdio -no-reboot
 ```
@@ -730,12 +948,14 @@ Two things to expect:
 
 The `/bin` commands described earlier are Bun scripts built on two shared
 modules in `/lib`. `--help` uses `Bun.markdown.ansi` to render the Markdown
-manual with hyperlinks. The shared pieces are:
+manual with hyperlinks, and prints the page's absolute path at the end so it
+can be read or edited directly. The shared pieces are:
 
-* `/lib/dlopen.js` — one `bun:ffi` binding to `/lib/libc.musl-x86_64.so.1`
+* `/lib/dlopen.js` — one `bun:ffi` binding to `/lib/libc.musl-<arch>.so.1`
   (`mount`, `umount2`, `ioctl`, `socket`, `sync`, `reboot`, `syscall`, …), `errno`/`strerror`,
   a `SysError` class and the `showDocument()` helper behind every `--help`.
-  `init.js` keeps its own copy of the binding because it runs before `/proc`
+  `process.arch` picks the libc file name and the `finit_module` syscall
+  number, the only raw syscall the commands make. `init.js` keeps its own copy of the binding because it runs before `/proc`
   exists and cannot import anything.
 * `/lib/modprobe.js` — `modprobe(name)` resolves `modules.alias` and
   `modules.dep` under `/lib/modules/<release>/` and calls `finit_module`
@@ -757,7 +977,7 @@ The default `--real` image embeds this kernel command line (shown for the
 currently pinned LTS release):
 
 ```text
-console=ttyS0,115200 console=tty0 REAL_MACHINE=1 panic=0 PATH=/bin KERNEL_RELEASE=6.18.52-0-lts rdinit=/bin/bun -- -e import('/init.js')
+console=ttyS0,115200 console=tty0 REAL_MACHINE=1 panic=0 PATH=/bin KERNEL_RELEASE=6.18.53-0-lts rdinit=/bin/bun -- -e import('/init.js')
 ```
 
 The physical display (`tty0`) is the final console and therefore owns PID 1's
@@ -812,14 +1032,20 @@ was found.
 It installs signal handlers, loads a separate physical copy of musl through
 `bun:ffi`, mounts `/proc`, `/sys`, `/dev`, `/tmp` and `/dev/pts` (without
 the devpts mount every pty open fails with `ENODEV`, since `/dev/ptmx`
-resolves through `/dev/pts/ptmx`), prints a greeting, and starts `node:repl`.
+resolves through `/dev/pts/ptmx`), turns Num Lock on, prints a greeting, and
+starts `node:repl`. The kernel starts every virtual console with Num Lock
+off, so the keypad would type arrows instead of digits; init sets it through
+`KDSKBLED` on each console that exists, as the current state and as the state
+a console is reset to. A console first activated later — `Ctrl-Alt-F3` on a
+fresh boot — starts from the kernel default again, and `numlock()` in the REPL
+(or `numlock(false)`) applies the setting to every console again.
 Submitting an empty or whitespace-only REPL line prints the welcome message
 and the available `cfg` getters again. The loader and libc paths
 contain identical bytes but are deliberately distinct inodes:
 
 ```text
-/lib/ld-musl-x86_64.so.1
-/lib/libc.musl-x86_64.so.1
+/lib/ld-musl-x86_64.so.1      /lib/ld-musl-aarch64.so.1
+/lib/libc.musl-x86_64.so.1    /lib/libc.musl-aarch64.so.1
 ```
 
 Calling `dlopen` on the same musl inode that is already acting as Bun's loader
@@ -866,9 +1092,15 @@ for the userspace session.
     + [Or build from a source checkout](#or-build-from-a-source-checkout)
     + [Write the image to a USB drive](#write-the-image-to-a-usb-drive)
     + [Booting from the USB drive](#booting-from-the-usb-drive)
+  * [Build and test with QEMU on macOS or Linux](#build-and-test-with-qemu-on-macos-or-linux)
+    + [macOS](#macos)
+    + [amd64 Linux](#amd64-linux)
+    + [What differs on aarch64](#what-differs-on-aarch64)
+    + [Testing on a Linux host in Docker](#testing-on-a-linux-host-in-docker)
 - [Using Buninu Linux](#using-buninu-linux)
   * [Basic configuration](#basic-configuration)
   * [Editor quick start](#editor-quick-start)
+    + [jsmdcui](#jsmdcui)
   * [Panes, terminals, and tabs](#panes-terminals-and-tabs)
     + [Pane and tab controls](#pane-and-tab-controls)
   * [Using Bun Modern Shell](#using-bun-modern-shell)
@@ -914,15 +1146,16 @@ MIT License; see [LICENSE](LICENSE). The Buninu userspace under
 `initramfs/buninu/` is also MIT (`initramfs/buninu/LICENSE`) and carries its
 own third-party notices, listed at the end of [NOTICE.md](NOTICE.md).
 
-The repository also commits four third-party platform binaries under
-`initramfs/lib/`, and the built image redistributes several more. Each stays
+The repository also commits four third-party platform binaries per guest
+architecture under `native/<arch>/lib/`, and the built image redistributes
+several more. Each stays
 under its own terms, with the full texts in [`LICENSES/`](LICENSES/):
 
 ### Bundled component licenses
 
 | Component | License | Where |
 |---|---|---|
-| musl (`ld-musl-x86_64.so.1`, `libc.musl-x86_64.so.1`) | MIT | committed |
+| musl (`ld-musl-x86_64.so.1`, `libc.musl-x86_64.so.1`, and the `aarch64` pair) | MIT | committed |
 | GCC runtime (`libgcc_s.so.1`, `libstdc++.so.6`) | GPL-3.0-or-later with the GCC Runtime Library Exception | committed |
 | Linux kernels and networking, storage, xHCI, USB and HID modules | GPL-2.0-only with the Linux syscall note | image only |
 | systemd EFI stub | LGPL-2.1-or-later | image only |
@@ -941,4 +1174,5 @@ lets them ship next to MIT-licensed code, so nothing here changes Buninu
 Linux's own terms — but if your organisation screens for GPL, these are the
 components it will find. [NOTICE.md](NOTICE.md) records the
 exact Alpine build of every component, the pinned aports commit that is its
-Corresponding Source, and SHA-256 sums for every binary.
+Corresponding Source, package SHA-256 sums and selected extracted-file
+SHA-256 sums.

package/build-image.sh

@@ -3,9 +3,13 @@ set -euo pipefail
 
 cd "$(dirname "$0")"
 
+. ./scripts/arch.sh
+
 mkdir -p vda/EFI/BOOT
-test -s vda/EFI/BOOT/BOOTX64.EFI || {
-    echo "error: build stage: no EFI payload yet; run ./build-uki.sh (./index.js -b) or ./hello/build-hello.sh first" >&2
+test -s "vda/EFI/BOOT/$efi_boot_name" || {
+    hint="./build-uki.sh (./index.js -b)"
+    [ "$arch" = x86_64 ] && hint="$hint or ./hello/build-hello.sh"
+    echo "error: build stage: no $arch EFI payload vda/EFI/BOOT/$efi_boot_name yet; run $hint first" >&2
     exit 1
 }
 
@@ -13,7 +17,7 @@ test -s vda/EFI/BOOT/BOOTX64.EFI || {
 # it into a GPT disk.  No mount, loop device, or root privilege is required.
 for required_tool in parted mkfs.fat mmd mcopy; do
     command -v "$required_tool" >/dev/null || {
-        echo "error: build stage needs $required_tool; run inside PRoot, see README section 0" >&2
+        echo "error: build stage needs $required_tool; run inside PRoot or with ./index.js --docker, see README Build environment" >&2
         exit 1
     }
 done
@@ -29,7 +33,7 @@ esp_sectors=$((esp_end - esp_start + 1))
 truncate -s $((esp_sectors * 512)) "$temporary_esp"
 mkfs.fat -F 32 -h "$esp_start" -n EFIBOOT "$temporary_esp" >/dev/null
 mmd -i "$temporary_esp" ::/EFI ::/EFI/BOOT
-mcopy -i "$temporary_esp" vda/EFI/BOOT/BOOTX64.EFI ::/EFI/BOOT/BOOTX64.EFI
+mcopy -i "$temporary_esp" "vda/EFI/BOOT/$efi_boot_name" "::/EFI/BOOT/$efi_boot_name"
 
 rm -f vda.img
 truncate -s $((disk_sectors * 512)) vda.img
@@ -41,4 +45,4 @@ dd if="$temporary_esp" of=vda.img bs=512 \
     seek="$esp_start" count="$esp_sectors" \
     conv=notrunc,sparse status=none
 
-echo "Packed vda/EFI/BOOT/BOOTX64.EFI into vda.img"
+echo "Packed vda/EFI/BOOT/$efi_boot_name into vda.img"