From 53c04711eb9254ac4a6b6d5bca1245e18a306a52 Mon Sep 17 00:00:00 2001 From: Graeme Geldenhuys Date: Wed, 13 May 2026 01:23:07 +0100 Subject: [PATCH] docs: document cold-bootstrap RTL chicken-and-egg issue On a clean checkout, compiler/target/blaise does not exist yet, so plain `make` in rtl/ produces empty .ssa files and a silently broken RTL archive. The fix is to pass BLAISE=../releases/v0.7.0/blaise to make on the first RTL build. Document this in both README.adoc and CLAUDE.md with the correct three-step cold-bootstrap sequence. --- README.adoc | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/README.adoc b/README.adoc index 309dfc0..4df7b76 100644 --- a/README.adoc +++ b/README.adoc @@ -161,10 +161,15 @@ compiles the next version. The bootstrap chain starts from the binary in === Bootstrap from a release +The RTL build compiles its Pascal units (`blaise_str.pas`, `blaise_arc.pas`, +`blaise_sys.pas`) using the Blaise binary at `compiler/target/blaise`. On a +clean checkout that binary does not exist yet, so the release binary must be +passed explicitly via the `BLAISE` make variable. + [source,shell] ---- -# 1. Build the RTL (C static library) -cd rtl && make && make install && cd .. +# 1. Build the RTL using the release binary (BLAISE= avoids chicken-and-egg) +cd rtl && make BLAISE=../releases/v0.7.0/blaise && make install && cd .. # 2. Compile the compiler using the latest release binary releases/v0.7.0/blaise \ @@ -178,6 +183,9 @@ vendor/qbe/qbe -o /tmp/blaise.s /tmp/blaise.ssa gcc -o compiler/target/blaise /tmp/blaise.s compiler/target/blaise_rtl.a ---- +Once `compiler/target/blaise` exists, subsequent RTL rebuilds (`make && make install`) +work without the override. + === Build via PasBuild PasBuild can drive the full compile and test cycle using a Blaise binary: