The Compilation Pipeline

What happens between a .pkl file and machine code, phase by phase.

vlatest

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.