The Compilation Pipeline
What happens between a .pkl file and machine code, phase by phase.
The compiler is organised as a straight line of phases.
| Phase | What it does |
|---|---|
| Lex | Bytes to tokens. Newline is a real token, which is why statements are newline separated. |
| Parse | Tokens to an AST. Declarations, statements and expressions; the AST keeps spans for diagnostics. |
| Frontend | Finds the manifest, builds the module graph, loads every import, merges them into one program, and runs the rewriter pass. |
| Check | Type checking. Also owns the table that maps a message to a stable code when a diagnostic is raised without one. |
| Resolve | The builtin registry: every println, len, min and the rest, with their arities and result types. |
| Emit | Lowers the checked AST to PickleIR. |
| Backend | Lowers PickleIR to x86-64 machine code, in memory for run or as an object file for build, and links it. |
Two entry points, one difference
The frontend stops after the rewriter. The checked entry point runs the frontend
and then type-checks the result. The check subcommand uses the second, which
is why pickle check type-checks without generating any code: the fastest loop
in the toolchain.
The rewriter
The rewriter runs between parsing and checking, which is where desugaring
lives. It is the reason a few forms are easier to write than they look in the
AST. A single-expression => body and a block whose last expression is the
return value are normalized here, so fn f() -> int { a + b } and
fn f() -> int => a + b are the same function by the time the checker sees
them.
Module resolution happens first
The frontend is where picklescript.toml is read. Only the directories listed
under [workspace] members are searched, and the std prefix maps to
stdlib/. A module that is not reachable through the manifest is
E0206 module not found, which is a resolution failure rather than a missing
file.
Because resolution is a graph walk, a diagnostic in an imported module is reported against that module's own file and span, not the importing one.
