diff --git a/REFERENCES.md b/REFERENCES.md new file mode 100644 index 0000000..9fc17d5 --- /dev/null +++ b/REFERENCES.md @@ -0,0 +1,95 @@ +# Reference clones on this machine + +Read the source, do not recall it. Every claim in this repository's notes that came from one of these +was read out of the clone, and the ones that were recalled instead have been wrong before — see +`NEXT.md`'s corrections. When a note cites a file and line, it is because someone opened it. + +All paths are under `~/Repositories`. Dates are the last commit in the clone at the time this file was +written (2026-09-13); a stale clone is still the right source for how a thing works, just not for what +its newest release does. + +## The ones this language is built against + +| Clone | Last commit | What it answers | +|---|---|---| +| `Odin` | 2026-07-10 | **The primary reference.** Memory model, containers, generics. | +| `sbcl` | 2026-09-07 | Conditions and restarts — what they should *mean*. | +| `zig` | 2026-09-12 | Comptime, build system, error handling, C interop. | +| `jank` | 2026-09-11 | A Clojure with native interop and a REPL into a running process. | +| `janet` | 2025-09-29 | A small embeddable Lisp. `varfn` and its reload story. | +| `raylib` | 2026-07-16 | The C library the FFI binds. **Note:** `vendor/raylib/web/raylib-5.5/` in *this* repo is the vendored 5.5 the bindings are checked against; the clone may be a different version. | + +### Odin, specifically + +Most of what this repository copies. Places already cited in the notes: + +- `base/runtime/core.odin:369` — `Map_Info`. The type-erased container runtime: `rawptr` keys, cell + info for size and alignment, hash and equality as function pointers. This is why `Vec` and `Map` + here need no generics, and it is the thing **not** to convert when generics lands. +- `base/runtime/dynamic_map_internal.odin` — the map algorithm `(Map K V)` follows. +- `base/runtime/dynamic_array_internal.odin` — the same for `Vec`. +- `src/check_expr.cpp:470-510` — `find_or_generate_polymorphic_procedure`. The instantiation + cache: a polymorphic proc entity carries a `gen_procs` list, each call builds the concrete proc + type, and the checker scans for `are_types_identical` before generating a new `Entity`. This is + the machinery the generics spike copied. +- `src/check_type.cpp:173-200` — `FieldFlag_using` and `FieldFlag_subtype`. Odin's answer to + "a function over anything with these fields": nominal embedding, not row polymorphism. + +Two Odin facts worth keeping together, because conflating them has already caused one wrong note: +**`$T` procs are monomorphised, containers are type-erased.** Odin uses both and picks per case. + +### Also present, same family + +`odin-examples`, `ols` (the Odin language server), `odin-imgui`, +`odin-raylib-hot-reload-game-template` — the last is a worked hot-reload loop in the language this +one borrows its memory model from. + +## Lisp, conditions, and the editor loop + +| Clone | Last commit | What it answers | +|---|---|---| +| `farolero` | 2023-05-05 | Common Lisp conditions and restarts, portably — a smaller read than SBCL's for *semantics*. | +| `lem` | 2025-08-29 | An editor written in CL. Its own REPL and process model. | +| `cider` | 2026-09-10 | The Clojure editor protocol this repo's `flan-dev.el` is shaped after. | +| `emacs` | 2026-04-18 | Overlays, faces, `pre-command-hook` — the C and Lisp behind the editor half. | +| `fennel-ls` | 2026-05-06 | A Lisp language server. | +| `Carp` | 2026-08-24 | A statically typed Lisp with no GC. **The closest thing to this language's premise.** | +| `lisp` | — | assorted. | +| `cl-missile-command`, `b12n-raylib-clj`, `raylib-clojure-playground` | — | games in the Lisps, the same corpus `~/Development/fnm` ports. | + +`Carp` deserves the note it has: statically typed, no GC, Lisp syntax, borrow-checked. Whatever it +got right or wrong is the nearest prior art to what is being built here. + +## Graphics and the C boundary + +`raylib`, `raygui`, `glfw`, `SDL`, `freetype-gl`, `TIC-80`, `aseprite`, `macroquad`, `godot`, `bevy`. + +`glfw` and `SDL` matter for the window and input layer raylib sits on. `TIC-80` and `aseprite` are +real C/C++ programs to read for how they structure a frame loop. + +## Tooling, debuggers, terminals + +`tree-sitter` (grammars — relevant if the editor mode ever stops being regexp-based), `dape` (a +debug-adapter client for Emacs), `gf` (a GDB frontend), `kitty`, `st`, `ratatui`, `stumpwm`. + +`dape` and `gf` are the two to read when the debugger question comes back: this repo emits DWARF +already and `flan dev --debug` exists. + +## Everything else + +`Ambient`, `CelesteClone`, `RI-DASH`, `RichTextFX`, `controlsfx`, `openglfx`, `cljfx`, `pyimgui`, +`emsdk` (the Emscripten SDK — the web target uses it), `esp-idf`, `linux`, `fedora-kernel`, +`quickemu`, `OSX-KVM`, `tauri`, `keyd`, `alttab`, `xdg-ninja`, `jpm`, `cl-git`, `bragi`, `calm`, +`pretty`, `dash-*`, `graph-rag`, `gptel`, `neocaml`, `marian`, `brainfuck`, +`minimal_blockchain_in_rust`, `mpgameserver`, `computer_enhance`, `interactive-c-demo`, +`falconerd-editor`, `unity-paper.io-2`, `vscode-defold`, `PyPaperBot`, `RyzenAdj`, `Tug`, +`doom-themes`, `odin-webgl-experiment`. + +`emsdk` is the only one of these on a build path — the `--target=web` build needs it. + +## Related, not under `~/Repositories` + +`~/Development/fnm` — the author's own falling-sand and siam-farmer ports in Clojure, Common Lisp, +jank, Janet, Odin, OCaml and JS. `PORTING.md` in this repository is the report written from reading +them, and `sand.flan` is kept at parity with `lisp/sand.lisp`, `clojure/src/fnm/sand.clj` and +`src/fnm/sand.jank`.