66 lines
5.1 KiB
Markdown
66 lines
5.1 KiB
Markdown
# What is in here, and what is still true
|
|
|
|
These are the documents that are written once and read occasionally: the reasons behind the code, the
|
|
reports from finished investigations, and the record of individual work sessions. The documents that are
|
|
edited every day stay at the repository root, because source comments cite them by bare filename from
|
|
dozens of places and a path that moves is a path that rots. So `plan.org`, `NEXT.md`, `spec-memory.md`
|
|
and `spec-conditions.md` are one directory up, and everything here points back at them.
|
|
|
|
A note on how to read the citations below: a document in this directory that says `plan.org` means the
|
|
one at the repository root. Nothing in `docs/` is named for a file at the root, so there is no ambiguity,
|
|
and rewriting a hundred prose mentions into `../plan.org` would have cost more in readability than it
|
|
bought in precision.
|
|
|
|
## If you have thirty seconds
|
|
|
|
Read **`BUILT.md`**. It is by far the largest document here and it is the one that pays: it holds the
|
|
reason behind every part of the compiler that exists, from why nothing is ever `dlclose`d to why the
|
|
printer is a compile-time walk over a type rather than a runtime function. It is current, it is
|
|
maintained, and deleting it would mean deriving all of it again. If you want to know why a thing is the
|
|
shape it is, the answer is in here.
|
|
|
|
After that, **`../NEXT.md`** at the root for what is actually in flight, and **`REFERENCES.md`** here for
|
|
where the evidence comes from — the reference clones on this machine, what each one answers, and the
|
|
standing rule that a claim in these notes was read out of a clone rather than recalled.
|
|
|
|
## The current documents
|
|
|
|
| File | What it is |
|
|
|---|---|
|
|
| `BUILT.md` | Why the parts that exist are shaped the way they are. The longest and the most load-bearing document in the repository. **Current.** |
|
|
| `DISCUSS.md` | Open questions, raised and deliberately not answered. Nothing in it is a decision or a task; entries that have since been answered say so and point at where the answer landed. **Current**, though it is half archive by now. |
|
|
| `PORTING.md` | What the author's game, `siam-farmer`, needs from Flan that Flan does not have yet, measured against the code that exists rather than against a plan. It is the requirements document the language is actually steering by. **Current.** |
|
|
| `REFERENCES.md` | The reference clones under `~/Repositories`, what each one is consulted for, and the specific files and lines already cited from them. **Current.** |
|
|
|
|
## The reports
|
|
|
|
| File | What it is |
|
|
|---|---|
|
|
| `SPIKE-GENERICS.md` | Milestone 5's parametric polymorphism, run early and out of order as a spike. The spike succeeded and generics landed, so this is the report of finished work rather than a live plan — but its findings about where the cost falls are still the reason the implementation looks the way it does. **Historical, findings still stand.** |
|
|
| `overview.md` | The first brainstorm, from before the language had S-expressions. It says in its own first line that it is superseded and no longer accurate. Kept for history only; its table of what changed is the only part worth reading. **Superseded.** |
|
|
|
|
## `handoffs/`
|
|
|
|
One report per work session, each written by whoever held the branch at the time. They are the
|
|
operational record: what was attempted, what was measured, what was decided without being able to ask,
|
|
and what was left open for the next lane. They are all historical the moment they are written — a handoff
|
|
describes a session that has ended — but they are cited by name from source comments and from `NEXT.md`,
|
|
because the reasoning behind a guard or a calling convention is often only written down once and this is
|
|
where it was written.
|
|
|
|
Six of them are the hand-written x86-64 backend, read in the order the work happened:
|
|
`handoffs/HANDOFF-x86-rt.md` set the remaining-items list that the four after it close, `handoffs/HANDOFF-x86-redef.md`
|
|
built the redefinition emitter, `handoffs/HANDOFF-x86-aggregates.md` took that across the struct boundary,
|
|
`handoffs/HANDOFF-x86-guards.md` settled the two guards nothing reaches, `handoffs/HANDOFF-x86-debug.md` added debug
|
|
information, and `handoffs/HANDOFF-x86-cost.md` measured what the backend costs and set the survey running on its
|
|
own so a refusal cannot sit unnoticed again.
|
|
|
|
The other six sessions are unrelated to each other. `handoffs/HANDOFF-arith.md` is why a divide by zero is a condition
|
|
rather than a `SIGFPE`. `handoffs/HANDOFF-raylib-ports.md` is the running record of the last two raylib example
|
|
ports, whose lasting findings were folded into `PORTING.md`, and `handoffs/HANDOFF-cimport-ptr.md` is the arm
|
|
`cimport.ml`'s header check had been promising in a comment and not implementing — which is what those two ports
|
|
found, worked around and wrote up. `handoffs/HANDOFF-devtest-noise.md` is the linker
|
|
error `dune test` used to print on every run. `handoffs/HANDOFF-emacs-flake.md` is the `test_emacs` flake that
|
|
turned out to be `SIGPIPE` killing the daemon mid-reply, and it is worth reading for the two mechanisms it
|
|
rules out as much as for the one it found. `handoffs/HANDOFF-tidy.md` is this reorganisation.
|