buninu-linux 0.4.0 → 0.6.0

package/build-uki.sh

@@ -3,14 +3,12 @@ set -euo pipefail
 
 cd "$(dirname "$0")"
 
-linux_flavor=${LINUX_FLAVOR:-virt}
-kernel_release="6.18.52-0-$linux_flavor"
-kernel_image="kernel/vmlinuz-$linux_flavor"
+. ./scripts/arch.sh
 
-if [ ! -s "$kernel_image" ] || [ ! -s "initramfs/lib/modules/$kernel_release/modules.dep" ] || \
+if [ ! -s "$kernel_image" ] || [ ! -s "$kernel_dir/$efi_stub" ] || [ ! -s "$modules_root/modules.dep" ] || \
     { [ "${REAL_MACHINE:-}" = 1 ] && \
-    { [ ! -s "initramfs/lib/modules/$kernel_release/kernel/drivers/hid/usbhid/usbhid.ko" ] || \
-      [ ! -s "initramfs/lib/modules/$kernel_release/kernel/drivers/acpi/battery.ko" ]; }; }; then
+    { [ ! -s "$modules_root/kernel/drivers/hid/usbhid/usbhid.ko" ] || \
+      [ ! -s "$modules_root/kernel/drivers/acpi/battery.ko" ]; }; }; then
     ./fetch-alpine.sh
 fi
 ./scripts/pack-initramfs.sh
@@ -31,35 +29,53 @@ printf '%s\n' \
 # kernel does not care about the order of the parameters, so `rdinit=` goes
 # last and the tail of the line reads as the `bun -e ...` it turns into.
 #
-# ttyS0 is listed last so it, not tty0, is the console the kernel opens as the
-# init process's fd 0/1/2. `-display none` leaves tty0 with nowhere to go.
+# The serial port (ttyS0, or ttyAMA0 on aarch64) is listed last so it, not
+# tty0, is the console the kernel opens as the init process's fd 0/1/2.
+# `-display none` leaves tty0 with nowhere to go.
 if [ "${REAL_MACHINE:-}" = 1 ]; then
-    consoles="console=ttyS0,115200 console=tty0 REAL_MACHINE=1"
+    consoles="console=$serial_console,115200 console=tty0 REAL_MACHINE=1"
 else
-    consoles="console=tty0 console=ttyS0,115200"
+    consoles="console=tty0 console=$serial_console,115200"
 fi
 printf '%s' "$consoles panic=0 PATH=/bin KERNEL_RELEASE=$kernel_release rdinit=/bin/bun -- -e import('/init.js')" > build/cmdline
 
-if command -v x86_64-w64-mingw32-objcopy >/dev/null; then
-    objcopy_command=x86_64-w64-mingw32-objcopy
-    objdump_command=x86_64-w64-mingw32-objdump
-else
-    echo "error: build stage needs x86_64-w64-mingw32-objcopy (Debian binutils-mingw-w64-x86-64)" >&2
-    echo "run inside PRoot; see README section 0" >&2
+if ! command -v "$uki_objcopy" >/dev/null || ! command -v "$uki_objdump" >/dev/null; then
+    echo "error: build stage needs $uki_objcopy and $uki_objdump (Debian $uki_binutils_package)" >&2
+    echo "run inside PRoot or with ./index.js --docker; see README Build environment" >&2
     exit 1
 fi
 
