gfx-rs/wgpu

Getting started

This page describes how to build and run the code in this repository as a contributor. If you only want to use wgpu from another project, add wgpu = "29" to your Cargo.toml and follow the Learn Wgpu tutorial instead.

Prerequisites

A Rust toolchain matching rust-toolchain.toml (currently nightly is not required; rustup will pick the right stable toolchain when you first run cargo). The repository's MSRV policy is documented in README.md:
- wgpu MSRV: 1.87
- wgpu-core, wgpu-hal, wgpu-types, naga MSRV: 1.87
- Everything else in the workspace: 1.93 (workspace.package.rust-version in Cargo.toml).
The Vulkan SDK from https://vulkan.lunarg.com/sdk/home, with its bin/ on PATH. Tests use VK_LAYER_KHRONOS_validation; without it some tests will pass when they shouldn't.
Taplo for formatting *.toml. CI checks formatting.
cargo-nextest — cargo install cargo-nextest. cargo xtask test calls it.
For the DX12 backend on Windows: a recent dxcompiler.dll (≥ v1.8.2502) on PATH, or build with the static-dxc feature.
For running the WebGPU CTS: a working Deno runtime, although cargo xtask cts will fetch and use what it needs.

Build

cargo build                         # build the default workspace (wgpu, wgpu-core, wgpu-hal, naga, examples, ...)
cargo build -p wgpu                 # build only the wgpu crate
cargo build -p naga --all-features  # build naga with every front- and backend

Don't pass --release unless you specifically need it; debug builds are much faster and CI is happy with them.

Test

cargo xtask test                    # the canonical entry point — runs nextest with the right wiring
cargo nextest run -p naga           # naga unit + snapshot + validation tests
cargo nextest run --test wgpu-validation
cargo nextest run --test wgpu_trace

xtask test runs the GPU integration tests against your system's default GPU. The full picture of which test crates exist and what they do is in how-to-contribute/testing.md.

To run the WebGPU Conformance Test Suite:

cargo xtask cts                                      # default test list (cts_runner/test.lst)
cargo xtask cts 'webgpu:api,operation,buffers:*'     # a single suite
cargo xtask cts -- --list 'webgpu:...'               # list, don't run

CTS test list files live in cts_runner/test.lst, cts_runner/fail.lst, and cts_runner/skip.lst. AGENTS.md and cts_runner/README.md document conventions for editing them.

Run the examples

cargo run --bin wgpu-examples cube           # native
cargo xtask run-wasm                         # build and serve the wasm examples

Each entry under examples/features/src/ is a separately runnable demo (cube, water, bunnymark, ray_*, etc.). Standalone copy-and-paste-friendly examples live in examples/standalone/ (01_hello_compute, 02_hello_window, custom_backend).

The web examples are pre-published at https://wgpu.rs/examples/.

Pick a backend

Tests, examples, and Instance::from_env honor a small set of environment variables. The full list is in reference/configuration.md, but the most useful ones are:

Variable	Effect
`WGPU_BACKEND`	Comma-separated subset of `vulkan,metal,dx12,gl`.
`WGPU_ADAPTER_NAME`	Case-insensitive substring of the adapter name.
`WGPU_DX12_COMPILER`	`dxc`, `static-dxc`, or `fxc`.
`WGPU_POWER_PREF`	`low` or `high` for adapter selection.

The Deno-side equivalents (DENO_WEBGPU_BACKEND, ...) only apply when running through cts_runner or deno_webgpu.

Format and lint

cargo fmt
cargo clippy --tests

CI fails on warnings (RUSTFLAGS=-D warnings). clippy.toml and the [workspace.lints.clippy] block in Cargo.toml set a few extra rules (e.g. ref_as_ptr is a warn, large-error-threshold is set in clippy.toml). Each crate's lib.rs has its own #![warn(...)]/#![allow(...)] set; matching the surrounding style is preferred over adding new allow attributes.