commit 203b4b271024e403cd997d2bec21a0ce6c26b5db
parent 8e53781e5a0dd5b1a6b264ffee145d7e8a0f925a
Author: Ryan Sepassi <rsepassi@gmail.com>
Date: Wed, 6 May 2026 13:12:55 -0700
B (README): arch×driver matrix, build entry points, tests pointer
PLAN.md "B. Polish / Docs" pass for README. Adds:
- arch × driver completion matrix (aarch64 full both drivers; amd64
seed boot3+ unvalidated; riscv64 full both drivers).
- DRIVER explanation (podman vs seed; coexisting trees; first-time
setup constraint).
- both build entry points: scripts/boot.sh and the path-based
make build/<arch>/<driver>/boot{N}/<file> targets.
- tests/ section with suite list + invocation; pointer to
tests/README.md and tests/seed-accept.sh.
Extends the Scheme-flavored bootstrap narrative through boot5/boot6.
Diffstat:
| M | README.md | | | 76 | ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
1 file changed, 76 insertions(+), 0 deletions(-)
diff --git a/README.md b/README.md
@@ -38,6 +38,13 @@
(define tcc0 (scc tcc.c)) ;; boot3: compiler is scheme cc.scm
(define tcc1 (tcc0 tcc.c)) ;; boot4: compiler is scheme-compiled tcc
(define tcc (tcc1 tcc.c)) ;; boot4: compiler is tcc-compiled tcc
+
+;; ── boot5.sh ── musl ──────────────────────────────────────────────────
+;; tcc + mes-libc compile musl-1.2.5 to produce libc.a + crt{1,i,n}.o.
+
+;; ── boot6.sh ── seed-kernel ───────────────────────────────────────────
+;; tcc links the seed-kernel ELF (Image on aarch64). That kernel is the
+;; runtime for DRIVER=seed re-runs, closing the bootstrap loop.
```
* P1: [docs/P1.md](docs/P1.md.html)
@@ -46,5 +53,74 @@
* P1PP: [docs/LIBP1PP.md](docs/LIBP1PP.md.html), [P1/P1.M1pp](P1/P1.M1pp.html), [P1/P1pp.P1pp](P1/P1pp.P1pp.html)
* Scheme: [docs/SCHEME1.md](docs/SCHEME1.md.html), [scheme1/scheme1.P1pp](scheme1/scheme1.P1pp.html)
* C: [docs/CC.md](docs/CC.md.html), [cc/cc.scm](cc/cc.scm.html)
+* OS: [docs/OS.md](docs/OS.md.html) (seed-kernel contract), [docs/MUSL.md](docs/MUSL.md.html)
+
+## Architectures × drivers
+
+| | DRIVER=podman | DRIVER=seed |
+|---------|------------------------|--------------------------------------------|
+| aarch64 | boot0 → boot6 complete | boot0 → boot6 complete |
+| amd64 | boot0 → boot6 complete | boot0 → boot2 complete; boot3+ unvalidated |
+| riscv64 | boot0 → boot6 complete | boot0 → boot6 complete |
+
+`DRIVER` selects the runtime that executes each bootN stage:
+
+* **podman** (default) — each stage runs in a per-arch container under
+ `qemu-user`. One-time host setup: a working `podman` + the qemu-user
+ static binaries for the cross arches.
+* **seed** — each stage runs inside the tcc-built seed-kernel under
+ `qemu-system-<arch>`. Closes the loop: the kernel built by
+ `DRIVER=podman` boot6 is the runtime for the next pass. First-time
+ setup therefore requires one prior `DRIVER=podman` pass per arch.
+ Host needs `qemu-system-<arch>` for the target.
+
+Both drivers write to disjoint trees (`build/<arch>/<driver>/...`), so
+they coexist.
+
+## Building
+
+End-to-end via the driver script:
+
+```sh
+./scripts/boot.sh aarch64 # default DRIVER=podman
+DRIVER=seed ./scripts/boot.sh aarch64 # re-run on the tcc-built kernel
+./scripts/boot.sh --help # env vars (DRIVER, BOOT*_TIMEOUT, …)
+```
+
+Or via path-based Make targets — outputs are the targets, so deps walk
+the chain back to source-prep:
+
+```sh
+make build/aarch64/podman/boot6/Image # full chain
+make build/amd64/podman/boot6/kernel.elf
+make build/riscv64/podman/boot1/M1pp # only prep-src + boot0 + boot1
+make all ARCH=aarch64 DRIVER=podman # convenience: boot6 kernel
+make help # target list
+```
+
+Per-stage outputs land at `build/<arch>/<driver>/boot{0..6}/`; the
+canonical generated source tree (used by every stage) is at
+`build/<arch>/src/`.
+
+## Tests
+
+Suites live in `tests/` with their own Makefile (included from the
+top-level). Each suite picks fixtures by `<NNN>-<name>.<ext>` and
+diff-checks `<NNN>-<name>.expected` (and optional `.expected-exit`).
+
+```sh
+make test # all suites, default arch
+make test SUITE=cc # one suite
+make test SUITE=cc NAMES='001 042' # filter by fixture prefix
+make test SUITE=tcc-cc ARCH=amd64 STAGE=2 # tcc-built test runner
+```
+
+Suites: `m1pp`, `p1`, `scheme1`, `cc-util`, `cc-lex`, `cc-pp`, `cc-cg`,
+`cc`, `cc-libc`, `cc-ext`, `tcc-cc`, `tcc-libc`. Full per-suite contract
+in [tests/README.md](tests/README.md).
+
+`tests/seed-accept.sh` is a separate seed-driver acceptance harness that
+diffs seed-built vs podman-built artifacts for byte equivalence; see
+that script's header for modes.
If you'd like to chat, email me at hi at ryansepassi.com
