Frontend

Active contributors: andrewrk, mlugg, vexu, jacobly, alexrp

Purpose

The Zig frontend — tokenization, parsing, AST construction, and ZIR generation — lives in lib/std/zig/. It is part of the standard library, not the compiler, so user programs (and tools like zig fmt, zig ast-check, autodoc, the LSP, formatters) can use it directly.

Directory layout

lib/std/zig/
├── Ast.zig             # AST data structure (~149 KB)
├── Ast/                # rendering helpers
├── AstGen.zig          # AST → ZIR (~576 KB, the single largest stdlib file)
├── AstRlAnnotate.zig   # result-location annotator (~43 KB)
├── BuiltinFn.zig       # @builtin function table (~22 KB)
├── ErrorBundle.zig     # diagnostics container (~33 KB)
├── LibCDirs.zig        # libc directory discovery
├── LibCInstallation.zig# libc install record parsing
├── Parse.zig           # parser (~136 KB)
├── Server.zig          # JSON-RPC server (used by `zig std` and others)
├── Client.zig          # JSON-RPC client
├── WindowsSdk.zig      # Windows SDK detection (~46 KB)
├── Zir.zig             # ZIR encoding (~210 KB)
├── Zoir.zig            # ZON IR
├── ZonGen.zig          # ZON parser → Zoir (~36 KB)
├── c_translation/      # helpers used by translate-c
├── llvm/               # LLVM target descriptor mappings
├── number_literal.zig
├── parser_test.zig     # parser fixtures
├── perf_test.zig       # parser micro-benchmarks
├── primitives.zig      # built-in primitives table
├── string_literal.zig
├── system/             # OS detection helpers
├── system.zig          # system info (~49 KB)
├── target.zig          # target detection (~25 KB)
└── tokenizer.zig       # the tokenizer (~63 KB)

Key abstractions

Type	File	Description
Ast	lib/std/zig/Ast.zig	Concrete AST: nodes, tokens, extra_data, errors. Exposes parse, render, and traversal helpers.
Tokenizer	lib/std/zig/tokenizer.zig	Streaming tokenizer; scans a Zig source slice.
Parser (internal)	lib/std/zig/Parse.zig	Recursive-descent parser. Emits Ast.
AstGen	lib/std/zig/AstGen.zig	Lowers an Ast to a Zir.
Zir	lib/std/zig/Zir.zig	Encoded ZIR: opcode-tagged instructions, extra data, declarations.
BuiltinFn	lib/std/zig/BuiltinFn.zig	Table of @-prefixed builtin functions.
Zoir, ZonGen	lib/std/zig/Zoir.zig, lib/std/zig/ZonGen.zig	ZON parsing and IR.
ErrorBundle	lib/std/zig/ErrorBundle.zig	Aggregated diagnostics, used by tooling and by Compilation.
Server, Client	lib/std/zig/Server.zig, lib/std/zig/Client.zig	JSON-RPC plumbing for zig std, autodoc, and other tools.
LibCInstallation, LibCDirs, WindowsSdk	same names	System library/SDK discovery.

How it works

graph LR
  src["Zig source"] --> Tok["Tokenizer"]
  Tok -->|tokens| P["Parse"]
  P -->|Ast| RL["AstRlAnnotate"]
  RL -->|annotated Ast| AG["AstGen"]
  AG -->|Zir| Sema["src/Sema.zig"]
  src2["zig fmt"] --> Tok2["Tokenizer"]
  Tok2 --> P2["Parse"]
  P2 --> Render["Ast.render"]
  Render --> Out["formatted source"]

• Two-pass parser. The tokenizer is single-pass; the parser is recursive-descent over an arena. Errors are recorded in Ast.errors and rendered by ErrorBundle.
• Result-location annotation. AstRlAnnotate runs over the AST before AstGen to compute where each expression's result is stored. This is what enables var x = if (...) a else b; style without temporaries.
• AstGen produces ZIR. AstGen.zig is a giant per-node lowering; the output is a flat instruction stream consumed by src/Sema.zig. ZIR is intentionally untyped — types are recovered by Sema.

Integration points

• Compiler. src/Compilation.zig calls std.zig.AstGen per file; src/Sema.zig consumes ZIR.
• zig fmt. src/fmt.zig uses std.zig.Ast.render directly.
• zig ast-check. Same parse path; reports errors and exits.
• Autodoc / zig std. lib/compiler/std-docs.zig parses every stdlib file and emits HTML.
• Tools. tools/docgen.zig and tools/doctest.zig parse Zig snippets out of the language reference.
• LSPs. External LSPs link against this same module.

Entry points for modification

• New token / keyword. Edit lib/std/zig/tokenizer.zig (table) and lib/std/zig/Parse.zig (production). Update lib/std/zig/primitives.zig if it is a primitive.
• New AST node. Add a tag to Ast.Node.Tag, the parser production, the renderer in Ast/, and a lowering in AstGen.zig.
• New ZIR opcode. Add it to Zir.Inst.Tag, lower it from AstGen, then handle it in src/Sema.zig.
• New @builtin. Add to BuiltinFn.zig, lower in AstGen, analyze in Sema.
• Formatter tweak. Edit lib/std/zig/Ast/'s render functions.

Key source files

File	Purpose
lib/std/zig/tokenizer.zig	Tokenizer.
lib/std/zig/Parse.zig	Parser.
lib/std/zig/Ast.zig	AST + rendering.
lib/std/zig/AstRlAnnotate.zig	Result-location annotation.
lib/std/zig/AstGen.zig	AST → ZIR.
lib/std/zig/Zir.zig	ZIR encoding.
lib/std/zig/ZonGen.zig	ZON parsing.
lib/std/zig/BuiltinFn.zig	Builtin table.
lib/std/zig/ErrorBundle.zig	Diagnostics.
lib/std/zig/system.zig	System / OS detection.
lib/std/zig/target.zig	Target detection.

See Compiler for what consumes the ZIR produced here.