Installation
Prerequisites
- Rust 1.87+ (stable toolchain). Install via rustup if you don’t already have it.
- A GPU with a driver supported by wgpu. Required for roundtrip tests and running example renderers. On macOS, Metal works out of the box.
Adding wgsl-rs to your project
Add wgsl-rs to your Cargo.toml with the explicit beta pin — cargo won’t
resolve a pre-release version from a bare version requirement:
cargo add wgsl-rs@0.1.0-beta.5
which adds:
[dependencies]
wgsl-rs = "0.1.0-beta.5"
The crate re-exports its proc macros, so you only need the one dependency. If you prefer to depend on the macro crate directly as well, the equivalent is:
[dependencies]
wgsl-rs = "0.1.0-beta.5"
wgsl-rs-macros = "0.1.0-beta.5"
The validation feature is enabled by default and pulls in naga to validate generated WGSL at test time. No extra configuration is required to get it.
Cargo features
| Feature | Default | Purpose |
|---|---|---|
validation | on | naga-based WGSL validation; auto-generates __validate_wgsl tests. |
dispatch-runtime | on | CPU-side fragment dispatch runtime for roundtrip testing. |
wgpu linkage generation is not a cargo feature: it lives in the separate
wgsl-rs-linkage-wgpu crate, with one cargo feature per supported wgpu major.
See Cargo Features for details on each.
Running the example crate
The repository ships an example crate containing 35+ transpiled modules. List them with:
cargo run -p example -- show
Print the generated WGSL for a specific module with:
cargo run -p example -- source hello_triangle
Verifying your setup
Run the test suite to confirm validation is working:
cargo test -p example
Each #[wgsl] module auto-generates a #[test] fn __validate_wgsl() that feeds the emitted WGSL_SOURCE through naga. If the suite passes, your installation is correct.