Compiler architecture
Trace the compiler pipeline and find an existing implementation to follow for a change.
This page follows source text through the compiler and host. It names the entry points and data structures at each boundary, then gives starting files and existing examples for common changes.
The path of a program
This diagram follows the normal source surface. The parser lexes internally; the checking and compilation wrappers also collect diagnostics at their boundaries.
source text
-- lexer::lex3 --> tokens (Lexed)
-- Parser::module inside syn3::parse_module --> syn3::ast::Module
-- syn3::lower::lower --> ast::Module (older syntax tree)
-- resolve_parsed / resolve::resolve --> hir::Program
-- types::check_selected --> types::Typed alongside hir::Program
-- lower::lower_tests_numeric (including control::split) --> ir::Program
-- emit::wat / wat::parse_str --> Wasm bytes
-- ilang_cli::optimize / ilang_binaryen::optimize --> optimized Wasm
-- Built::host_program / Program::from_bytes --> host Program
-- Program::run_entry --> Outcome At optimisation level 0 the CLI returns the unoptimized bytes. At levels 2 and 3 it calls Binaryen and validates the result.
Packages and source
The CLI library exposes load and build, with BuildOptions and Built. The package loader assembles a PackageGraph, containing packages, modules, and Sources. Its manifest reader and module discovery are the starting points for package layout changes.
Syntax
lexer.rs produces tokens and spans. syn3/parse.rs builds the tree defined in syn3/ast.rs. The public ilang_syntax::parse_module calls syn3::parse_lowered, which uses syn3/lower.rs to produce the older ast.rs tree read by the checker. The old tree and this syntax lowering are planned to go in the tree rewrite; they are present here.
Resolution and checking
The checker entry points assemble Parsed modules, resolve them, and return Checked, with an optional hir::Program, optional types::Typed, and diagnostics. resolve.rs resolves names; order.rs orders top-level values. hir.rs defines resolved identifiers, expressions, and patterns. types/mod.rs defines solver types and dispatches checking.
Macros
ilang-macro coordinates macro preparation, execution, and expansion. session.rs, item_phase.rs, and typed.rs are useful entry points. Prepared holds macro bindings and syntax templates; Session tracks invocation marks and expansion depth, and Transaction holds effects until validation succeeds. Expansion transforms parsed modules and calls back into checking.
Wasm and optimization
ilang-wasm’s entry points accept HIR and Typed. lower.rs produces the A-normal intermediate form defined in ir.rs. control.rs splits functions around suspending calls. emit/mod.rs emits WAT, which is encoded to Wasm and validated. ilang-binaryen invokes the linked optimizer.
Host and tools
ilang-host embeds Wasmtime. Program holds a compiled module and interface; Instance executes it, and a call returns an Outcome. The CLI selects commands; the native runner starts packaged executables. The language server answers editor requests using checker queries and the syntax formatter.
Where to start for a kind of change
| Change | Existing example to follow |
|---|---|
| A diagnostic | Start with the stable code constants in check/lib.rs. In resolve.rs, module_of emits UNKNOWN_NAME (E0201), with a span and a message, when a module name cannot be found. Add a diagnostic case in the relevant test layer. |
| A built-in/core function | Follow bit_size: its declaration is in lib/i/core.i, its name and runtime mapping are in CORE and CORE_FUNCS in wasm/lower.rs, and $core_bit_size is implemented in runtime/core.rs. runtime/tests.rs exercises it. |
| A std function | Follow bool.not in std/src/bool.i: export, doc comment, and an ordinary function body. std/test/bool_test.i has the corresponding true/false tests. |
| A formatter rule | syn3/print.rs contains the layout rules; data_item writes labelled items as name = value, and data chooses their layout. Follow formatter_layout in tests/syn3.rs and its formatting stability checks. |
| An LSP feature | Follow hover in server.rs: advertise the capability, handle the request, query the checked program, and convert positions and ranges. protocol.rs includes hover_on_a_local_name_uses_the_names_of_the_scheme. |