seed: Document the bootstrap history

7a1d3e52f4729e5c3bb89ef0a3e02445f9aeeca2fdbd522fabd151b2769f8068
Nothing described how to rebuild the seed chain, how breaking changes
reach a seed, or which emulator runs which seed. The seed image format
and host interface changed over time, so rebuilding the history needs
three emulator commits, and the host ABI transition needs two of them in
one seed update.

Add a section to `seed/README` on how each seed relates to its source
and to the previous seed, how to verify the chain, and how breaking
changes are staged. Add `seed/emulators`, which names for each seed
source tree the emulator commit that runs compilers built from that
tree. A compiler runs on the emulator of the tree that built it, so a
seed update across a format or interface change runs its first stage on
the previous seed's emulator.

Assisted-by: Claude:opus-5.5
Alexis Sellier committed ago 1 parent 74d917cd
seed/README +49 -0
43 43
                               text, read-only data, and read-write data.
44 44
  seed/radiance.rv64.git       Full Git tree ID of the source commit that
45 45
                               was compiled to produce this seed.
46 46
  seed/update                  Tool that finds the fixed point and
47 47
                               updates the seed.
48 +
  seed/emulators               Emulator commit that runs the compiler built
49 +
                               from each seed source tree.
48 50
49 51
50 52
EVERYDAY DEVELOPMENT
51 53
52 54
Most compiler work -- bug fixes, optimizations, new standard library
194 196
    Compare that result with the recorded tree ID. The title uses the
195 197
    first eight characters: Create new seed from `<tree ID>`.
196 198
    The recorded object must be inspectable with `git cat-file -p TREE_ID`.
197 199
198 200
201 +
BOOTSTRAPPING THE HISTORY
202 +
203 +
  Every commit in the history builds with its own checked-in seed. Each
204 +
  seed commit has its source as its parent: `seed/radiance.rv64.git`
205 +
  names that parent commit, or its tree in later seeds. The seed is the
206 +
  fixed point of that source, reached from the previous seed. The first
207 +
  seed is the fixed point reached from `radiance.s0`, the bootstrapping
208 +
  compiler at its commit 7834d3a.
209 +
210 +
  To verify the whole chain, build the first seed with `--from-s0`.
211 +
  Then, for each later seed commit in order, check out its parent, run
212 +
  `seed/update --seed <previous seed>` with the emulators that
213 +
  `seed/emulators` names (see below), and compare the result with the
214 +
  seed that the seed commit checks in.
215 +
216 +
  Breaking changes
217 +
218 +
    A change that the previous seed cannot compile is staged. First the
219 +
    compiler supports the new form without requiring it, and a seed
220 +
    follows. Then the compiler's own source moves to the new form, and
221 +
    finally a commit requires it. The ownership rewrite instead follows a
222 +
    bridge commit, "Bootstrap ownership syntax", which extends the
223 +
    previous compiler just enough to compile the rewrite.
224 +
225 +
  Emulators
226 +
227 +
    The seed image format and host interface changed over time, so
228 +
    different seeds run on different commits of the emulator.
229 +
    `seed/emulators` gives, for each seed source tree, the emulator
230 +
    commit that runs compilers built from that tree:
231 +
232 +
      <seed source tree>  <emulator commit>
233 +
234 +
    A compiler runs on the emulator of the tree that built it. When the
235 +
    image format or host interface changes, the first stage of a seed
236 +
    update runs the previous seed on its emulator, and later stages run
237 +
    on the new one. `seed/update` uses one emulator, so for such a seed,
238 +
    build the first stage yourself:
239 +
240 +
      RAD_EMULATOR=<previous emulator> make bin/radiance.rv64.dev
241 +
      RAD_EMULATOR=<new emulator> seed/update --seed bin/radiance.rv64.dev
242 +
243 +
    When you update the seed, add a line for its source tree, the ID that
244 +
    `seed/update` writes to `seed/radiance.rv64.git`, and the emulator
245 +
    commit that runs the new seed.
246 +
247 +
199 248
TROUBLESHOOTING
200 249
201 250
  "No fixed point reached after N stages"
202 251
203 252
    The compiler output is non-deterministic. Diff the binaries
