Bootstrapping

The compiler is written in qdx, so compiling it needs a compiler. The repository solves that by carrying one, already built, as bootstrap/qdx. It is the only file in the repository that is not source.

The build

bootstrap/qdx run std/*.qdx build.qdx

build.qdx is the build program, written in qdx. It makes three compilers, each from the same source in std/ and compiler/:

qdx2 and qdx3 must be identical, byte for byte. If the new compiler cannot reproduce itself, the build stops there. qdx1 is allowed to differ, because the old compiler may generate code differently from the new one.

The tests then run against qdx3.

Reseeding

bootstrap/qdx run std/*.qdx build.qdx -- seed

This runs the build and the tests, and if they pass, replaces bootstrap/qdx with build/qdx3. Commit the new binary together with the source change that produced it.

Reseed after any change to compiler/ or std/, so that the committed binary always matches the committed source.

Changing the language in two steps

The bootstrap compiler has to be able to compile the compiler’s own source. So the compiler cannot start using a feature in the same change that adds it.

To add a feature the compiler itself will use, such as a new built-in function:

1. Teach the compiler the feature, without using it anywhere in compiler/ or std/. Build, reseed, commit.
2. Now use it. Build, reseed, commit.

Removing a feature goes the other way: stop using it and reseed, then remove it and reseed.

A feature that only programs outside compiler/ and std/ will use needs one step.

If the binary is lost

The git tag ocaml-seed marks the last commit at which the compiler could be built without itself, from an earlier version written in OCaml. Building from there and walking forward through the commits, reseeding at each, is the way back to a working bootstrap/qdx. That path has not been exercised.

What the build needs

A Linux kernel on x86-64, and the repository. Nothing else is involved: no make, no shell script, no C compiler.