# 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/raylib-5.5.h` in *this* repo is the committed header the bindings are checked against on every build; the clone may be a different version. It used to be whatever `vendor/raylib/web/` happened to hold, which is gitignored and therefore absent from a fresh worktree — the reason the header is tracked now. |

### 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 that was **not** converted when generics
  landed — `Vec` and `Map` are still type-erased, and a `$t` only reaches them as an
  element or key type.
- `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.
- `core/encoding/json/` — what `vendor/json` is written against. Three facts were read out of it
  rather than recalled. `tokenizer.odin` allocates nothing and hands back the raw literal including
  its quotes, while `parser.odin:320` `unquote_string` does the copy against an allocator — which is
  the split `vendor/json` copies, and the reason its `string-of` is the only function in the package
  that allocates. `parser.odin:388` clones even when the literal holds no escape at all, and
  `types.odin:96` `destroy_value` frees every `String` it walks — together those settle that a
  `Value` owns its strings unconditionally, which is what lets one `free-all` take a whole document.
  And `types.odin:49` sets `DEFAULT_SPECIFICATION` to JSON5, not JSON: `vendor/json` deliberately
  does not follow that one, and every refusal in it that names a dialect names this difference.

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

## Compiling to JavaScript

Cloned 2026-09-17, for the JS backend (FIX.org item 6, docs/DISCUSS.md §5).

| Clone | What it answers |
|---|---|
| `Fable` | **The best semantic match**: statically typed F# to readable JS, value-semantics structs, real i64/u64. `src/fable-library-ts/Long.ts`, `Int32.ts`, `BigInt.ts` for how .NET integer semantics live on JS numbers; `src/Fable.Transforms/` for how a typed AST lowers, including where structs get cloned at assignment and call sites. Large — read it for specific answers, not through. |
| `squint` | A small Clojure-syntax-to-JS compiler. `src/squint/compiler.cljc` is the emitter to read for output style and structure. |
| `clojurescript` | The full-size version of the same problem, including host interop. Consult, don't read through. |

The Lisp-to-JS pair never faces the two hard questions here — integer width and struct copy
semantics — because they are dynamic. Fable does, which is why it is on this list despite being
neither a Lisp nor small.

## 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`.