buninu-linux 0.5.1 → 0.7.0

package/initramfs/lib/fbdev.js

@@ -355,8 +355,12 @@ const setConsoleSwitchMode = (consoleDevice, mode) => {
 // when it comes back (answered with VT_ACKACQ), at which point `onAcquire`
 // runs so the caller can repaint what fbcon left on the screen. Returns a
 // function that puts the console back into automatic switching.
-export const watchConsoleSwitches = (consoleDevice, onAcquire) => {
+export const watchConsoleSwitches = (consoleDevice, callbacks) => {
+  // Keep the original (console, onAcquire) public form working.
+  const onRelease = typeof callbacks === "function" ? () => {} : callbacks.onRelease;
+  const onAcquire = typeof callbacks === "function" ? callbacks : callbacks.onAcquire;
   const release = () => {
+    try { onRelease(); } catch {}
     try { ioctlValue(consoleDevice.fd, VT_RELDISP, 1, "VT_RELDISP"); } catch {}
   };
   const acquire = () => {
@@ -429,6 +433,7 @@ const defaultTriangle = (display) => [
 // before text mode returns, such as putting a keyboard back into cooked mode.
 export const runGraphics = async (draw, {
   device = "/dev/fb0", console: consolePaths, switchConsole = true,
+  prepareConsole = null,
 } = {}) => {
   const display = openFramebuffer(device);
   let consoleDevice;
@@ -442,6 +447,7 @@ export const runGraphics = async (draw, {
   let previousConsole = null;
   let unwatch = null;
   const restoreCallbacks = [];
+  const releaseCallbacks = [];
   const acquireCallbacks = [];
   const restore = () => {
     while (restoreCallbacks.length) {
@@ -470,6 +476,10 @@ export const runGraphics = async (draw, {
   for (const [signal, handler] of signalHandlers) process.on(signal, handler);
   process.on("exit", restore);
   try {
+    if (prepareConsole) {
+      const cleanup = await prepareConsole(consoleDevice);
+      if (typeof cleanup === "function") restoreCallbacks.push(cleanup);
+    }
     const target = switchConsole ? consoleNumber(consoleDevice.path) : null;
     if (target !== null) {
       const active = activeConsole(consoleDevice);
@@ -480,22 +490,35 @@ export const runGraphics = async (draw, {
     }
     setConsoleGraphics(consoleDevice);
     graphics = true;
+    // An async draw callback runs synchronously until its first await.  Start
+    // it before enabling VT_PROCESS so it can register release/acquire hooks;
+    // otherwise a switch in that small window could be acknowledged without
+    // giving the renderer a chance to stop.
+    const drawing = draw(display, {
+      console: consoleDevice,
+      onRestore: (callback) => { restoreCallbacks.push(callback); },
+      onRelease: (callback) => { releaseCallbacks.push(callback); },
+      onAcquire: (callback) => { acquireCallbacks.push(callback); },
+    });
     if (switchConsole) {
       try {
-        unwatch = watchConsoleSwitches(consoleDevice, () => {
-          for (const callback of acquireCallbacks) {
-            try { callback(); } catch {}
-          }
+        unwatch = watchConsoleSwitches(consoleDevice, {
+          onRelease: () => {
+            for (const callback of releaseCallbacks) {
+              try { callback(); } catch {}
+            }
+          },
+          onAcquire: () => {
+            for (const callback of acquireCallbacks) {
+              try { callback(); } catch {}
+            }
+          },
         });
       } catch {
         // Not a virtual console (or no permission): switches stay automatic.
       }
     }
-    return await draw(display, {
-      console: consoleDevice,
-      onRestore: (callback) => { restoreCallbacks.push(callback); },
-      onAcquire: (callback) => { acquireCallbacks.push(callback); },
-    });
+    return await drawing;
   } finally {
     restore();
     process.off("exit", restore);

package/initramfs/usr/share/doc/buninu-linux/bunterm.md

@@ -7,8 +7,9 @@ box drawing and kitty graphics protocol images — no X11, Wayland or GPU.
 
 ```sh
 bunterm                      # run /bin/sh on the console you are on
-bunterm /dev/tty1            # use virtual console 1 for graphics and keys
-bunterm --font-size 20
+bunterm 2                    # start a detached bunterm on /dev/tty2
+bunterm /dev/tty1            # the full virtual-console spelling also works
+bunterm -s 20                # short for --font-size 20
 bunterm -e bun /buninu/apps/jsmdcui/src/index.js --demo
 bunterm --no-mouse          # keyboard only
 bunterm -h
@@ -19,13 +20,21 @@ The program's `TERM` is `xterm-256color`, `COLORTERM=truecolor`,
 Markdown images without `--kitty`). When it exits, the console returns to
 text mode and `bunterm` exits with its status.
 
+Every live session has a canonical `/bin/bunterm /dev/ttyN ...` command line.
+When no console is named, the currently active VT is used in the foreground.
+Naming a different VT starts bunterm as a detached session and returns
+immediately to the calling shell. Only one bunterm may control a given VT;
+ownership is
+identified from the process task name and its open console descriptor under
+`/proc`, so it disappears automatically when the process exits.
+
 ## Options
 
 | Option | Meaning |
 | --- | --- |
-| `/dev/ttyN` | The virtual console to use for graphics and the keyboard. If another console is on screen, the display switches to this one first and back when `bunterm` exits. Without it the process's own console and stdin are used, so run it from a VT (not a serial line or a PTY). |
+| `N`, `/dev/ttyN` | The virtual console to use for graphics and the keyboard; for example, `2` means `/dev/tty2`. Naming a VT other than the active one starts a detached bunterm there, switches the display to it, and immediately returns control to the calling shell. Without this argument, bunterm uses the active VT in the foreground. |
 | `-e command [argument...]` | The program to run; everything after `-e` belongs to it. Default `/bin/sh`. |
-| `--font-size N` | Font size in pixels (default 16). The cell is 0.6 × N wide and 1.16 × N tall with DejaVu Sans Mono, so 1024×768 at 16 px gives 106 × 41 cells. |
+| `-s N`, `--font-size N` | Font size in pixels (default 16). The cell is 0.6 × N wide and 1.16 × N tall with DejaVu Sans Mono, so 1024×768 at 16 px gives 106 × 41 cells. |
 | `--line-height F` | Multiplies the cell height (default 1). |
 | `--fb /dev/fbN` | The framebuffer device (default `/dev/fb0`). |
 | `--no-blink` | A steady cursor. |
@@ -57,7 +66,11 @@ text mode and `bunterm` exits with its status.
 
 The console stays in the kernel's translated keyboard mode, so
 `Ctrl-Alt-F2` and friends still switch consoles; coming back repaints the
-screen. A few console-specific
+screen. While its VT is inactive, bunterm continues consuming PTY output and
+updating its scrollback and kitty images, but neither writes the framebuffer
+nor forwards global `/dev/input` mouse events. This allows separate bunterm
+processes on `/dev/tty1`, `/dev/tty2`, and so on to hand the display back and
+forth through the normal Linux VT switch. A few console-specific
 sequences are rewritten to xterm's (`F1`–`F5`, `Home`, `End`), and arrow keys
 follow the program's application cursor mode.
 
@@ -80,7 +93,9 @@ hidden while it is scrolled out of view.
 `/dev/input` and never loads the mouse module.
 
 `init.js` loads `evdev` and `psmouse` at boot, so a PS/2 mouse — which is
-what QEMU's q35 machine and most PCs present — has a device node ready. A USB
+what QEMU's q35 machine and most PCs present — has a device node ready. The
+aarch64 image loads `virtio_input` in place of `psmouse`, for QEMU's
+`virtio-tablet-pci` and `virtio-keyboard-pci`. A USB
 mouse also needs the `usbhid` stack, which a `--real` image carries and
 `cfg.all` loads. The pointer follows relative devices (a mouse) and absolute
 ones (a tablet or touchscreen) alike; a device that cannot be opened is
@@ -91,6 +106,8 @@ reported and the session continues without it.
 - Needs a framebuffer: `linux-lts` has one built in, while the default
   `linux-virt` builds it as modules the image does not ship, so build with
   `--linux-lts` or `--real` (efifb/simpledrm from UEFI).
+- The aarch64 image has no framebuffer yet: `run-qemu.sh` gives QEMU's
+  `virt` machine no display device, so there is no `/dev/fb0` to draw on.
 - No selection, and no keyboard way to scroll back: the wheel is it. The
   buffer keeps 1000 lines. A program that does not enable mouse reporting
   sees no clicks — the arrow still moves, so the pointer is visibly alive.
@@ -100,7 +117,8 @@ reported and the session continues without it.
 - Kitty images are drawn above text; `z` ordering below text and animation
   frames are not implemented, and file transmission (`t=f`/`t=t`) works only
   for files under `/tmp`, `/dev/shm` or `$TMPDIR`.
-- One framebuffer, one session. For panes and tabs run `jsmdcui` inside it.
+- One bunterm per virtual console may use the framebuffer; only the active VT
+  draws. For panes and tabs within one VT, run `jsmdcui` inside it.
 
 ## See also
 

package/initramfs/usr/share/doc/buninu-linux/fbdev.md

@@ -84,7 +84,7 @@ than an X11 `Display`. Colours are `{ r, g, b, a }` objects.
 | `openConsole`, `setConsoleGraphics`, `setConsoleText` | Explicit Linux virtual-console control for callers that need it. |
 | `activeConsole(console)`, `activateConsole(console, n)`, `consoleNumber(path)` | `VT_GETSTATE` / `VT_ACTIVATE` + `VT_WAITACTIVE`, and the number in a `/dev/ttyN` path. |
 | `watchConsoleSwitches(console, onAcquire)` | `VT_SETMODE` with `VT_PROCESS`: answers the kernel's switch-away and switch-back signals and calls `onAcquire` when the display returns. Returns a function restoring automatic switching. |
-| `runGraphics(draw, { device, console, switchConsole }?)` | Open the framebuffer, put the console in graphics mode, run `await draw(display, { console, onRestore, onAcquire })`, and restore text mode however the call ends (return, throw, `process.exit()`, `SIGHUP`/`SIGINT`/`SIGQUIT`/`SIGTERM`). `console` lists console devices to try, such as `["/dev/tty1"]`; when the one opened is a `/dev/ttyN` other than the console on screen, the display is switched to it first and back afterwards (`switchConsole: false` disables this). Console switches with Ctrl-Alt-Fn keep working; `onAcquire(callback)` runs when the display comes back so the caller can repaint, and `onRestore(callback)` registers cleanup to run before text mode returns. |
+| `runGraphics(draw, { device, console, switchConsole, prepareConsole }?)` | Open the framebuffer, optionally call `await prepareConsole(console)`, put the console in graphics mode, run `await draw(display, { console, onRestore, onRelease, onAcquire })`, and restore text mode however the call ends (return, throw, `process.exit()`, `SIGHUP`/`SIGINT`/`SIGQUIT`/`SIGTERM`). `console` lists console devices to try, such as `["/dev/tty1"]`; when the one opened is a `/dev/ttyN` other than the console on screen, the display is switched to it first and back afterwards (`switchConsole: false` disables this). Console switches with Ctrl-Alt-Fn keep working: `onRelease(callback)` runs before the switch is acknowledged so drawing can stop, `onAcquire(callback)` runs when the display comes back, and `onRestore(callback)` registers cleanup to run before text mode returns. A cleanup function returned by `prepareConsole` is registered the same way. |
 | `runDemo({ polygons, device }?)` | Run the CLI demo through `runGraphics()`. Each item in `polygons` is drawn separately. |
 
 The module supports 16-, 24-, and 32-bit packed-pixel framebuffers and uses

package/initramfs/usr/share/doc/buninu-linux/tar.md

@@ -28,6 +28,8 @@ Use `-` as ARCHIVE to read from standard input or write to standard output.
 | `-z`, `--gzip` | Create gzip-compressed tar, or explicitly identify gzip input. |
 | `--zstd` | Create or read a zstd-compressed tar. A `.zst` or `.tzst` input is also detected by name. |
 | `-v` | Print names while creating/extracting; with `-t`, also show each member's size, modification time, kind and link target. |
+| `-o`, `--no-same-owner`, `--no-same-permissions`, `--overwrite` | GNU tar compatibility for extraction; these already match Bun.Archive's behaviour. |
+| `--exclude=PATTERN` | Accepted for js-udocker compatibility. Device nodes are not extracted and js-udocker removes whiteout files separately. |
 
 Short options can be combined, for example `-xzvf` or `-czf`.
 For the traditional first option word, the leading hyphen is optional, so

package/initramfs/usr/share/licenses/README.md

@@ -0,0 +1,4 @@
+# Licenses in the built image
+
+The packaging step copies the project `LICENSE`, `NOTICE.md`, and third-party
+`LICENSES/` directory here.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "buninu-linux",
-  "version": "0.5.1",
+  "version": "0.7.0",
   "description": "A Linux distribution running Bun as PID 1 with the Buninu userspace.",
   "type": "module",
   "main": "./index.js",
@@ -13,7 +13,7 @@
     "type": "git",
     "url": "git+https://github.com/jjtseng93/buninu-linux.git"
   },
-  "homepage": "https://github.com/jjtseng93/buninu-linux#readme",
+  "homepage": "https://buninu.org",
   "bugs": {
     "url": "https://github.com/jjtseng93/buninu-linux/issues"
   },

package/run-qemu.sh

@@ -2,19 +2,68 @@
 
 cd "$(dirname "$0")"
 
-test -f vda.img || ./build-image.sh
-
-if [ -z "$PREFIX" ] ; then
-  PREFIX=/usr
+# The guest is whatever build-uki.sh last put in vda/EFI/BOOT (it leaves only
+# one architecture there), unless BUNINU_ARCH (index.js --arch) names one.
+if [ -z "$BUNINU_ARCH" ] && [ -f vda/EFI/BOOT/BOOTAA64.EFI ]; then
+    BUNINU_ARCH=aarch64
 fi
+. ./scripts/arch.sh
+
+test -f vda.img || ./build-image.sh || exit 1
+test -f "vda/EFI/BOOT/$efi_boot_name" || {
+    echo "error: vda.img holds no $arch UKI; build one with ./index.js -b --arch $arch" >&2
+    exit 1
+}
+
+qemu="qemu-system-$arch"
+command -v "$qemu" >/dev/null || {
+    echo "error: $qemu not found (macOS: brew install qemu; Debian: apt install qemu-system)" >&2
+    exit 1
+}
 
-ovmf_filepath="$PREFIX"/share/qemu/edk2-x86_64-code.fd
+case $arch in
+    x86_64) machine=q35 distro_firmware=/usr/share/OVMF/OVMF_CODE_4M.fd ;;
+    aarch64) machine=virt distro_firmware=/usr/share/AAVMF/AAVMF_CODE.fd ;;
+esac
+
+# UEFI firmware: OVMF_FILE if set; then the edk2 build QEMU ships next to its
+# own binary (Termux's $PREFIX/share/qemu, Homebrew's share/qemu, ...); then
+# the distribution packages (Debian ovmf / qemu-efi-aarch64).
+qemu_share="$(dirname "$(command -v "$qemu")")/../share/qemu"
+ovmf_filepath=
+for candidate in "$OVMF_FILE" "$distro_firmware" "$qemu_share/edk2-$arch-code.fd" \
+    "/usr/share/qemu/edk2-$arch-code.fd"; do
+    if [ -n "$candidate" ] && [ -f "$candidate" ]; then
+        ovmf_filepath=$candidate
+        break
+    fi
+done
+test -n "$ovmf_filepath" || {
+    echo "error: no $arch UEFI firmware found; set OVMF_FILE to an edk2-$arch-code.fd" >&2
+    exit 1
+}
 
-if [ -f /usr/share/OVMF/OVMF_CODE_4M.fd ] ; then
-  ovmf_filepath=/usr/share/OVMF/OVMF_CODE_4M.fd
-elif [ -f "$OVMF_FILE" ] ; then
-  ovmf_filepath=$OVMF_FILE
+# Hardware acceleration needs the guest to match the host CPU: KVM on Linux,
+# Hypervisor.framework on macOS (Apple Silicon runs the aarch64 guest natively,
+# an Intel Mac the x86_64 one). Anything else, such as the x86_64 guest on
+# Apple Silicon or on an Android phone, is emulated with TCG. ACCEL overrides
+# the choice, e.g. ACCEL=tcg to rule acceleration out while debugging.
+case "$(uname -m)" in
+    arm64 | aarch64) host_arch=aarch64 ;;
+    *) host_arch=$(uname -m) ;;
+esac
+if [ -z "$ACCEL" ]; then
+    ACCEL=tcg
+    if [ "$host_arch" = "$arch" ]; then
+        case "$(uname -s)" in
+            Linux) [ -r /dev/kvm ] && [ -w /dev/kvm ] && ACCEL=kvm ;;
+            Darwin) [ "$(sysctl -n kern.hv_support 2>/dev/null)" = 1 ] && ACCEL=hvf ;;
+        esac
+    fi
 fi
+# TCG emulates every feature it knows; KVM and HVF pass the host CPU through.
+if [ "$ACCEL" = tcg ]; then cpu=max; else cpu=host; fi
+echo "run-qemu.sh: $arch guest on $machine, accel=$ACCEL, firmware $ovmf_filepath" >&2
 
 # User-mode networking is NAT: the guest can reach out, nothing reaches in
 # unless a port is forwarded. PORTS lists them, space-separated, as
@@ -31,9 +80,9 @@ for port in ${PORTS:-}; do
     nic="$nic,hostfwd=tcp:127.0.0.1:$host-:$guest"
 done
 
-exec qemu-system-x86_64 \
-    -machine q35,accel=tcg \
-    -cpu max \
+exec "$qemu" \
+    -machine "$machine,accel=$ACCEL" \
+    -cpu "$cpu" \
     -m 1G \
     -drive if=pflash,format=raw,readonly=on,file="$ovmf_filepath" \
     -drive if=virtio,format=raw,file=vda.img \

package/scripts/arch.sh

@@ -0,0 +1,113 @@
+# Sourced by the fetch, build and run scripts; not executable on its own.
+#
+# Everything that differs between the two guest architectures lives here:
+# the pinned packages and their SHA-256, the file names inside them, the EFI
+# removable-media name, the PE-aware objcopy that assembles the UKI and the
+# serial console. BUNINU_ARCH (index.js --arch) picks one; x86_64 is the
+# default. LINUX_FLAVOR (virt or lts) and REAL_MACHINE are read here too.
+#
+# Fetched and extracted files are kept per architecture, so both guests can
+# be built from one checkout without refetching:
+#
+#   downloads/<arch>/  the pinned archives (both repos use the same names)
+#   kernel/<arch>/     vmlinuz-<flavor> and the UKI stub
+#   native/<arch>/     bun, musl, libgcc/libstdc++ and kernel modules;
+#                      scripts/pack-initramfs.sh lays it over initramfs/
+
+case "${BUNINU_ARCH:-x86_64}" in
+    x86_64 | amd64 | x64) arch=x86_64 ;;
+    aarch64 | arm64) arch=aarch64 ;;
+    *)
+        echo "error: unsupported BUNINU_ARCH=$BUNINU_ARCH (use x86_64 or aarch64)" >&2
+        exit 1
+        ;;
+esac
+
+linux_flavor=${LINUX_FLAVOR:-virt}
+case $linux_flavor in
+    virt | lts) ;;
+    *)
+        echo "error: unsupported LINUX_FLAVOR=$linux_flavor (use virt or lts)" >&2
+        exit 1
+        ;;
+esac
+
+if [ "${REAL_MACHINE:-}" = 1 ] && [ "$arch" != x86_64 ]; then
+    echo "error: --real images are x86_64 only; its module set is PC hardware" >&2
+    exit 1
+fi
+
+# The Alpine repository keeps only the newest build of a package, so a pin
+# stops downloading when Alpine bumps it; the hashes below then fail loudly
+# rather than silently taking the new build. ALPINE_MIRROR swaps the host for
+# a closer mirror; the SHA-256 check is the same either way.
+alpine_mirror=${ALPINE_MIRROR:-https://dl-cdn.alpinelinux.org/alpine}
+alpine_base="$alpine_mirror/v3.24/main/$arch"
+
+kernel_version=6.18.53
+kernel_release="$kernel_version-0-$linux_flavor"
+linux_package="linux-$linux_flavor-$kernel_version-r0.apk"
+musl_package=musl-1.2.6-r2.apk
+stub_package=systemd-efistub-260.2-r0.apk
+libstdcpp_package=libstdc++-15.2.0-r5.apk
+libgcc_package=libgcc-15.2.0-r5.apk
+bun_version=1.4.2
+
+downloads_dir="downloads/$arch"
+kernel_dir="kernel/$arch"
+kernel_image="$kernel_dir/vmlinuz-$linux_flavor"
+native_dir="native/$arch"
+modules_root="$native_dir/lib/modules/$kernel_release"
+musl_loader="ld-musl-$arch.so.1"
+musl_libc="libc.musl-$arch.so.1"
+
+case $arch in
+    x86_64)
+        linux_virt_sha256=cad859cc46342e18002621fdde166bf2cd520dfec5e781d241de7d13e53970d6
+        linux_lts_sha256=8e3cfdd1d98e0e70c2e70a8c299ed3cd1e0939d60ad7bbd1da1cf241d794490b
+        musl_sha256=573712e2f49c15bfc20a2699f204acdfc74c772722b15e7353d768057fae0e71
+        stub_sha256=8e64a5a3afee5f930e6e6716be726dc6d405530ac7f8fa5be6251dae68671ec9
+        libstdcpp_sha256=14c987b556f5385a5db18376e788c75f37d85321b8dc1920d926ea7daac1d6f6
+        libgcc_sha256=393dcd32629f06d7d85409c272d142d0c082772d10b87ef55ee82f47de3be637
+        # Bun ships one x64 musl build; -baseline is an alias (NOTICE.md).
+        bun_build=bun-linux-x64-musl-baseline
+        bun_sha256=76e1db84e98f22f78de0a87e309bfbbf297732847f9720db36750646c85c8c18
+        efi_stub=linuxx64.efi.stub
+        efi_boot_name=BOOTX64.EFI
+        uki_objcopy=x86_64-w64-mingw32-objcopy
+        uki_objdump=x86_64-w64-mingw32-objdump
+        uki_binutils_package=binutils-mingw-w64-x86-64
+        # COM1 on q35 and on PCs.
+        serial_console=ttyS0
+        serial_major=4
+        ;;
+    aarch64)
+        linux_virt_sha256=fea61b7fd5e72e626d771f9798df56c83db658d0e221044f06fc28aacf5a118b
+        linux_lts_sha256=46885041022ea11afa1e07c40199c74146bf72d362368a844338af0c162e365c
+        musl_sha256=5e9674b7f41152fe2119093b5cb4c13eaaadb19c2d5422b2d7267913e663ee6e
+        stub_sha256=a1823d2d7082db555d528f82c1809f276c818aeb5b40f198f4565f104e055c38
+        libstdcpp_sha256=2302e766d4e4926038ec166ecb85837ee884576115236ddb565e3a5fca4a11d7
+        libgcc_sha256=369aaa6e9d099a737bad6dd3e6c2fe7bb1547ca26d22b94ee0411228f709b403
+        bun_build=bun-linux-aarch64-musl
+        bun_sha256=71760b6c8ea30623b81a4907cb815d48e2ea266f2e73e751534a44a0607950df
+        efi_stub=linuxaa64.efi.stub
+        efi_boot_name=BOOTAA64.EFI
+        # The aarch64 ELF binutils also read and write pei-aarch64-little:
+        # native binutils on an arm64 Debian, the cross package on amd64.
+        uki_objcopy=aarch64-linux-gnu-objcopy
+        uki_objdump=aarch64-linux-gnu-objdump
+        uki_binutils_package=binutils-aarch64-linux-gnu
+        # The PL011 UART of QEMU's virt machine.
+        serial_console=ttyAMA0
+        serial_major=204
+        ;;
+esac
+
+if [ "$linux_flavor" = lts ]; then
+    linux_sha256=$linux_lts_sha256
+else
+    linux_sha256=$linux_virt_sha256
+fi
+
+bun_zip="$bun_build-$bun_version.zip"
+bun_url="https://github.com/oven-sh/bun/releases/download/bun-v$bun_version/$bun_build.zip"

package/scripts/fetch.sh

@@ -2,8 +2,9 @@
 #
 # fetch <url> <name> <sha256>
 #
-# Downloads to downloads/<name>, unless a file with that exact SHA-256 is
-# already sitting there. The hash is both the cache key and the integrity
+# Downloads to $downloads_dir/<name> (downloads/<arch>/, set by
+# scripts/arch.sh), unless a file with that exact SHA-256 is already sitting
+# there. The hash is both the cache key and the integrity
 # check, so there is no weaker "file exists" path: a truncated, stale or
 # tampered file fails the first comparison, gets fetched again, and still has
 # to pass the second one before any script extracts from it.
@@ -12,7 +13,7 @@
 # a version (which changes both the name and the hash) always refetches.
 fetch() {
     local url=$1 name=$2 sha=$3
-    local path="downloads/$name"
+    local path="$downloads_dir/$name"
 
     if [ -f "$path" ] && printf '%s  %s\n' "$sha" "$path" | sha256sum --check --status; then
         echo "cached $name"
@@ -20,6 +21,7 @@ fetch() {
     fi
 
     echo "fetch  $name"
+    mkdir -p "$downloads_dir"
     curl -fL "$url" -o "$path"
     # --quiet prints only failures; a mismatch exits non-zero under `set -e`.
     printf '%s  %s\n' "$sha" "$path" | sha256sum --check --quiet

package/scripts/pack-initramfs.sh

@@ -2,13 +2,30 @@
 set -euo pipefail
 
 cd "$(dirname "$0")/.."
+
+. ./scripts/arch.sh
+
+test -x "$native_dir/bin/bun" || {
+    echo "error: no $native_dir/bin/bun yet; run the fetch stage first (./index.js -f)" >&2
+    exit 1
+}
 mkdir -p build
 
 staging="$(mktemp -d "$PWD/.initramfs.XXXXXX")"
 archive="$(mktemp "$PWD/.initramfs.XXXXXX.cpio")"
 trap 'rm -rf "$staging"; rm -f "$archive"' EXIT
 
+# initramfs/ is the same for every architecture; native/<arch>/ adds bun, the
+# musl loader, the GCC runtime and the kernel modules on top of it.
+# A checkout fetched before native/ existed still has an x86_64 bun and its
+# modules under initramfs/; they are dropped rather than packed.
 cp -a --reflink=auto initramfs/. "$staging/"
+rm -rf "$staging/bin/bun" "$staging/lib/modules"
+cp -a --reflink=auto "$native_dir/." "$staging/"
+# Keep the project README canonical while making it available to
+# buninu-linux-help from the conventional installed-document path.
+cp README.md "$staging/usr/share/doc/buninu-linux/README.md"
+cp -a LICENSE NOTICE.md LICENSES "$staging/usr/share/licenses/"
 
 # fakeroot lets cpio record the character devices without real root. Nothing
 # has mounted devtmpfs when the kernel execs Bun as PID 1, so every device
@@ -20,10 +37,11 @@ cp -a --reflink=auto initramfs/. "$staging/"
 #            This is the one device that actually blocks booting Bun as PID 1.
 #
 # The rest are cheap to include and keep /dev usable if the devtmpfs mount in
-# init.js ever fails.
+# init.js ever fails. The serial port is ttyS0 (4, 64) on x86_64 and the
+# PL011 ttyAMA0 (204, 64) on aarch64.
 fakeroot-tcp -- sh -c '
     mknod -m 0600 "$1/dev/console" c 5 1
-    mknod -m 0620 "$1/dev/ttyS0" c 4 64
+    mknod -m 0620 "$1/dev/$3" c "$4" 64
     mknod -m 0666 "$1/dev/null" c 1 3
     mknod -m 0666 "$1/dev/zero" c 1 5
     mknod -m 0666 "$1/dev/random" c 1 8
@@ -34,8 +52,8 @@ fakeroot-tcp -- sh -c '
         | sort -z \
         | cpio --null --create --format=newc --owner=0:0 --reproducible 2>/dev/null \
         > "$2"
-' sh "$staging" "$archive"
+' sh "$staging" "$archive" "$serial_console" "$serial_major"
 
 gzip -9n < "$archive" > build/initramfs.cpio.gz
 
-echo "Built build/initramfs.cpio.gz"
+echo "Built build/initramfs.cpio.gz for $arch"

package/test/host/Dockerfile

@@ -0,0 +1,13 @@
+# The "ordinary Debian 13 machine" host-test.sh builds and boots the guests on:
+# the README's build packages for both guests, QEMU with OVMF and AAVMF, node
+# to run index.js, git to clone the checkout and expect to drive the serial
+# console. Built for linux/amd64 or linux/arm64, whichever host is simulated.
+FROM debian:13-slim
+RUN apt-get update && apt-get install -y --no-install-recommends \
+      binutils-mingw-w64-x86-64 binutils-aarch64-linux-gnu cpio curl dosfstools fakeroot mtools parted unzip \
+      ca-certificates git nodejs expect \
+      qemu-system-x86 ovmf qemu-system-arm qemu-efi-aarch64 \
+    && rm -rf /var/lib/apt/lists/*
+
+# parted asks udev to settle after writing a partition table; see ../../Dockerfile.
+RUN ln -s /bin/true /usr/local/bin/udevadm

package/test/host/boot-test.exp

@@ -0,0 +1,70 @@
+#!/usr/bin/expect -f
+# Boots vda.img with `node ./index.js -r --arch <arch>` and drives the serial
+# console: the REPL, the Buninu shell, eth0, PID 1, a tmpfs mount, a fetch from
+# inside the guest and poweroff. Each step waits for the output it expects, so
+# a hang or a wrong answer fails with a message instead of racing ahead.
+#
+# Usage: boot-test.exp <checkout> x86_64|aarch64 [boot timeout in seconds]
+
+set checkout [lindex $argv 0]
+set arch [lindex $argv 1]
+set boot_timeout [expr {[llength $argv] > 2 ? [lindex $argv 2] : 900}]
+switch -- $arch {
+    x86_64 { set js_arch x64 }
+    aarch64 { set js_arch arm64 }
+    default {
+        puts "usage: boot-test.exp <checkout> x86_64|aarch64 \[boot timeout\]"
+        exit 2
+    }
+}
+
+proc fail {message} {
+    puts "\n### FAIL: $message"
+    exit 1
+}
+
+# Sends one line to the guest, then waits for a regular expression in the
+# output. The patterns match what the command prints, not its echo.
+proc step {what line pattern} {
+    send -- "$line\r"
+    expect {
+        -re $pattern { puts "\n### ok: $what" }
+        timeout { fail "$what: no match for /$pattern/ within $::timeout s" }
+        eof { fail "$what: QEMU exited" }
+    }
+}
+
+cd $checkout
+set start [clock seconds]
+spawn node ./index.js -r --arch $arch
+
+set timeout $boot_timeout
+expect {
+    "bun-repl>" { puts "\n### ok: REPL after [expr {[clock seconds] - $start}] s" }
+    "Kernel panic" { fail "kernel panic before the REPL" }
+    timeout { fail "no REPL within $boot_timeout s" }
+    eof { fail "QEMU exited before the REPL" }
+}
+
+# bunmsh switches bracketed paste off (ESC[?2004l) before a command's output
+# and Bun colours the numbers it prints, so a line of output can carry escape
+# sequences around the text.
+set esc {(?:\x1b\[[0-9;?]*[a-zA-Z])*}
+
+set timeout 180
+step "process.arch is $js_arch" "process.arch" "'$js_arch'"
+step "Buninu shell" "start()" {\$ }
+step "uname reports $arch" "uname -a" "Linux \\(none\\) \[^\r\n\]* $arch"
+step "eth0 is 10.0.2.15" "ip -br addr" {eth0 +UP +10\.0\.2\.15/24}
+step "PID 1 is bun" "ps -eo pid,args" {\n +1 /bin/bun -e import}
+step "tmpfs mount" \
+    "mount -t tmpfs -o size=8M tmpfs /tmp/x --mkdir && echo hi > /tmp/x/f && cat /tmp/x/f && umount /tmp/x" \
+    "\n${esc}hi${esc}\r"
+step "fetch from the guest" \
+    {bun -e 'console.log((await fetch("http://example.com")).status)'} \
+    "\n${esc}200${esc}\r"
+step "poweroff" "poweroff" "reboot: Power down"
+expect {
+    eof { puts "\n### ok: QEMU exited, [expr {[clock seconds] - $start}] s in total" }
+    timeout { fail "QEMU still running after poweroff" }
+}

package/test/host/host-test.sh

@@ -0,0 +1,49 @@
+#!/usr/bin/env bash
+# Builds and boots both guests on a fresh Debian 13 host of either CPU, in
+# Docker:
+#
+#   test/host/host-test.sh [amd64|arm64]
+#
+# The platform defaults to this machine's own CPU; the other one runs
+# emulated and takes a few times longer. The container (./Dockerfile) has the
+# README's build packages and QEMU. It clones the committed HEAD of this
+# checkout, so uncommitted changes to the project are not tested, then builds
+# with the host toolchain rather than --docker and boots each guest through
+# boot-test.exp. The exit status is 0 only when every step passed.
+#
+#   GUESTS="aarch64"         which guests to test (default: x86_64 aarch64)
+#   BUILD_FLAGS=--linux-lts  extra flags for the build stage
+#   BOOT_TIMEOUT=900         seconds to wait for the REPL
+#   ALPINE_MIRROR=...        passed through to the fetch stage
+#
+# downloads/ is mounted read-only as a cache; running `./index.js -f --arch
+# <arch>` here first saves the container from downloading.
+set -euo pipefail
+
+cd "$(dirname "$0")/../.."
+
+case "${1:-$(uname -m)}" in
+    amd64 | x86_64) platform=amd64 ;;
+    arm64 | aarch64) platform=arm64 ;;
+    *)
+        echo "usage: $0 [amd64|arm64]" >&2
+        exit 2
+        ;;
+esac
+
+image="buninu-linux-hosttest:$platform"
+echo "### building $image (the first build takes a few minutes)"
+docker build --quiet --platform "linux/$platform" --tag "$image" test/host > /dev/null
+
+# A Linux host's KVM reaches the container too, so a guest that matches the
+# platform runs accelerated. Docker Desktop on macOS exposes no /dev/kvm.
+kvm_device=
+if [ -e /dev/kvm ]; then kvm_device=--device=/dev/kvm; fi
+
+mkdir -p downloads
+# $kvm_device is empty or a single word.
+exec docker run --rm --platform "linux/$platform" $kvm_device \
+    --mount "type=bind,src=$PWD,dst=/repo,readonly" \
+    --mount "type=bind,src=$PWD/downloads,dst=/cache,readonly" \
+    --env GUESTS --env BUILD_FLAGS --env BOOT_TIMEOUT --env ALPINE_MIRROR \
+    "$image" /repo/test/host/in-container.sh