buninu-linux 0.9.56 → 0.10.56

package/initramfs/usr/lib/bootstrap/README.md

@@ -0,0 +1,204 @@
+# Bootstrap from Bun
+
+- Route and recipe reference: [ZilchOS/bootstrap-from-tcc](https://github.com/ZilchOS/bootstrap-from-tcc),
+  by Alexander Sosedkin. See [NOTICE.md](NOTICE.md) for full credit and component licenses.
+
+- Requires Bun with `Bun.cc`, `Bun.Archive` and `Bun.YAML` (tested with 1.4.2).
+- Supported targets: native ARM64 and x86-64 Linux with musl.
+- Run stages 1 and 2 outside the new rootfs; run stages 3–12 inside it.
+- The numbered filenames are the execution order.
+- Inside the new rootfs, use `cd /bootstrap`; scripts, `lib/`, `README.md` and
+  `downloads.md` live alongside `src`, `toolchain`, `deps`, `build` and `result`.
+- Copies of scripts 1/2 are included for reference; run preparation/entry from
+  the outer package, which also contains the bundled seed archives.
+
+## 1. Prepare a new rootfs
+
+```sh
+bun /usr/lib/bootstrap/1.prepare-rootfs.js
+```
+
+- Default architecture: the running Bun's architecture.
+- Default destination: `./roota` for ARM64, `./rootx` for x86-64.
+- Optional arguments: `[ARCH] [ROOTFS]`.
+- Architecture aliases: `a`, `arm64`, `aarch64`; `x`, `x64`, `x86_64`, `x86-64`.
+- A single directory argument uses the default architecture.
+- Destination must be new; its parent directory must already exist.
+
+```sh
+bun /usr/lib/bootstrap/1.prepare-rootfs.js a ./my-root
+bun /usr/lib/bootstrap/1.prepare-rootfs.js x
+bun /usr/lib/bootstrap/1.prepare-rootfs.js ./my-root
+```
+
+- On Buninu Linux (`ID=buninu-linux` in `/etc/os-release`), reuse the local
+  Bun, musl loader, libgcc, libstdc++, DNS configuration, bunmsh and extraction tools.
+- For a different target architecture, or outside Buninu Linux:
+  - Fetch `buninu-linux@0.9.56` for the runtime libraries and JavaScript tools.
+  - Fetch musl Bun 1.4.2 for the target architecture (x64 uses baseline).
+  - Verify SHA-256 before using either download.
+- Pins live in `downloads.md`; despite its extension, it is YAML with the same
+  URL/hash pair format as `scripts/npm-packages.md`.
+- Cache: `${XDG_CACHE_HOME:-$HOME/.cache}/buninu-bootstrap/`; cached files are
+  verified again. A bad cache entry causes an error, not an unchecked fallback.
+- No musl-dev APK, prebuilt CRT, installed headers or standalone compiler required.
+- Bundled sources are hash-checked and extracted:
+  - `sources/musl-1.2.6.tar.gz` -> `/bootstrap/src/musl`.
+  - `sources/tinycc-05f0faf-upstream.tar.gz` -> `/bootstrap/src/tinycc`.
+  - `sources/tinycc-local-bootstrap-files.tar.gz` -> TinyCC recipes and `/bin/cc`.
+- `/bin/sh` is an executable JavaScript file with `#!/bin/bun`.
+- It prepends `/bootstrap/result/bin` and `/bootstrap/toolchain/bin` to PATH,
+  removes duplicates, then dynamically imports bunmsh. Missing bin directories
+  are harmless; child processes inherit the environment.
+- Build stages use a separate shell launcher and explicit PATH so installed
+  result tools do not silently replace bootstrap tools during a rebuild.
+- Scripts 1–12 and helpers are copied to `/bootstrap` in the new rootfs.
+- Preparation can select another architecture; entering/building requires a
+  matching CPU or a separately configured emulator. These scripts do not set up emulation.
+
+## 2. Print the entry command
+
+```sh
+bun /usr/lib/bootstrap/2.enter-rootfs.js
+```
+
+- Accepts `[ARCH] [ROOTFS]`, with the same architecture aliases as stage 1.
+- Without a destination (including an architecture-only invocation), prints
+  `/path/to/your/rootfs` as a placeholder instead of assuming `roota` or `rootx`.
+- Prints commands only; it does not enter, modify or read the rootfs or its
+  marker file. The destination does not need to exist to print instructions.
+- Reads the host's os-release only to choose chroot versus bunproot.
+- Buninu Linux example (requires chroot privileges):
+
+```sh
+chroot '/absolute/path/rootx' /bin/sh
+```
+
+- Android/Termux and other hosts with bunproot:
+
+```sh
+bun x bunproot -koe -r '/absolute/path/roota'
+```
+
+## 3. Generate musl development files, inside the rootfs
+
+```sh
+cd /bootstrap
+bun 3.gen-musl-dev.js
+```
+
+- Generate 217 public headers from musl's source and architecture templates.
+- Build TinyCC in memory using `Bun.cc`; emit `crt1.o`, `crti.o`, `crtn.o`.
+- Install headers under `/usr/include`, CRT objects under `/usr/lib`.
+- Preserve the original musl sources.
+- ARM64 only: use a temporary startup-header override omitting the unused
+  `_DYNAMIC` argument, because TinyCC's ARM64 assembler does not support `adrp`.
+- This override applies only to ordinary `crt1`; static PIE `rcrt1` and the
+  dynamic loader are not built here.
+- Refuse existing headers/CRT instead of overwriting them.
+- If this stage fails after headers were generated, preserve the rootfs for
+  diagnosis and prepare a fresh destination before repeating the full flow.
+
+## 4. Build a standalone C compiler, inside the rootfs
+
+```sh
+bun /bootstrap/4.build-tcc.js
+cc /bootstrap/src/tinycc/bun-hello-libc.c -o /tmp/hello
+/tmp/hello
+```
+
+- Build TinyCC stage1 through `Bun.cc`, using the generated CRT.
+- Build the x64 compiler runtime helpers when needed.
+- Rebuild stage2 with stage1 and require byte-identical executables.
+- Verify libc, x64 conversions/variadic calls, and CRT startup behavior.
+- `/bin/cc` launches `/bootstrap/toolchain/bin/tcc` with the headers, libraries and helpers.
+- Stages 3/4 are offline; no host build tools are used.
+- The seed Bun, musl shared library, libgcc and libstdc++ remain prebuilt inputs.
+- Source licenses remain in the archives and extracted trees:
+  - musl: `/bootstrap/src/musl/COPYRIGHT`.
+  - TinyCC: `/bootstrap/src/tinycc/COPYING` and individual source-file notices.
+
+## 5–12. Build through GCC 4.7
+
+- Run each numbered script inside the same rootfs, in order.
+- Each stage fetches its source on demand and checks the SHA-256 in `downloads.md`.
+- These eight large source archives are **not** included in the npm package or initramfs.
+- Fixed version/commit URLs are used, never `latest` or a moving branch.
+- Cache: `/root/.cache/buninu-bootstrap` by default.
+- Source trees: `/bootstrap/src`; build trees and logs: `/bootstrap/build`.
+- Reserve at least 3 GB of writable workspace; avoid a small RAM-only rootfs.
+- Set `BOOTSTRAP_JOBS=1` to reduce build concurrency (default: 2).
+
+| Stage | Command after `bun /bootstrap/` | Source |
+| --- | --- | --- |
+| 5 | `5.build-make.js` | GNU Make 4.4.1, official GNU release |
+| 6 | `6.build-binutils.js` | Binutils 2.39, official GNU release |
+| 7 | `7.build-gmp.js` | GMP 4.3.2, official GNU release |
+| 8 | `8.build-mpfr.js` | MPFR 2.4.2, official version directory |
+| 9 | `9.build-mpc.js` | MPC 0.8.1, GCC infrastructure archive |
+| 10 | `10.build-m4.js` | GNU m4 1.4.18, official GNU release |
+| 11 | `11.build-flex.js` | Flex 2.6.4, official GitHub release |
+| 12 | `12.build-gcc.js` | GCC mirror, commit `9d2b63d100ae7c99ee8b128fb41086fd85c8f57d` |
+
+- GNU Make first uses its shipped no-make builder, then rebuilds itself.
+- Binutils supplies the assembler, linker and archive tools; stage 6 also
+  builds/tests the additional TinyCC runtime helpers needed by later stages.
+- GMP/MPFR/MPC are static prerequisite libraries; MPFR runs upstream arithmetic
+  tests, and MPC's stage verifies all three libraries together.
+- m4 and Flex are built from source and tested before GCC uses them.
+- `configure` and build shell commands use bunmsh. External utility adapters
+  call its JavaScript builtins in POSIX mode; no host awk/sed/coreutils enter the build.
+- Logs are streamed to the terminal and retained under `/bootstrap/build/logs/`.
+- Re-running a failed stage revalidates the download, reconfigures and resumes
+  its existing build tree. Source compatibility patches are idempotent.
+- GCC uses a vendor 4.7 branch containing both ARM64 and x64 backends. The pinned
+  GitHub snapshot's 76,720 regular source files match the earlier local archive.
+- Stage 12 builds the C frontend and libgcc, then tests `-O0`/`-O2`, the musl
+  interpreter, architecture/type macros and 128-bit runtime arithmetic.
+- Stage 12 runs GCC's `install-gcc` and `install-target-libgcc` rules with
+  `--prefix=/bootstrap/result`, and includes native Binutils executables.
+- GCC's private `include` and `include-fixed` directories are installed using
+  JavaScript with symlinks dereferenced, avoiding the tar pipe and recursive
+  `cp -p` requirements and retaining headers after source/build removal.
+- The installed compiler is `/bootstrap/result/bin/gcc`; it is not an `xgcc`
+  wrapper and needs no `-B` pointing into a build directory.
+- The final check temporarily renames `src`, `toolchain`, `deps` and `build`
+  to sibling `*.verification-hidden` directories, compiles/runs ordinary and
+  shared-library checks using only result tools, then restores the directories.
+- If interrupted by a forced kill, restore any `*.verification-hidden` directory
+  to its original name before resuming. Ordinary errors restore them automatically.
+- Successful verification writes `/bootstrap/result/verified.json` and
+  `/bootstrap/result/verification.log`; stage 12's build log remains in `build/logs`.
+- After stage 12 succeeds, `/bootstrap/build` can be deleted. The installed GCC
+  also does not need `src`, `deps` or `toolchain`; keep these to rebuild or use
+  the intermediate tools such as Make and TinyCC.
+- Result still uses the rootfs's musl loader/libc, `/usr/include`, `/usr/lib`
+  startup objects and seed runtime libraries. It is not a self-contained rootfs.
+- The installation prefix is fixed at `/bootstrap/result`; moving it into `/usr`
+  is not supported by simply copying it. A system installation should instead
+  configure `--prefix=/usr` and stage the installation with `DESTDIR`.
+- This is the GCC 4.7 C + libgcc stopping milestone, not a full GCC three-stage
+  bootstrap or a completed Bun rebuild.
+- This layout/install revision has only received static checks; validate it
+  by running the numbered stages in a new rootfs.
+
+## Directory layout
+
+| Directory | Contents |
+| --- | --- |
+| `/bootstrap/src` | musl, TinyCC and downloaded package source trees |
+| `/bootstrap/toolchain` | intermediate compiler, runtime helpers, Make, Binutils, m4, Flex and JS utility adapters |
+| `/bootstrap/deps` | static GMP, MPFR and MPC libraries and headers |
+| `/bootstrap/build` | intermediate objects, build trees and build logs |
+| `/bootstrap/result` | installed GCC, libgcc, Binutils and final verification records |
+
+```sh
+# Entering through /bin/sh already sets PATH.
+gcc --version
+gcc hello.c -o hello
+./hello
+```
+
+- The generated musl headers and CRT remain in `/usr/include` and `/usr/lib`.
+- The source archive download cache remains under `/root/.cache/buninu-bootstrap`.
+

package/initramfs/usr/lib/bootstrap/downloads.md

@@ -0,0 +1,49 @@
+# YAML: [immutable download URL, SHA-256]
+# npm SHA-256 verified against registry SHA-512 integrity.
+# Bun 1.4.2 pins match scripts/arch.js.
+
+"buninu-linux@0.9.56":
+  - https://registry.npmjs.org/buninu-linux/-/buninu-linux-0.9.56.tgz
+  - sha256:972b46b5f0b1caaa0e64e352de68e37b28cc6955ed4240e91f0fe358b0d6f73d
+
+"bun-linux-aarch64-musl@1.4.2":
+  - https://github.com/oven-sh/bun/releases/download/bun-v1.4.2/bun-linux-aarch64-musl.zip
+  - sha256:71760b6c8ea30623b81a4907cb815d48e2ea266f2e73e751534a44a0607950df
+
+"bun-linux-x64-musl-baseline@1.4.2":
+  - https://github.com/oven-sh/bun/releases/download/bun-v1.4.2/bun-linux-x64-musl-baseline.zip
+  - sha256:76e1db84e98f22f78de0a87e309bfbbf297732847f9720db36750646c85c8c18
+
+# Stages 5–12: fetched on demand, never bundled in the npm package.
+
+"make@4.4.1":
+  - https://ftp.gnu.org/gnu/make/make-4.4.1.tar.gz
+  - sha256:dd16fb1d67bfab79a72f5e8390735c49e3e8e70b4945a15ab1f81ddb78658fb3
+
+"binutils@2.39":
+  - https://ftp.gnu.org/gnu/binutils/binutils-2.39.tar.gz
+  - sha256:d12ea6f239f1ffe3533ea11ad6e224ffcb89eb5d01bbea589e9158780fa11f10
+
+"gmp@4.3.2":
+  - https://ftp.gnu.org/gnu/gmp/gmp-4.3.2.tar.gz
+  - sha256:7be3ad1641b99b17f6a8be6a976f1f954e997c41e919ad7e0c418fe848c13c97
+
+"mpfr@2.4.2":
+  - https://www.mpfr.org/mpfr-2.4.2/mpfr-2.4.2.tar.gz
+  - sha256:246d7e184048b1fc48d3696dd302c9774e24e921204221540745e5464022b637
+
+"mpc@0.8.1":
+  - https://gcc.gnu.org/pub/gcc/infrastructure/mpc-0.8.1.tar.gz
+  - sha256:e664603757251fd8a352848276497a4c79b7f8b21fd8aedd5cc0598a38fee3e4
+
+"m4@1.4.18":
+  - https://ftp.gnu.org/gnu/m4/m4-1.4.18.tar.gz
+  - sha256:ab2633921a5cd38e48797bf5521ad259bdc4b979078034a3b790d7fec5493fab
+
+"flex@2.6.4":
+  - https://github.com/westes/flex/releases/download/v2.6.4/flex-2.6.4.tar.gz
+  - sha256:e87aae032bf07c26f85ac0ed3250998c37621d95f8bd748b31f15b33c45ee995
+
+"gcc@4.7-9d2b63d":
+  - https://codeload.github.com/gcc-mirror/gcc/tar.gz/9d2b63d100ae7c99ee8b128fb41086fd85c8f57d
+  - sha256:8ba051b9c7e2de8f3dd97d0092cffd17cafec2e2e2f70f1ec17a6c94972c8f80

package/initramfs/usr/lib/bootstrap/lib/build.js

@@ -0,0 +1,155 @@
+import {
+  appendFileSync, chmodSync, copyFileSync, existsSync, mkdirSync,
+  readFileSync, readdirSync, utimesSync, writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+import { bootstrap, bun, download, quote, requireRootfs } from "./common.js";
+
+export const tools = "/bootstrap/toolchain/bin";
+export const toolchain = "/bootstrap/toolchain";
+export const deps = "/bootstrap/deps";
+export const sourceRoot = "/bootstrap/src";
+export const buildRoot = "/bootstrap/build";
+export const resultRoot = "/bootstrap/result";
+export function useLog(path) { log = path; }
+// Build shells preserve the explicit build PATH, without the guest entry
+// shell's preference for installed result tools.
+export const shell = tools + "/sh";
+export const make = tools + "/make";
+let log;
+
+export function stage(number, name, args) {
+  if (args.length) throw new Error(`Usage: bun ${number}.build-${name}.js`);
+  const { arch } = requireRootfs();
+  mkdirSync(buildRoot + "/logs", { recursive: true });
+  log = `${buildRoot}/logs/${number}-${name}.log`;
+  note(`\n${new Date().toISOString()} Stage ${number}: ${name} (${arch})`);
+  return { arch, triple: `${arch}-unknown-linux-musl` };
+}
+
+function note(text) {
+  console.log(text);
+  if (log) appendFileSync(log, text + "\n");
+}
+
+export function environment(extra = {}) {
+  return {
+    PATH: `${tools}:/bin:/usr/bin`, HOME: "/root", LC_ALL: "C",
+    SHELL: shell, CONFIG_SHELL: shell, CC: tools + "/cc", CC_FOR_BUILD: tools + "/cc",
+    AR: existsSync(toolchain + "/bin/ar") ? toolchain + "/bin/ar" : tools + "/bootstrap-ar",
+    LD: existsSync(toolchain + "/bin/ld") ? toolchain + "/bin/ld" : tools + "/bootstrap-ld",
+    RANLIB: existsSync(toolchain + "/bin/ranlib") ? toolchain + "/bin/ranlib" : ":",
+    NM: toolchain + "/bin/nm", MAKE: make, MAKEINFO: ":", CFLAGS: "-O2",
+    CFLAGS_FOR_TARGET: "-O2", lt_cv_sys_max_cmd_len: "32768",
+    ...extra,
+  };
+}
+
+export async function command(argv, cwd = buildRoot, extra = {}, capture = false) {
+  mkdirSync(cwd, { recursive: true });
+  note("$ " + argv.map(quote).join(" "));
+  const child = Bun.spawn(argv, {
+    cwd, env: environment(extra), stdin: "ignore", stdout: "pipe", stderr: "pipe",
+  });
+  const chunks = [];
+  async function drain(stream, output, collect) {
+    for await (const bytes of stream) {
+      const data = Buffer.from(bytes);
+      output.write(data);
+      if (log) appendFileSync(log, data);
+      if (collect) chunks.push(data);
+    }
+  }
+  const [status] = await Promise.all([
+    child.exited, drain(child.stdout, process.stdout, capture), drain(child.stderr, process.stderr, false),
+  ]);
+  if (status !== 0) throw new Error(`Command exited ${status}; see ${log}: ${argv[0]}`);
+  return capture ? Buffer.concat(chunks).toString() : "";
+}
+
+export async function source(pin, directory) {
+  // Verify on every stage invocation, including a cached archive.
+  const archive = await download(pin);
+  const target = join(sourceRoot, directory);
+  if (!existsSync(target)) {
+    mkdirSync(sourceRoot, { recursive: true });
+    const tar = new Bun.Archive(readFileSync(archive));
+    await tar.extract(sourceRoot);
+    // Preserve release-generated parsers/Makefiles: extraction time must
+    // not accidentally request autoconf, automake or bison regeneration.
+    for (const [name, file] of await tar.files()) {
+      const seconds = file.lastModified / 1000;
+      utimesSync(join(sourceRoot, name), seconds, seconds);
+    }
+  }
+  if (!existsSync(join(target, "configure"))) throw new Error(`Incomplete source tree: ${target}`);
+  return target;
+}
+
+export function patch(path, before, after) {
+  const old = readFileSync(path, "utf8");
+  if (old.includes(after)) return;
+  if (!old.includes(before)) throw new Error(`Patch context missing: ${path}`);
+  writeFileSync(path, old.replaceAll(before, after));
+}
+
+export function script(path, text) {
+  writeFileSync(path, "#!/bin/bun\n" + text, { mode: 0o755 });
+  chmodSync(path, 0o755);
+}
+
+export function installAdapters() {
+  mkdirSync(tools, { recursive: true });
+  script(shell, "await import('/buninu/apps/bunmsh/src/main.js');\n");
+  // Native Make/configure can exec these names; implementations remain JS.
+  const names = "awk basename cat chmod cmp cp cut date diff dirname echo egrep expr false fgrep grep head ln ls mkdir mktemp mv printf pwd rm rmdir sed sleep sort tail test touch tr true uname uniq wc".split(" ");
+  for (const name of names) script(`${tools}/${name}`, `
+import {executeArgv,createState,finishShell} from '/buninu/apps/bunmsh/src/shell.js';
+const state=createState({shellOptions:{posix:true}});
+const result=await executeArgv(['builtin',${JSON.stringify(name)},...process.argv.slice(2)],state);
+process.exitCode=(await finishShell(state,result.status)).status;
+`);
+  script(tools + "/bootstrap-ar", `import {existsSync} from 'node:fs';const ar='/bootstrap/toolchain/bin/ar';const p=Bun.spawn([...(existsSync(ar)?[ar]:['/bootstrap/toolchain/bin/tcc','-ar']),...Bun.argv.slice(2)],{stdin:'inherit',stdout:'inherit',stderr:'inherit'});process.exitCode=await p.exited;\n`);
+  script(tools + "/bootstrap-ld", `import {existsSync} from 'node:fs';const ld='/bootstrap/toolchain/bin/ld';const p=Bun.spawn([existsSync(ld)?ld:'/bootstrap/toolchain/bin/tcc',...Bun.argv.slice(2)],{stdin:'inherit',stdout:'inherit',stderr:'inherit'});process.exitCode=await p.exited;\n`);
+  installCc();
+}
+
+export function installCc() {
+  script(tools + "/cc", `
+import {existsSync} from 'node:fs';
+const args=Bun.argv.slice(2);
+const info=args.length===0 || args.every(a=>['-v','--version','-h','-hh','--help','-dumpversion','-dumpmachine','-print-search-dirs'].includes(a));
+const linking=!info && !args.some(a=>['-c','-E','-S','-r'].includes(a));
+const archive=process.arch==='x64'?'/bootstrap/toolchain/lib/tcc/libbootstrap-tcc-x64.a':'/bootstrap/toolchain/lib/tcc/libbootstrap-tcc-arm64.a';
+const runtime=linking&&existsSync(archive)?[archive]:[];
+const p=Bun.spawn(['/bootstrap/toolchain/bin/tcc',...args,...(info?[]:['-B/bootstrap/toolchain/lib/tcc','-nostdinc','-I/usr/include','-I/bootstrap/toolchain/lib/tcc/include','-L/usr/lib','-L/lib',...runtime,...(linking?['-lgcc_s']:[])])],{stdin:'inherit',stdout:'inherit',stderr:'inherit'});
+process.exitCode=await p.exited;
+`);
+}
+
+export async function configure(src, build, flags, extra = {}) {
+  await command([bun(), "/buninu/apps/bunmsh/index.js", src + "/configure", ...flags], build, extra);
+}
+
+export async function makeIn(build, targets = ["all"], extra = {}) {
+  const jobs = process.env.BOOTSTRAP_JOBS || "2";
+  if (!/^[1-9][0-9]*$/.test(jobs)) throw new Error("BOOTSTRAP_JOBS must be a positive integer");
+  await command([make, "SHELL=" + shell, "MAKEINFO=:", "-j" + jobs, ...targets], build, extra);
+}
+
+export function canonicalizers(src) {
+  const binutils = sourceRoot + "/binutils-2.39";
+  for (const name of ["config.sub", "config.guess"]) {
+    copyFileSync(join(binutils, name), join(src, name));
+    chmodSync(join(src, name), 0o755);
+  }
+}
+
+export function ready(number, message) {
+  note(`Stage ${number} verified: ${message}`);
+  if (number < 12) {
+    const next = readdirSync(bootstrap).find(name => name.startsWith(`${number + 1}.`) && name.endsWith(".js"));
+    if (!next) throw new Error(`Missing stage ${number + 1}`);
+    note(`Next: bun /bootstrap/${next}`);
+  }
+}

package/initramfs/usr/lib/bootstrap/lib/common.js

@@ -0,0 +1,134 @@
+import {
+  existsSync, lstatSync, mkdirSync, readFileSync, writeFileSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { createHash } from "node:crypto";
+
+export const bootstrap = resolve(import.meta.dir, "..");
+export const bun = () => Bun.which("bun") || process.argv0;
+export const quote = value => "'" + value.replaceAll("'", "'\\''") + "'";
+
+export function normalizeArch(name) {
+  if (["x", "x64", "x86_64", "x86-64"].includes(name)) return "x86_64";
+  if (["a", "aarch64", "arm64"].includes(name)) return "aarch64";
+  throw new Error(`Unsupported architecture: ${name}`);
+}
+
+export function options(args) {
+  if (args.includes("--help") || args.includes("-h")) {
+    console.log("Usage: bun SCRIPT [ARCH] [ROOTFS]");
+    console.log("ARCH: a/arm64/aarch64 or x/x64/x86_64/x86-64; default: host architecture.");
+    console.log("ROOTFS: default ./roota (arm64) or ./rootx (x64). A lone path is accepted.");
+    return null;
+  }
+  let arch = normalizeArch(process.arch);
+  const rest = [...args];
+  if (rest.length && /^(x|x64|x86_64|x86-64|a|arm64|aarch64)$/.test(rest[0])) {
+    arch = normalizeArch(rest.shift());
+  }
+  if (rest.length > 1 || rest.some(arg => arg.startsWith("-"))) {
+    throw new Error("Expected [ARCH] [ROOTFS]; use --help");
+  }
+  return { arch, rootfs: resolve(rest[0] ?? (arch === "aarch64" ? "roota" : "rootx")) };
+}
+
+// Parse data only: do not execute os-release as shell code.
+export function isBuninuLinux() {
+  let text;
+  try { text = readFileSync("/etc/os-release", "utf8"); }
+  catch (error) {
+    if (error.code !== "ENOENT") throw error;
+    try { text = readFileSync("/usr/lib/os-release", "utf8"); }
+    catch (fallback) { if (fallback.code === "ENOENT") return false; throw fallback; }
+  }
+  return hasBuninuId(text);
+}
+
+export function hasBuninuId(text) {
+  const ids = [...text.matchAll(/^ID=(.*)\r?$/gm)];
+  const value = ids.at(-1)?.[1].trim();
+  return ["buninu-linux", '"buninu-linux"', "'buninu-linux'"].includes(value);
+}
+
+export function assertAbsent(path) {
+  try { lstatSync(path); }
+  catch (error) { if (error.code === "ENOENT") return; throw error; }
+  throw new Error(`Refusing existing destination: ${path}`);
+}
+
+export function write(path, bytes, mode = 0o644) {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, bytes, { flag: "wx", mode });
+}
+
+export const sha256 = bytes => createHash("sha256").update(bytes).digest("hex");
+
+export async function download(name) {
+  const pins = Bun.YAML.parse(readFileSync(join(bootstrap, "downloads.md"), "utf8"));
+  const pin = pins[name];
+  if (!Array.isArray(pin) || !/^sha256:[a-f0-9]{64}$/.test(pin[1])) {
+    throw new Error(`Missing or invalid download pin: ${name}`);
+  }
+  const [url, hash] = pin;
+  const expected = hash.slice(7);
+  const cache = join(process.env.XDG_CACHE_HOME || join(homedir(), ".cache"), "buninu-bootstrap");
+  const path = join(cache, expected + "-" + new URL(url).pathname.split("/").at(-1));
+  if (existsSync(path)) {
+    const bytes = readFileSync(path);
+    if (sha256(bytes) !== expected) throw new Error(`Cached file hash mismatch: ${path}`);
+    console.log(`Verified cache: ${name}`);
+    return path;
+  }
+  console.log(`Fetching ${name}`);
+  const response = await fetch(url);
+  if (!response.ok) throw new Error(`${url}: HTTP ${response.status}`);
+  const bytes = Buffer.from(await response.arrayBuffer());
+  if (sha256(bytes) !== expected) throw new Error(`Download hash mismatch: ${name}`);
+  mkdirSync(cache, { recursive: true });
+  writeFileSync(path, bytes, { flag: "wx", mode: 0o644 });
+  return path;
+}
+
+export async function run(argv) {
+  console.log("$ " + argv.map(quote).join(" "));
+  const child = Bun.spawn(argv, { stdin: "inherit", stdout: "inherit", stderr: "inherit" });
+  const status = await child.exited;
+  if (status !== 0) throw new Error(`Command exited ${status}: ${argv[0]}`);
+}
+
+export async function cli(main) {
+  const mask = process.umask(0o022);
+  try { await main(Bun.argv.slice(2)); }
+  catch (error) { console.error(error.message); process.exitCode = 1; }
+  finally { process.umask(mask); }
+}
+
+export function requireRootfs() {
+  // Prevent an accidental stage 3/4 invocation from writing host /usr/include.
+  const marker = JSON.parse(readFileSync("/etc/buninu-bootstrap.json", "utf8"));
+  if (marker.format !== 1 || marker.arch !== normalizeArch(process.arch)) {
+    throw new Error("Enter the prepared rootfs for the matching architecture first");
+  }
+  if (bootstrap !== "/bootstrap") throw new Error("Run this stage inside the prepared rootfs");
+  return marker;
+}
+
+export function validateElf(name, data, arch) {
+  if (data.length < 64 || data.toString("hex", 0, 4) !== "7f454c46"
+      || data[4] !== 2 || data[5] !== 1 || data.readUInt16LE(18) !== (arch === "aarch64" ? 183 : 62)) {
+    throw new Error(`Not a ${arch} little-endian ELF64 file: ${name}`);
+  }
+}
+
+export function elfInterpreter(data) {
+  const start = Number(data.readBigUInt64LE(32)), stride = data.readUInt16LE(54), count = data.readUInt16LE(56);
+  for (let i = 0; i < count; i++) {
+    const p = start + i * stride;
+    if (!Number.isSafeInteger(p) || stride < 56 || p + 56 > data.length) throw new Error("Invalid Bun ELF program headers");
+    if (data.readUInt32LE(p) !== 3) continue;
+    const at = Number(data.readBigUInt64LE(p + 8)), size = Number(data.readBigUInt64LE(p + 32));
+    if (!Number.isSafeInteger(at) || !Number.isSafeInteger(size) || at + size > data.length) throw new Error("Invalid Bun ELF interpreter range");
+    return data.subarray(at, at + size).toString().replace(/\0.*$/s, "");
+  }
+}

package/initramfs/usr/lib/bootstrap/lib/compile-object.c

@@ -0,0 +1,14 @@
+#include "/bootstrap/src/tinycc/libtcc.c"
+
+int compile_object(const char *source, const char *output, const char *flags) {
+    TCCState *s = tcc_new();
+    if (!s) return 10;
+    tcc_set_lib_path(s, "/bootstrap/src/tinycc");
+    int result = tcc_set_options(s, flags);
+    if (!result) result = tcc_set_output_type(s, TCC_OUTPUT_OBJ);
+    if (!result) result = tcc_add_file(s, source);
+    if (!result) result = tcc_output_file(s, output);
+    tcc_delete(s);
+    return result;
+}
+#include "/bootstrap/src/tinycc/bun-x64-runtime.c"

package/initramfs/usr/lib/bootstrap/lib/musl-headers.js

@@ -0,0 +1,59 @@
+// Generate musl 1.2.6 public headers without Make, sed or a C compiler.
+import {
+  existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync,
+} from "node:fs";
+import { dirname, join } from "node:path";
+
+export function generateHeaders(arch, source, output) {
+  if (readFileSync(join(source, "VERSION"), "utf8").trim() !== "1.2.6") {
+    throw new Error("This generator follows musl 1.2.6's header rules");
+  }
+  if (existsSync(output)) throw new Error(`Refusing existing output: ${output}`);
+  const headers = new Map();
+  const copyHeaders = (directory, prefix = "") => {
+    for (const entry of readdirSync(directory, { withFileTypes: true })) {
+      if (entry.isFile() && entry.name.endsWith(".h")) {
+        headers.set(prefix + entry.name, readFileSync(join(directory, entry.name)));
+      }
+    }
+  };
+
+  // Makefile's include/*.h and include/*/*.h public headers.
+  copyHeaders(join(source, "include"));
+  for (const entry of readdirSync(join(source, "include"), { withFileTypes: true })) {
+    if (entry.isDirectory()) copyHeaders(join(source, "include", entry.name), entry.name + "/");
+  }
+  // Architecture-specific bits override generic fallbacks.
+  copyHeaders(join(source, "arch/generic/bits"), "bits/");
+  copyHeaders(join(source, "arch", arch, "bits"), "bits/");
+
+  // Translate tools/mkalltypes.sed's three substitutions literally. The
+  // replacement's final newline is intentional, in addition to the input's.
+  const types = readFileSync(join(source, "arch", arch, "bits/alltypes.h.in"), "utf8")
+    + readFileSync(join(source, "include/alltypes.h.in"), "utf8");
+  headers.set("bits/alltypes.h", types
+    .replace(/^TYPEDEF (.*) ([^ ]*);$/gm, (_, type, name) =>
+      `#if defined(__NEED_${name}) && !defined(__DEFINED_${name})\ntypedef ${type} ${name};\n#define __DEFINED_${name}\n#endif\n`)
+    .replace(/^STRUCT * ([^ ]*) (.*);$/gm, (_, name, body) =>
+      `#if defined(__NEED_struct_${name}) && !defined(__DEFINED_struct_${name})\nstruct ${name} ${body};\n#define __DEFINED_struct_${name}\n#endif\n`)
+    .replace(/^UNION * ([^ ]*) (.*);$/gm, (_, name, body) =>
+      `#if defined(__NEED_union_${name}) && !defined(__DEFINED_union_${name})\nunion ${name} ${body};\n#define __DEFINED_union_${name}\n#endif\n`));
+
+  // Makefile: copy the input, then append sed -n 's/__NR_/SYS_/p' output.
+  const syscalls = readFileSync(join(source, "arch", arch, "bits/syscall.h.in"), "utf8");
+  const aliases = syscalls.split("\n").filter(line => line.includes("__NR_"))
+    .map(line => line.replace("__NR_", "SYS_") + "\n").join("");
+  headers.set("bits/syscall.h", syscalls + aliases);
+
+  const previousUmask = process.umask(0o022);
+  try {
+    mkdirSync(output); // Parent must exist; refuse races with another writer.
+    for (const [name, data] of headers) {
+      const path = join(output, name);
+      mkdirSync(dirname(path), { recursive: true });
+      writeFileSync(path, data, { flag: "wx", mode: 0o644 });
+    }
+  } finally { process.umask(previousUmask); }
+  console.log(`Generated ${headers.size} ${arch} headers at ${output}`);
+}
+