diff options
Diffstat (limited to 'ONBOARD.md')
| -rw-r--r-- | ONBOARD.md | 46 |
1 files changed, 36 insertions, 10 deletions
@@ -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 |