diff --git a/design/comptime-compiler-api.md b/design/comptime-compiler-api.md index c93fb648..aafef64d 100644 --- a/design/comptime-compiler-api.md +++ b/design/comptime-compiler-api.md @@ -148,12 +148,38 @@ special paths: lexer/parser token + sema handling (`src/lexer.zig`, `src/parser. registration in `compiler_hooks.zig` (the registry stays, re-homed under `compiler`). sx footprint is tiny (2 lines in `library/modules/build.sx`). +## Code anchors (confirmed 2026-06-17) + +Foundation that ALREADY exists: +- `#library "name"` lexes (`hash_library`, `src/lexer.zig:91`) and parses into a + `library_decl { lib_name, name }` AST node (`src/parser.zig:210`). So + `compiler :: #library "compiler";` works today (used for FFI libs like raylib). +- `extern` / `export` are keywords (`src/token.zig:46`, `kw_extern`/`kw_export`). + +New work for Phase 1: +- **Lexer/parser**: the `(.zig)` ABI qualifier on `extern`, and the trailing + `` identifier — `… extern(.zig) ` postfix on FN decls (after the + return type, beside `#builtin`/`#compiler` at `src/parser.zig:233`/`:315`) and + STRUCT decls (beside `struct #compiler`, `src/parser.zig:953`). +- **AST**: an abi/layout-binding field on `FnDecl` and the struct decl (`abi: + .c | .zig`, `lib: ?name`). +- **Binding registry**: re-home / generalize `src/ir/compiler_hooks.zig` (today's + `#compiler` registry) into the `compiler` lib's type+function registry, keyed by + exported sx name → Zig type (`@offsetOf` layout) / Zig fn (host-call). +- **Layout + emit**: sx struct layout (`src/ir/types.zig` / lowering) honors the + bound type's offsets; LLVM emission (`src/backend/llvm/types.zig`) hits them. +- **Host-call bridge**: extend the comptime path (`src/ir/host_ffi.zig` + + `interp.zig`) to dispatch `compiler` functions to their registered Zig fns, + comptime-only. + ## Build order (each phase keeps `zig build test` green) -1. **`extern(.zig)` + `#library` foundation** — lex/parse the postfix attribute and - `#library "compiler"`; a binding registry (sx name → Zig type/fn); the layout - engine honoring the bound type's `@offsetOf` offsets + LLVM emission that hits - them; **build-time layout-equality assertion**. Prove with `Field` (two u32s). +1. **`extern(.zig)` + `#library` foundation** — parse the postfix attribute (the + `#library` decl already exists); a binding registry (sx name → Zig type/fn); + the layout engine honoring the bound type's `@offsetOf` offsets + LLVM emission + that hits them; **build-time layout-equality assertion**. Prove with `Field` + (two u32s). First testable sub-step: `extern(.zig) ` PARSES on a fn decl + (parser unit test), AST carries the binding — no semantics yet. 2. **Weld `StructInfo`** + `StringId` accessors (`intern`/`text_of`) over the host-call bridge. 3. **Re-express `type_info`/`define` (struct)** as sx over `register_struct`/