seed/emulators added +27 -0
1 +
# Emulator commit that runs the compiler built from each seed source tree.
2 +
# One line per seed, in history order: source tree, emulator commit.
3 +
2f8daf197dc1e5942908278b184575b3e47c1d04f77c7a5d9c678fc32e5426e6 92cdb0c5293447964be053214fac403b49193ac3ec07c902576346ebaa205535
4 +
97a0b1b94a1e8c2bb2b6c85cc166d307b7bd74d966b08f8cea828d2fe42cbfa7 92cdb0c5293447964be053214fac403b49193ac3ec07c902576346ebaa205535
5 +
bacf9561dadcac0334dd3acb4515f44ce87d82cbcd300957f7e83b0bea3a3b94 92cdb0c5293447964be053214fac403b49193ac3ec07c902576346ebaa205535
6 +
ab336db3567c634b5582c9b539d6915400ecb66eb49d4ea7c47653391b9184ad 92cdb0c5293447964be053214fac403b49193ac3ec07c902576346ebaa205535
7 +
b4f5c16072626d496f8bf6452c309a75c474bdbd87fe68ffdc35ef429e6caca7 92cdb0c5293447964be053214fac403b49193ac3ec07c902576346ebaa205535
8 +
fc24bde316e1c1784c5545344acd61df3d9a34196f7b25f3f4f915c2f69c4be9 92cdb0c5293447964be053214fac403b49193ac3ec07c902576346ebaa205535
9 +
a0c9ab81c14eab067d1cd8a1150a3fecd8413136a9ab390453cd7c5ee393b35a 92cdb0c5293447964be053214fac403b49193ac3ec07c902576346ebaa205535
10 +
79fd0b036ed056a30d49b1c1c1fe4cd58c0ebd1abb43d23fb928a7025cd977d5 92cdb0c5293447964be053214fac403b49193ac3ec07c902576346ebaa205535
11 +
dbff2ca7b2f4a1e31ca14453be2cb9b2558decfc9b0d46f77cc77d925d24067f 92cdb0c5293447964be053214fac403b49193ac3ec07c902576346ebaa205535
12 +
45ecb7fab60cf80dbed4796b1008ef6ab54c88de6a2ae54678dc35c44885e64b 92cdb0c5293447964be053214fac403b49193ac3ec07c902576346ebaa205535
13 +
87fbb28f6d727d5894cff3dc16187b2c56b18a4b6fc99a84b0e440a97dde03ae 92cdb0c5293447964be053214fac403b49193ac3ec07c902576346ebaa205535
14 +
f7cbb68a5a845e7ed95c78c225900cdc08753c9b5cf81c6bf3997fa55acfc927 92cdb0c5293447964be053214fac403b49193ac3ec07c902576346ebaa205535
15 +
30d107f2b5bca00fe9ecf97e44fc92c5716d74c8527e9a03c2af255ed7def8ad 92cdb0c5293447964be053214fac403b49193ac3ec07c902576346ebaa205535
16 +
a44684634d40fd27c130ff8c6a46b204e18ca55147921894e4cd820916b93ec2 92cdb0c5293447964be053214fac403b49193ac3ec07c902576346ebaa205535
17 +
867edd324bef4c7132641d1bd2f06d9cba7ffd688650d26abfa07b8916fe01ec 92cdb0c5293447964be053214fac403b49193ac3ec07c902576346ebaa205535
18 +
7af0c5e24f3b67136f27f5a261b696eb6ce482798f5162e650063a935634348c 92cdb0c5293447964be053214fac403b49193ac3ec07c902576346ebaa205535
19 +
f8dbdfe3e1bfe72e6061740e05596b554d8bbaf537110bbf5ea5216495a6037c 92cdb0c5293447964be053214fac403b49193ac3ec07c902576346ebaa205535
20 +
a07dbae68b995f9602ef47cd3c7aba68149676f43da4c20a47fcd430ff684b5d 92cdb0c5293447964be053214fac403b49193ac3ec07c902576346ebaa205535
21 +
e6981272c54718370b40b301e822897876b1d5ad4dcc104db6096cf1c79ae927 92cdb0c5293447964be053214fac403b49193ac3ec07c902576346ebaa205535
22 +
1d06b7cb9ea82eb3ca31edc29ddb076de3a77654d4ffb30678f41a5c81adeb22 92cdb0c5293447964be053214fac403b49193ac3ec07c902576346ebaa205535
23 +
cb02cf9981476f9aad308125e7d4086abf9261448b33f5359ff807ec79abdffa 92cdb0c5293447964be053214fac403b49193ac3ec07c902576346ebaa205535
24 +
0ba4857a931e06a3123a41253559cc45976cb4d17a9e46ebc84ccc2e87941daa 92cdb0c5293447964be053214fac403b49193ac3ec07c902576346ebaa205535
25 +
e9231f251c2fb025d885e633ba769793c27790a097071685a08d71f1c7ef8d85 92cdb0c5293447964be053214fac403b49193ac3ec07c902576346ebaa205535
26 +
db68bd728b5426857c3b8ad5230b6dbb02433add2d286044e0bd946b6805f097 4db56f55927810527a31ca73d68ffbd0f2799b8ccae7330b161c3fcb040bc36e
27 +
71178f37518b593d5f451245567b757f9ad798455ed0cb60a8696dd1ce5d0f90 e76b614c356a89ad71fc7253f63624b0c7e6bbabca8040c54db541f30e364309