Naga frontends

Frontends parse source text or binary into Naga IR. They live under naga/src/front/.

Layout

naga/src/front/
├── mod.rs              shared types
├── atomic_upgrade.rs   helper for SPIR-V atomics
├── interpolator.rs     interpolation-attribute helpers
├── type_gen.rs         type emission helpers
├── wgsl/               WGSL frontend
├── glsl/               GLSL 440+ frontend (Vulkan semantics only)
└── spv/                SPIR-V binary frontend

Status

Frontend	Files	Status
WGSL	naga/src/front/wgsl/	Primary, fully validated.
SPIR-V	naga/src/front/spv/	Primary.
GLSL	naga/src/front/glsl/	Secondary. GLSL 440+ with Vulkan semantics only.

The relative status mirrors the WebGPU/wgpu integration story: WGSL is the WebGPU canonical language, SPIR-V is what users with existing pipelines often have, GLSL is supported as a convenience.

WGSL frontend

The WGSL frontend is the largest (naga/src/front/wgsl/lower/mod.rs alone is ~197 KB). It's a hand-written recursive-descent parser plus a "lowering" pass that turns AST nodes into IR.

graph LR
    Source[WGSL source] --> Lex[lex/]
    Lex --> Tokens
    Tokens --> Parse[parse/]
    Parse --> AST
    AST --> Lower[lower/]
    Lower --> Module[naga::Module]

Sub-modules:

• naga/src/front/wgsl/lex/ — token stream.
• naga/src/front/wgsl/parse/ — AST construction.
• naga/src/front/wgsl/lower/ — AST → IR lowering. Where most of the weight lives.
• naga/src/front/wgsl/error.rs — diagnostic types with span-aware formatting via codespan-reporting.

The WGSL parser is responsible for almost all of naga's user-visible diagnostics. naga/tests/naga/wgsl_errors.rs (152 KB) is the test harness for them.

WGSL's @diagnostic(...) attributes are handled by naga/src/diagnostic_filter.rs and consumed during lowering.

SPIR-V frontend

naga/src/front/spv/ is similarly large (naga/src/front/spv/mod.rs ~116 KB and next_block.rs ~140 KB). It walks the SPIR-V module, builds basic blocks, and reconstructs structured control flow as Naga's IR is structured (it doesn't model arbitrary CFGs).

Key files:

• naga/src/front/spv/mod.rs — top-level loop that consumes opcodes.
• naga/src/front/spv/next_block.rs — the structurizer.
• Plus several helpers: function.rs, image.rs, null.rs, error.rs.

Naga uses rspirv for raw SPIR-V parsing. The spirv crate (spirv = "0.4") provides the type definitions for ops, decorations, capabilities.

GLSL frontend

naga/src/front/glsl/ is the smallest of the three. It uses pp-rs for preprocessing and accepts GLSL 440+ with Vulkan semantics. Limitations are documented in naga/src/front/glsl/README.md (if present) and in the README at the crate level.

Building and testing frontends

To exercise a single frontend during iteration, naga's Cargo.toml lets you flip default features temporarily, e.g. default = ["wgsl-in", "msl-out"]. The README calls out this pattern:

default = ["spv-out"] #TEMP!

This keeps IDE checks tight while you're working on a specific path.

Tests

Test	Location	Purpose
WGSL errors	naga/tests/naga/wgsl_errors/	All diagnostic messages that the WGSL frontend produces.
Validation	naga/tests/naga/validation/	Hand-rolled validator tests for cases not covered by frontend errors.
Snapshots	naga/tests/naga/snapshot/, naga/tests/in/, naga/tests/out/	End-to-end input → output.
SPIR-V capabilities	naga/tests/naga/spirv_capabilities/	WGSL → SPIR-V → assert that the right capabilities are emitted.
example_wgsl	naga/tests/naga/example_wgsl/	Every WGSL file under examples/ parses and validates.

Modifying a frontend

• Adding language coverage to WGSL — extend parse/, lower/, and the error module. Add inputs to naga/tests/in/wgsl/ (which automatically generate output for every backend).
• Adding SPIR-V opcode coverage — add a handler in front/spv/mod.rs or function.rs. Add a fixture in naga/tests/in/spv/.
• Fixing a GLSL extension — edit front/glsl/. Tests in naga/tests/in/glsl/.

The validator should generally be the source of "is this construct allowed?" checks; frontends should focus on parsing the source and producing IR.