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
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 |