-image_base_hex="$($objdump_command -p kernel/linuxx64.efi.stub \
-    | awk '$1 == "ImageBase" { print $2; exit }')"
-image_base=$((16#$image_base_hex))
-osrel_vma=$((image_base + 0x20000))
-cmdline_vma=$((image_base + 0x30000))
-linux_vma=$((image_base + 0x2000000))
-initrd_vma=$((image_base + 0x3000000))
+stub="$kernel_dir/$efi_stub"
+pe_header() { "$uki_objdump" -p "$stub" | awk -v key="$1" '$1 == key { print $2; exit }'; }
+align_up() { echo $(( ($1 + $2 - 1) / $2 * $2 )); }
+max() { echo $(( $1 > $2 ? $1 : $2 )); }
+
+# The conventional x86-64 UKI offsets from the image base: .osrel +0x20000,
+# .cmdline +0x30000, .linux +0x2000000, .initrd +0x3000000. The stub's own
+# sections (SizeOfImage) and the kernel are measured rather than assumed, so
+# a larger stub or a kernel of 16 MiB or more moves the later sections up
+# instead of overlapping them. The x86_64 stub and both kernels fit the
+# conventional layout; the aarch64 stub ends at +0x38000, which puts .osrel
+# and .cmdline at +0x40000 and +0x50000 there.
+image_base=$((16#$(pe_header ImageBase)))
+stub_size=$((16#$(pe_header SizeOfImage)))
+kernel_size=$(wc -c < "$kernel_image")
+osrel_offset=$(max 0x20000 "$(align_up "$stub_size" 0x10000)")
+cmdline_offset=$((osrel_offset + 0x10000))
+linux_offset=$(max 0x2000000 "$(align_up $((cmdline_offset + 0x10000)) 0x1000000)")
+initrd_offset=$(max 0x3000000 "$(align_up $((linux_offset + kernel_size)) 0x1000000)")
+osrel_vma=$((image_base + osrel_offset))
+cmdline_vma=$((image_base + cmdline_offset))
+linux_vma=$((image_base + linux_offset))
+initrd_vma=$((image_base + initrd_offset))
+
+# Only this architecture's removable-media name may remain: firmware of the
+# other architecture ignores it, but run-qemu.sh reads the guest from it.
+for efi in vda/EFI/BOOT/*.EFI; do
+    [ "$efi" = "vda/EFI/BOOT/$efi_boot_name" ] || rm -f "$efi"
+done
 
-# These are the conventional non-overlapping VMAs used for x86-64 UKIs.
-# Both supported Alpine kernels are below 16 MiB, so .linux ends before .initrd.
-"$objcopy_command" \
+"$uki_objcopy" \
     --add-section .osrel=build/os-release \
     --change-section-vma .osrel="$osrel_vma" \
     --set-section-flags .osrel=contents,alloc,load,readonly,data \
@@ -72,6 +88,6 @@ initrd_vma=$((image_base + 0x3000000))
     --add-section .initrd=build/initramfs.cpio.gz \
     --change-section-vma .initrd="$initrd_vma" \
     --set-section-flags .initrd=contents,alloc,load,readonly,data \
-    kernel/linuxx64.efi.stub vda/EFI/BOOT/BOOTX64.EFI
+    "$stub" "vda/EFI/BOOT/$efi_boot_name"
 
-echo "Built UKI with Alpine linux-$linux_flavor at vda/EFI/BOOT/BOOTX64.EFI"
+echo "Built $arch UKI with Alpine linux-$linux_flavor at vda/EFI/BOOT/$efi_boot_name"

package/fetch-alpine.sh

@@ -3,47 +3,34 @@ set -euo pipefail
 
 cd "$(dirname "$0")"
 
-base=https://dl-cdn.alpinelinux.org/alpine/v3.24/main/x86_64
-linux_flavor=${LINUX_FLAVOR:-virt}
-linux_package="linux-$linux_flavor-6.18.52-r0.apk"
-musl_package=musl-1.2.6-r2.apk
-stub_package=systemd-efistub-260.2-r0.apk
-if [ "$linux_flavor" = lts ]; then
-    linux_sha256=bd81f00522a7c7deb96886811a087c453d48530c0c8f742412ad73e24236037c
-else
-    linux_sha256=dff0c365a6d6c0fd015175af08dca0c39048fa39df6ef3150a7ea88d2cfdfa4f
-fi
-
-musl_sha256=573712e2f49c15bfc20a2699f204acdfc74c772722b15e7353d768057fae0e71
-stub_sha256=8e64a5a3afee5f930e6e6716be726dc6d405530ac7f8fa5be6251dae68671ec9
+. ./scripts/arch.sh
 
-kernel_release="6.18.52-0-$linux_flavor"
-
-modules_root="initramfs/lib/modules/$kernel_release"
-mkdir -p downloads kernel initramfs/lib "$modules_root"
+mkdir -p "$downloads_dir" "$kernel_dir" "$native_dir/lib" "$modules_root"
 
 . ./scripts/fetch.sh
 
-fetch "$base/$linux_package" "$linux_package" "$linux_sha256"
-fetch "$base/$musl_package" "$musl_package" "$musl_sha256"
-fetch "$base/$stub_package" "$stub_package" "$stub_sha256"
+fetch "$alpine_base/$linux_package" "$linux_package" "$linux_sha256"
+fetch "$alpine_base/$musl_package" "$musl_package" "$musl_sha256"
+fetch "$alpine_base/$stub_package" "$stub_package" "$stub_sha256"
 
-extract() { tar --warning=no-unknown-keyword -xOf "downloads/$1" "$2"; }
+extract() { tar --warning=no-unknown-keyword -xOf "$downloads_dir/$1" "$2"; }
 
-extract "$linux_package" "boot/vmlinuz-$linux_flavor" > "kernel/vmlinuz-$linux_flavor"
-extract "$musl_package" lib/ld-musl-x86_64.so.1 > initramfs/lib/ld-musl-x86_64.so.1
-extract "$stub_package" usr/lib/systemd/boot/efi/linuxx64.efi.stub > kernel/linuxx64.efi.stub
+# On aarch64 vmlinuz is an EFI zboot image: a PE executable that inflates
+# the kernel itself, so the stub can start it exactly like the x86_64 bzImage.
+extract "$linux_package" "boot/vmlinuz-$linux_flavor" > "$kernel_image"
+extract "$musl_package" "lib/$musl_loader" > "$native_dir/lib/$musl_loader"
+extract "$stub_package" "usr/lib/systemd/boot/efi/$efi_stub" > "$kernel_dir/$efi_stub"
 
 # Kernel modules. The package's modules.dep says what each one needs, so a
 # module is requested by name and its dependencies come along: on linux-lts
-# virtio_net pulls in virtio, virtio_ring and virtio_pci, which linux-virt
-# has built in. The initramfs gets a modules.dep trimmed to the shipped set,
+# virtio_net pulls in virtio and virtio_ring, which linux-virt has built in. The initramfs gets a modules.dep trimmed to the shipped set,
 # the fs-* lines of modules.alias and modules.builtin; /lib/modprobe.js reads
 # those three files.
 depfile="$(mktemp)"
 selected="$(mktemp)"
 trap 'rm -f "$depfile" "$selected" "$selected.names"' EXIT
 extract "$linux_package" "lib/modules/$kernel_release/modules.dep" > "$depfile"
+extract "$linux_package" "lib/modules/$kernel_release/modules.builtin" > "$modules_root/modules.builtin"
 
 select_module() {
     local name=$1 line path dep
@@ -58,14 +45,42 @@ select_module() {
     done
 }
 
-# Network: virtio-net for QEMU (init.js loads these at boot).
+# For modules one architecture or flavor builds in or leaves out: a built-in
+# one needs nothing, a missing one gets a note. aarch64 linux-virt has no
+# ext2.ko: it sets CONFIG_EXT4_USE_FOR_EXT2, and modules.alias maps fs-ext2 to
+# ext4, which is how /bin/mount looks the driver up.
+select_optional_module() {
+    if grep -qF -m1 -- "/$1.ko.gz:" "$depfile"; then
+        select_module "$1"
+    elif ! grep -q -- "/$1\.ko$" "$modules_root/modules.builtin"; then
+        echo "note: module $1 is not in $arch $linux_package; skipped" >&2
+    fi
+}
+
+# Network: virtio-net for QEMU (init.js loads these at boot). virtio_pci is
+# the PCI transport for every virtio device, disk included; linux-virt builds
+# it in, linux-lts has it as a module that nothing in modules.dep pulls in.
 for module in failover net_failover virtio_net; do select_module "$module"; done
+select_optional_module virtio_pci
 # Storage: what /bin/mount loads on demand. ext4 brings jbd2, mbcache and
 # crc16; FAT, exFAT and NTFS ask the kernel for the NLS tables at mount
 # time, which has no /sbin/modprobe to answer, so mount preloads them.
-for module in virtio_blk ext4 ext2 vfat exfat ntfs3 nls_utf8 nls_cp437 nls_iso8859-1; do
+for module in virtio_blk ext4 vfat exfat ntfs3 nls_utf8 nls_cp437 nls_iso8859-1; do
     select_module "$module"
 done
+select_optional_module ext2
+# Pointing devices for `bunterm --mouse`, which reads /dev/input/event*.
+# evdev is the character-device interface to the input layer; psmouse drives
+# the PS/2 mouse every PC and QEMU's q35 machine has. QEMU's aarch64 virt
+# machine has no PS/2 port; its keyboard and pointer are virtio-input. A USB
+# mouse needs the usbhid stack, which only the --real image carries. init.js
+# loads these at boot; nothing reads a pointer unless bunterm is asked to.
+select_module evdev
+if [ "$arch" = x86_64 ]; then
+    select_module psmouse
+else
+    select_module virtio_input
+fi
 
 if [ "${REAL_MACHINE:-}" = 1 ]; then
     # USB keyboard for the console; common storage paths (SATA/AHCI HDD and
@@ -108,8 +123,7 @@ extract "$linux_package" "lib/modules/$kernel_release/modules.alias" \
         $2 ~ /^fs-/ { print; next }
         $2 ~ /^(pci|usb|virtio):/ { m = $3; gsub("-", "_", m); if (m in shipped) print }
     ' > "$modules_root/modules.alias"
-extract "$linux_package" "lib/modules/$kernel_release/modules.builtin" > "$modules_root/modules.builtin"
 
-chmod 0755 initramfs/lib/ld-musl-x86_64.so.1
+chmod 0755 "$native_dir/lib/$musl_loader"
 
-echo "Fetched Alpine linux-$linux_flavor kernel, $(wc -l < "$selected") modules, musl, and the x64 UKI stub."
+echo "Fetched Alpine $arch linux-$linux_flavor kernel, $(wc -l < "$selected") modules, musl, and the $efi_stub UKI stub."

package/fetch-bun.sh

@@ -3,17 +3,10 @@ set -euo pipefail
 
 cd "$(dirname "$0")"
 
-bun_version=1.4.2
-alpine_base=https://dl-cdn.alpinelinux.org/alpine/v3.24/main/x86_64
-bun_url="https://github.com/oven-sh/bun/releases/download/bun-v${bun_version}/bun-linux-x64-musl-baseline.zip"
-bun_zip="bun-linux-x64-musl-baseline-${bun_version}.zip"
-libstdcpp_package=libstdc++-15.2.0-r5.apk
-libgcc_package=libgcc-15.2.0-r5.apk
-bun_sha256=76e1db84e98f22f78de0a87e309bfbbf297732847f9720db36750646c85c8c18
-libstdcpp_sha256=14c987b556f5385a5db18376e788c75f37d85321b8dc1920d926ea7daac1d6f6
-libgcc_sha256=393dcd32629f06d7d85409c272d142d0c082772d10b87ef55ee82f47de3be637
-
-mkdir -p downloads initramfs/bin initramfs/lib initramfs/dev initramfs/proc initramfs/sys initramfs/tmp
+. ./scripts/arch.sh
+
+mkdir -p "$downloads_dir" "$native_dir/bin" "$native_dir/lib" \
+  initramfs/dev initramfs/proc initramfs/sys initramfs/tmp
 
 . ./scripts/fetch.sh
 
@@ -21,21 +14,21 @@ fetch "$bun_url" "$bun_zip" "$bun_sha256"
 fetch "$alpine_base/$libstdcpp_package" "$libstdcpp_package" "$libstdcpp_sha256"
 fetch "$alpine_base/$libgcc_package" "$libgcc_package" "$libgcc_sha256"
 
-test -s initramfs/lib/ld-musl-x86_64.so.1 || {
+test -s "$native_dir/lib/$musl_loader" || {
   echo "error: fetch stage incomplete: run ./fetch-alpine.sh first (./index.js -f runs both)" >&2
   exit 1
 }
 
-unzip -p "downloads/$bun_zip" \
-  'bun-linux-x64-musl-baseline/bun' > initramfs/bin/bun
-tar --warning=no-unknown-keyword -xOf "downloads/$libstdcpp_package" \
-  usr/lib/libstdc++.so.6.0.34 > initramfs/lib/libstdc++.so.6
-tar --warning=no-unknown-keyword -xOf "downloads/$libgcc_package" \
-  usr/lib/libgcc_s.so.1 > initramfs/lib/libgcc_s.so.1
+unzip -p "$downloads_dir/$bun_zip" \
+  "$bun_build/bun" > "$native_dir/bin/bun"
+tar --warning=no-unknown-keyword -xOf "$downloads_dir/$libstdcpp_package" \
+  usr/lib/libstdc++.so.6.0.34 > "$native_dir/lib/libstdc++.so.6"
+tar --warning=no-unknown-keyword -xOf "$downloads_dir/$libgcc_package" \
+  usr/lib/libgcc_s.so.1 > "$native_dir/lib/libgcc_s.so.1"
 
 # Keep libc as a distinct inode from the active dynamic loader. Calling dlopen
 # on the loader inode itself deadlocks, while this physical copy is FFI-safe.
-cp initramfs/lib/ld-musl-x86_64.so.1 initramfs/lib/libc.musl-x86_64.so.1
-chmod 0755 initramfs/init.js initramfs/bin/bun initramfs/lib/*.so*
+cp "$native_dir/lib/$musl_loader" "$native_dir/lib/$musl_libc"
+chmod 0755 initramfs/init.js "$native_dir/bin/bun" "$native_dir"/lib/*.so*
 
-echo "Fetched Bun $bun_version and its x86_64 musl runtime into initramfs/."
+echo "Fetched Bun $bun_version and its $arch musl runtime into $native_dir/."

package/graphics.md

@@ -19,6 +19,7 @@ via Bun FFI.
  │   @xterm/headless Terminal ─ VT parser, screen buffer, attributes     │
  │   images.js ─ kitty placements as Skia images anchored to lines       │
  │   input.js ─ /dev/ttyN raw mode, console→xterm key sequences          │
+ │   mouse.js ─ /dev/input/event* pointer, unless --no-mouse             │
  │   renderer.js ─ cells → glyphs (fonts) or vectors (glyphs.js)         │
  └───────────────────────────────────────────────┬──────────────────────┘
                                                  │ Skia draw calls
@@ -130,6 +131,7 @@ Around those, `/lib/bunterm/` adds:
 | `glyphs.js` | Box drawing (U+2500–257F incl. double, dashed, rounded, mixed-weight), block elements and shades (U+2580–259F), Powerline (U+E0A0–E0BF) and legacy computing (U+1FB70–1FB97) drawn as Skia paths, so they meet seamlessly at any size. The shape tables are xterm.js's `CustomGlyphs.ts` (MIT); coordinates snap to pixel centres for crisp 1-px lines. |
 | `images.js` | Kitty placements: decodes PNG (`f=100`) with Skia or raw RGB/RGBA (`f=24/32`), with `Bun.Image` as a transcoder for other encodings; anchors each placement to an xterm marker so it scrolls with its line and disappears with it (on the alternate screen, where xterm.js issues no markers, to a fixed row that is dropped when that screen ends); sizes in cells (`c,r`) or from pixel size; crops (`x,y,w,h`), cell offsets (`X,Y`), `p=` placement ids, `a=d` deletion scopes, and the cursor move after a placement. |
 | `input.js` | Raw mode on the console (`TCGETS`/`TCSETS` through the shared libc binding) and translation of the kernel's "linux" key sequences to xterm's, honouring DECCKM. |
+| `mouse.js` | `/dev/input/event*` through the input layer: finds pointing devices by their sysfs capability bitmaps, decodes the 24-byte `input_event` records (relative deltas, absolute axes read with `EVIOCGABS`, buttons, wheel) and reports a pointer position per `EV_SYN`. Not loaded under `--no-mouse`; otherwise the session draws an arrow and hands each report to xterm.js's `CoreMouseService`, which decides what the program enabled and encodes it. A wheel notch the program is not asking for scrolls the viewport instead — `scrollLines()` on the normal screen, arrow keys on the alternate one. |
 | `terminal.js` | `createSession()` wires PTY → parser → emulator → renderer with a coalesced ~60 Hz frame timer and a serialized output queue, so a kitty packet always sees the cursor position left by the text before it. `runTerminal()` adds `runGraphics()` and the keyboard. |
 
 Manual: `bunterm --help` / `initramfs/usr/share/doc/buninu-linux/bunterm.md`.
@@ -150,7 +152,9 @@ Manual: `bunterm --help` / `initramfs/usr/share/doc/buninu-linux/bunterm.md`.
 4. `screen.flush()` finishes Skia's work and copies the wasm-heap frame into
    the `/dev/fb0` mapping.
 
-Keyboard bytes travel the other way: console → `input.js` → PTY. Terminal
+Keyboard bytes travel the other way: console → `input.js` → PTY, and with
+the mouse on, pointer reports go `/dev/input/event*` → `mouse.js` → the arrow on
+screen and xterm.js's `CoreMouseService` → PTY. Terminal
 replies (cursor position, device attributes, kitty acks) go from the
 emulator straight to the PTY.
 
@@ -204,7 +208,8 @@ through its transmit / `a=p` / `a=d` sequence exactly as in the browser.
 
 ## Not done yet
 
-- Mouse, selection and scrollback viewing in `bunterm`.
+- Selection and scrollback viewing in `bunterm` (the pointer itself works,
+  and `--no-mouse` turns it off).
 - Kitty `z < 0` (images behind text), animation frames, Unicode
   placeholders, and shared-memory transmission.
 - Text run shaping with ligatures for single-code-point cells (each cell is

package/index.js

@@ -8,28 +8,51 @@
 
 import pkg from "./package.json" with { type: "json" };
 import { spawnSync } from "node:child_process";
-import { accessSync, constants, copyFileSync, readFileSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { accessSync, constants, copyFileSync, existsSync, readFileSync } from "node:fs";
 import { delimiter, dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
 const rootDir = dirname(fileURLToPath(import.meta.url));
 const invocationDir = process.cwd();
 
+// Guest architectures. The names are Alpine's and the kernel's; the aliases
+// are what Go, Docker, Node and Apple call the same CPUs. scripts/arch.sh
+// holds everything else that differs between them.
+const architectures = {
+  x86_64: { aliases: ["amd64", "x64"], efi: "BOOTX64.EFI", binutils: "x86_64-w64-mingw32", apt: "binutils-mingw-w64-x86-64" },
+  aarch64: { aliases: ["arm64"], efi: "BOOTAA64.EFI", binutils: "aarch64-linux-gnu", apt: "binutils-aarch64-linux-gnu" },
+};
+
+function normalizeArch(name) {
+  for (const [arch, { aliases }] of Object.entries(architectures)) {
+    if (name === arch || aliases.includes(name)) return arch;
+  }
+  fail(`unknown architecture ${name} (use x86_64/amd64 or aarch64/arm64)`);
+}
+
+// What vda/EFI/BOOT holds decides the guest for a bare -r, as in run-qemu.sh.
+function builtArch() {
+  return existsSync(resolve(rootDir, "vda/EFI/BOOT", architectures.aarch64.efi)) ? "aarch64" : "x86_64";
+}
+
 // Pipeline order. Flags select stages; this array fixes the order they run in.
+// The fetch and build stages can run inside the Docker image from ./Dockerfile
+// (--docker, and always on macOS); run always uses the host's QEMU.
 const stages = [
   {
     flag: "fetch",
     short: "f",
     scripts: ["fetch-alpine.sh", "fetch-bun.sh"],
-    tools: ["curl", "unzip", "tar", "gzip", "sha256sum"],
+    tools: () => ["curl", "unzip", "tar", "gzip", "sha256sum"],
   },
   {
     flag: "build",
     short: "b",
     scripts: ["build-uki.sh", "build-image.sh"],
-    tools: [
+    tools: (arch) => [
       "fakeroot", "cpio", "gzip",
-      "x86_64-w64-mingw32-objcopy", "x86_64-w64-mingw32-objdump",
+      `${architectures[arch].binutils}-objcopy`, `${architectures[arch].binutils}-objdump`,
       "parted", "mkfs.fat", "mmd", "mcopy",
     ],
   },
@@ -37,7 +60,7 @@ const stages = [
     flag: "run",
     short: "r",
     scripts: ["run-qemu.sh"],
-    tools: ["qemu-system-x86_64"],
+    tools: (arch) => [`qemu-system-${arch}`],
   },
 ];
 
@@ -50,22 +73,32 @@ function usage() {
   return `${pkg.name} - ${pkg.description}
 
 Usage:
-  ${pkg.name} [-f] [-b] [-r] [--export] [--linux-lts] [--real] [-- qemu arguments]
+  ${pkg.name} [-f] [-b] [-r] [--arch ARCH] [--docker] [--export] [--linux-lts]
+               [--real] [-- qemu arguments]
 
 Stages (always run in this order, whichever you pick):
   -f, --fetch   download and verify the pinned kernel, musl, GCC runtime,
                 EFI stub and Bun      (fetch-alpine.sh, fetch-bun.sh)
   -b, --build   pack the initramfs, assemble the UKI, write vda.img
                                        (build-uki.sh, build-image.sh)
-  -r, --run     boot vda.img under QEMU (run-qemu.sh)
+  -r, --run     boot vda.img under QEMU (run-qemu.sh), with KVM or
+                Hypervisor.framework when the guest matches the host CPU
+
+  --arch ARCH   guest architecture: x86_64 (default; alias amd64, x64) or
+                aarch64 (alias arm64, native speed on Apple Silicon). A bare
+                -r boots whichever one vda.img was last built for
+  --docker      run fetch and build inside a Debian container built from
+                ./Dockerfile; always on for macOS, which lacks the toolchain
 
   --export      after -b/--build, copy the image to
-                ./buninu-linux-${pkg.version}.img
+                ./buninu-linux-${pkg.version}.img (x86_64) or
+                ./buninu-linux-${pkg.version}-aarch64.img
 
   --linux-lts   use Alpine's general-purpose linux-lts kernel for fetch/build
                 (the default is the smaller linux-virt kernel)
   --real        build for a physical machine: use linux-lts, make tty0 the
                 primary console, and include USB xHCI/HID keyboard modules
+                (x86_64 only)
 
   -h, --help    show this
   -V, --version show name, version, runtime and platform
@@ -73,11 +106,13 @@ Stages (always run in this order, whichever you pick):
 
 Short flags combine: -fbr is the whole pipeline, -br is what an edit to
 initramfs/init.js needs, -r just boots what is already there. Anything after
--- goes to qemu-system-x86_64 verbatim (for example: -r -- -m 1G).
+-- goes to qemu-system-x86_64 or qemu-system-aarch64 verbatim (for example:
+-r -- -smp 4).
 
-Fetch and build need the PRoot toolchain from README section 0; run needs
-qemu-system-x86_64, which Termux provides. Tools missing for the stages you
-picked are reported before anything starts.
+Fetch and build need the Debian toolchain from README "Build environment"
+(PRoot, a Debian or Ubuntu host, or --docker); run needs QEMU (Termux
+pkg, apt, or brew install qemu). Tools missing for the stages you picked are
+reported before anything starts.
 `;
 }
 
@@ -87,13 +122,24 @@ function parse(argv) {
   let linuxLts = false;
   let real = false;
   let exportImage = false;
+  let docker = false;
+  // BUNINU_ARCH is what scripts/arch.sh reads; --arch overrides it.
+  let arch = process.env.BUNINU_ARCH ? normalizeArch(process.env.BUNINU_ARCH) : null;
   let sawSeparator = false;
 
-  for (const argument of argv) {
+  for (let index = 0; index < argv.length; index++) {
+    const argument = argv[index];
     if (sawSeparator) {
       passthrough.push(argument);
     } else if (argument === "--") {
       sawSeparator = true;
+    } else if (argument === "--arch") {
+      if (index + 1 >= argv.length) fail("--arch needs a value: x86_64 or aarch64");
+      arch = normalizeArch(argv[++index]);
+    } else if (argument.startsWith("--arch=")) {
+      arch = normalizeArch(argument.slice("--arch=".length));
+    } else if (argument === "--docker") {
+      docker = true;
     } else if (argument === "-h" || argument === "--help") {
       console.log(usage());
       process.exit(0);
@@ -137,7 +183,10 @@ function parse(argv) {
   if (exportImage && !selected.has(stages[1])) {
     fail("--export requires -b/--build (use -fb --export for a clean build)");
   }
-  return { selected, passthrough, linuxLts, real, exportImage };
+  if (real && arch === "aarch64") {
+    fail("--real builds an x86_64 PC image; it cannot be combined with --arch aarch64");
+  }
+  return { selected, passthrough, linuxLts, real, exportImage, docker, arch };
 }
 
 // Same shape as Buninu's --version. The runtime line tells you whether this
@@ -180,54 +229,120 @@ function hasTool(name) {
   return false;
 }
 
+const inDocker = (stage) => useDocker && stage.flag !== "run";
+
 function checkTools(selectedStages) {
   const missing = [];
   for (const stage of selectedStages) {
-    for (const tool of stage.tools) {
+    const arch = stage.flag === "run" ? runArch : buildArch;
+    for (const tool of inDocker(stage) ? ["docker"] : stage.tools(arch)) {
       if (!hasTool(tool)) missing.push(`${tool} (for --${stage.flag})`);
     }
   }
   if (missing.length > 0) {
-    fail(
-      `missing tools, nothing was run:\n  ${missing.join("\n  ")}\n` +
-        `
-Run this command in Debian first:
-  apt install binutils-mingw-w64-x86-64 cpio curl dosfstools fakeroot mtools parted unzip
-`,
-    );
+    const hint = process.platform === "darwin"
+      ? `
+Install Docker Desktop (https://www.docker.com/products/docker-desktop/) for
+-f/-b, and QEMU with its UEFI firmware for -r:
+  brew install qemu
+`
+      : `
+Run this command in Debian or Ubuntu first, or pass --docker to build in a container:
+  apt install ${architectures[buildArch].apt} cpio curl dosfstools fakeroot mtools parted unzip
+QEMU for -r:
+  apt install qemu-system ovmf qemu-efi-aarch64
+`;
+    fail(`missing tools, nothing was run:\n  ${missing.join("\n  ")}\n${hint}`);
+  }
+  if (selectedStages.some(inDocker) && spawnSync("docker", ["info"], { stdio: "ignore" }).status !== 0) {
+    fail("docker is installed but its daemon is not answering; start Docker Desktop (or dockerd) and retry");
+  }
+}
+
+// The build image is tagged with a hash of the Dockerfile, so editing it
+// builds a fresh image and an unchanged one is reused without a rebuild. The
+// Dockerfile goes in on stdin: the build needs no context, and sending the
+// checkout (downloads/ included) would only slow it down.
+let dockerImageTag;
+function dockerImage() {
+  if (dockerImageTag) return dockerImageTag;
+  const dockerfile = readFileSync(resolve(rootDir, "Dockerfile"));
+  const tag = `buninu-linux-build:${createHash("sha256").update(dockerfile).digest("hex").slice(0, 12)}`;
+  if (spawnSync("docker", ["image", "inspect", tag], { stdio: "ignore" }).status !== 0) {
+    console.log(`\n==> [docker] building ${tag} from Dockerfile`);
+    const result = spawnSync("docker", ["build", "--tag", tag, "-"], {
+      input: dockerfile,
+      stdio: ["pipe", "inherit", "inherit"],
+    });
+    if (result.error) fail(`could not start docker build: ${result.error.message}`);
+    if (result.status !== 0) fail(`docker build exited with status ${result.status}`);
   }
+  return (dockerImageTag = tag);
+}
+
+// In Docker the script runs as the invoking user, so everything it writes
+// into the bind-mounted checkout stays owned by that user; fakeroot provides
+// the root ownership the initramfs records.
+function dockerRun(script, env) {
+  const passEnv = ["BUNINU_ARCH", "LINUX_FLAVOR", "REAL_MACHINE", "ALPINE_MIRROR"]
+    .filter((name) => env[name] !== undefined)
+    .flatMap((name) => ["--env", `${name}=${env[name]}`]);
+  const user = typeof process.getuid === "function"
+    ? ["--user", `${process.getuid()}:${process.getgid()}`]
+    : [];
+  return [
+    "run", "--rm", ...user,
+    "--mount", `type=bind,src=${rootDir},dst=/src`, "--workdir", "/src",
+    "--env", "HOME=/tmp", ...passEnv,
+    dockerImage(), `./${script}`,
+  ];
 }
 
 function runScript(stage, script, args = [], env = process.env) {
-  const path = resolve(rootDir, script);
-  console.log(`\n==> [${stage.flag}] ${script}${args.length ? " " + args.join(" ") : ""}`);
-  const result = spawnSync(path, args, { cwd: rootDir, stdio: "inherit", env });
+  const docker = inDocker(stage);
+  console.log(
+    `\n==> [${stage.flag}${docker ? " in docker" : ""}] ${script}${args.length ? " " + args.join(" ") : ""}`,
+  );
+  const result = docker
+    ? spawnSync("docker", dockerRun(script, env), { stdio: "inherit" })
+    : spawnSync(resolve(rootDir, script), args, { cwd: rootDir, stdio: "inherit", env });
   if (result.error) fail(`could not start ${script}: ${result.error.message}`);
   if (result.status !== 0) {
     fail(`${script} exited with status ${result.status ?? "signal " + result.signal}`);
   }
 }
 
-const { selected, passthrough, linuxLts, real, exportImage } = parse(process.argv.slice(2));
+const { selected, passthrough, linuxLts, real, exportImage, docker, arch } = parse(process.argv.slice(2));
 const ordered = stages.filter((stage) => selected.has(stage));
+const useDocker = docker || process.platform === "darwin";
+const buildArch = arch ?? "x86_64";
+// A bare -r after -b boots what -b just built; otherwise what vda.img holds.
+const runArch = arch ?? (selected.has(stages[1]) ? buildArch : builtArch());
 checkTools(ordered);
 
+const stageEnv = {
+  ...process.env,
+  ...(arch && { BUNINU_ARCH: arch }),
+  ...((linuxLts || real) && { LINUX_FLAVOR: "lts" }),
+  ...(real && { REAL_MACHINE: "1" }),
+};
+
 for (const stage of ordered) {
+  // run-qemu.sh builds a missing vda.img itself, which needs the build
+  // toolchain; with Docker that has to happen in the container first.
+  if (stage.flag === "run" && useDocker && !selected.has(stages[1]) &&
+      !existsSync(resolve(rootDir, "vda.img"))) {
+    runScript(stages[1], "build-image.sh", [], { ...stageEnv, BUNINU_ARCH: runArch });
+  }
   for (const script of stage.scripts) {
-    runScript(
-      stage,
-      script,
-      stage.flag === "run" ? passthrough : [],
-      linuxLts || real
-        ? { ...process.env, LINUX_FLAVOR: "lts", ...(real && { REAL_MACHINE: "1" }) }
-        : process.env,
-    );
+    runScript(stage, script, stage.flag === "run" ? passthrough : [], stageEnv);
   }
 }
 
 if (exportImage) {
   const source = resolve(rootDir, "vda.img");
-  const destination = resolve(invocationDir, `buninu-linux-${pkg.version}.img`);
+  const suffix = buildArch === "x86_64" ? "" : `-${buildArch}`;
+  const destination = resolve(invocationDir, `buninu-linux-${pkg.version}${suffix}.img`);
   try {
     accessSync(source, constants.R_OK);
     copyFileSync(source, destination);

package/initramfs/bin/bunterm

@@ -6,7 +6,7 @@ import { runTerminal } from "../lib/bunterm/terminal.js";
 
 const usage = () => {
   console.error(`Usage:
-  bunterm [/dev/ttyN] [--font-size N] [--fb /dev/fb0] [-e command [argument...]]
+  bunterm [/dev/ttyN] [--font-size N] [--fb /dev/fb0] [--no-mouse] [-e command [argument...]]
   bunterm -h | --help`);
 };
 
@@ -46,6 +46,10 @@ const main = async () => {
       options.device = valued("--fb");
     } else if (argument === "--no-blink") {
       options.cursorBlink = false;
+    } else if (argument === "--mouse") {
+      options.mouse = true;
+    } else if (argument === "--no-mouse") {
+      options.mouse = false;
     } else if (argument.startsWith("/dev/")) {
       options.console = argument;
     } else {