naga-cli

naga-cli (naga-cli/) is the command-line interface for naga. It's the fastest way to iterate on shader translation without having to spin up a full wgpu application.

Purpose

• Validate a single WGSL/GLSL/SPIR-V source file.
• Convert a shader from one language to another.
• Dump the Naga IR for inspection.
• Dump the SPIR-V control-flow graph as GraphViz DOT.

Installation

cargo install naga-cli                                     # release
cargo install naga-cli --git https://github.com/gfx-rs/wgpu.git  # development

The development install is what naga maintainers typically use; the published version may lag behind the in-tree code.

Examples (from naga/README.md)

naga my_shader.wgsl                              # parse + validate; print result
naga my_shader.spv my_shader.txt                 # dump IR
naga my_shader.spv my_shader.metal --flow-dir d  # SPV → MSL, plus DOT flow graph in d/
naga my_shader.wgsl my_shader.vert --profile es310  # WGSL → GLSL ES 3.10

The "decide what to do" rules are based on file extensions: input extension picks the frontend, output extension picks the backend. If you don't pass an output, naga only validates.

Command-line surface

The crate uses argh for argument parsing. Notable flags:

• --flow-dir <DIR> — write SPIR-V flow graphs as DOT.
• --profile <PROFILE> — GLSL profile string for the GLSL backend (vs310, es310, etc.).
• --shader-stage <STAGE> — pick a stage manually if the file has multiple entry points.
• --validation-flags <FLAGS> — pass through validator flags.
• --bounds-check-policy <POLICY> — pick the bounds-check policy emitted by backends.

Run naga --help for the up-to-date list.

Integration points

• Above: developer / CI.
• Below: naga (with a comprehensive feature set: every front-end and every back-end).

Entry points for modification

If you're adding a flag, edit the argument-parsing block in naga-cli/src/. If you're adding a new translation path, the relevant work usually lives in naga itself; the CLI only routes inputs to outputs based on extension.