The decisions
Each structuring choice in Phosphoric has its record: the context, what was decided, what it costs. A replaced decision is not erased; it points to the next one.
| No. | Decision | Why | What it costs |
|---|---|---|---|
| 0001 | The Makefile is the only build system (2.1.3) | the CMakeLists.txt was no longer maintained: twenty sources were missing from it | no more generated IDE projects; every new source is added to the Makefile |
| 0002 | External commands go through a queue drained by the emulator loop (1.52) | --control, the HTTP API and the F1 menu change the state; run mid-instruction, they would corrupt it | an HTTP command waits up to one frame (20 ms); the queue must be closed before the server |
| 0003 | The tick order is a separate table, distinct from the access dispatch order (2.4.0) | the two orders have always differed, and the tick order has observable effects | unifying them would first require proving byte-for-byte equivalence |
| 0004 | Changing cards relaunches the process (2.11.0) | plugging a card opens ROM, overlay, bus, transport, and sometimes a running firmware | a true cold start: the Oric’s memory is lost; the web version cannot relaunch |
| 0005 | Two mirror branches, French and English, differing only by comments (2.1.4) | the project is written in French, but also published for an English-speaking audience | every release happens in two steps: main, then the translation in main-en |
| 0006 | Expansion cards are modules, with an explicit list (2.13.0) | a simple card touched ten or so files; adding a card was slow and error-prone | no dynamic loading; one line per card in the list |
What each one made possible
- 0001 made the build reliable: the “
make SDL2=0thenmake tests” trap, which mixed incompatible objects, disappeared by construction. - 0002 gave a single interpreter,
control_dispatch(), to all command sources. Since 2.12.0, its commands are filed by theme (control_cmd_*.c). - 0003 made it possible to add a clocked peripheral at the exact place that keeps the measured behaviour, and to unroll the tick loop (a generic loop cost 22% per frame).
- 0004 made the F1 menu’s cards editable: a card added to the registry appears in the menu with no other change.
- 0005 is checked by a tool,
tools/check_comment_only_diff.py, which strips comments and requires identical files;make test-comment-difftests that tool itself. - 0006 was proved by
make test-card-template: the sample card, added to a copy of the tree, works end to end.
The full records are in the repository, docs/adr/.