From ce920b6ff47f32bc06dd27124e1b882f82f3d6ae Mon Sep 17 00:00:00 2001
From: zinc <zinc@downsta.ir>
Date: Wed, 14 Oct 2026 10:05:40 +0000
Subject: split compiler.zc into files by phase

src/compiler/compiler.zc is now twelve files under src/compiler/, listed in
order in src/compiler/parts. cat of the parts in order is byte-identical to
the old file, so every compiler and image except the language server's is
unchanged. no function was edited.

consumers read the list: the makefile, bootstrap-check, genmap (which still
writes one compiler.zc into a generated map directory), tinyvm.bat,
test.sh, test_win.ps1 and the lsp drivers. the language server embeds each
part and serves them joined as the one document tinyvm:/compiler.zc.
---
 ONBOARD.md | 46 ++++++++++++++++++++++++++++++++++++----------
 1 file changed, 36 insertions(+), 10 deletions(-)

(limited to 'ONBOARD.md')

diff --git a/ONBOARD.md b/ONBOARD.md
index 5b05862..8c36fb5 100644
--- a/ONBOARD.md
+++ b/ONBOARD.md
@@ -28,7 +28,8 @@ ls; ls src src/*; ls tests docs docs/design
 
 you should be able to say: what the genome is (the compiler and runtime, compiled
 to vm words, embedded in every core), and which files make it
-(`src/runtime/rt.zc`, `src/core/core.zc`, `src/compiler/compiler.zc`).
+(`src/runtime/rt.zc`, `src/core/core.zc`, and the compiler: the files of
+`src/compiler/`, listed in order in `src/compiler/parts`).
 
 ## 1. build it from nothing
 
@@ -80,7 +81,7 @@ bash tests/runerr.sh build/bin/zy tests/typeerrors
 bash tests/runerr.sh build/bin/zy tests/langerrors
 ```
 
-in `src/compiler/compiler.zc`, find the block that starts at
+in `src/compiler/analyzer.zc`, find the block that starts at
 `// the rules below are the heart of the analyzer` and read `recast`,
 `argcheck`, `assigncheck` and `retcheck`, then `exit_vars` and the `lend_*`
 helpers.
@@ -91,18 +92,43 @@ does to them.
 
 ## 4. the compiler's structure
 
-`src/compiler/compiler.zc` is about ten thousand lines and begins with an
-overview. read the overview, then use the section markers to navigate:
+the compiler is about ten thousand lines in twelve files, one per phase, which
+the build joins in the order `src/compiler/parts` lists (one file name per line;
+every script and the makefile read that list, so a new file is added there and
+nowhere else). the files are one source cut at section boundaries, not modules:
+they share one namespace and global state, and each only makes sense after the
+ones above it. `base.zc` begins with an overview. start there, then list the
+section markers of every part:
 
 ```sh
-grep -n "^// ----" src/compiler/compiler.zc
+cat src/compiler/parts
+grep -n "^// ----" $(sed 's|^|src/compiler/|' src/compiler/parts)
 ```
 
-read in this order: interning and symbols, the lexer (`lex1`), expressions
-(`primary`, `unary`, `bin`, `expr`), statements and keywords (`add_kw` and the
-`kw_*` functions), functions (`fndef`, `fn_begin`, `prologue`), globals
-(`gdecl2`, `kw_embed`), then `chk_unit` (check mode for the language server) and
-`build_image` (image mode for `src/tools/build.zc`).
+read in this order:
+
+- `base.zc`: the overview, the data region, state, errors, interning, symbols,
+  code emission and the o3 bookkeeping
+- `lex.zc`: input sources, the lexer (`lex1`), float literals and float code
+- `ops.zc`: the operator tables a program can extend
+- `analyzer.zc`: the ownership pass (function effects, locals, joins, the rules
+  at the places values flow)
+- `types.zc`: types, parsing types, methods
+- `builtins.zc`: statements that configure the compiler, `include`, built-ins
+  that look like functions, the c abi (`extern`, `cfunc`), reflection, fattening
+  (`kw_embed` is here)
+- `expr.zc`: expressions (`primary`, `unary`, `bin`, `expr`), type facts, hints,
+  closures, array initializers, constant expressions
+- `stmt.zc`: statements, asm blocks, `quote`
+- `decl.zc`: reading a unit, functions (`fndef`, `fn_begin`, `prologue`),
+  globals (`gdecl2`), enhancements, generics
+- `image.zc`: the symbol blob and `build_image` (image mode for
+  `src/tools/build.zc`)
+- `setup.zc`: the keyword table (`add_kw` calls), built-in names, the entry point
+- `check.zc`: `chk_unit`, check mode for the language server
+
+to see the compiler as one text, as the bootstrap does, run
+`cat $(sed 's|^|src/compiler/|' src/compiler/parts)`.
 
 you should be able to say where a new keyword is registered, how a keyword
 works at the top level and inside a function, and how the compiler emits a
-- 
cgit v1.2.3