Tooling

What's in the toolbox: build automation, formatters, linters, CI workflows, bots.

xtask — the repo's automation crate

xtask/src/main.rs dispatches to subcommands implemented in sibling files. Run with cargo xtask <command>.

Subcommand	File	What it does
cts	xtask/src/cts.rs	Build and run the WebGPU CTS via Deno. Pinned revision in cts_runner/revision.txt.
test	xtask/src/test.rs	Run all (or a subset of) test crates via cargo-nextest. Adds shims for Agility SDK, WARP, and code coverage.
run-wasm	xtask/src/run_wasm.rs	Build the wasm examples and serve them locally.
changelog	xtask/src/changelog.rs	Audit CHANGELOG.md to ensure all changes are under Unreleased. Used by CI on PRs.
miri	xtask/src/miri.rs	Run miri-compatible tests under miri. Requires nightly.
vendor-web-sys	xtask/src/vendor_web_sys.rs	Re-vendor web-sys WebGPU bindings from wasm-bindgen.
install-warp	xtask/src/install_warp.rs	Install Microsoft WARP DLL for software DX12 testing.
install-agility-sdk	xtask/src/install_agility_sdk.rs	Install D3D12 Agility SDK for up-to-date runtime.

A second xtask crate exists at naga/xtask/ for naga-specific automation. Most relevant: cargo xtask validate <backend> validates checked-in snapshot output with external compilers (SPIRV-Tools, glslang, DXC, FXC, GraphViz, Xcode CLI).

Formatters

• cargo fmt — workspace-wide. The root rustfmt.toml is empty; defaults apply.
• taplo fmt — *.toml files. Config: taplo.toml. Excluded paths via .prettierignore.
• prettier — Markdown, YAML, JS. Config: .prettierrc.toml, .prettierignore.

Linters and static analysis

• Clippy — cargo clippy --tests. Workspace lints in Cargo.toml's [workspace.lints.clippy]; per-crate #![warn]/#![allow] blocks add more. Project-wide config in clippy.toml (e.g. disallowed-types, large-error-threshold).
• rustdoc — cargo doc runs in CI with RUSTDOCFLAGS=-D warnings. Broken intra-doc links are errors.
• typos — config in typos.toml. Catches typos in source and docs.
• cargo-deny — config in .deny.toml. Audits the dependency tree for advisories, license compliance, banned crates, duplicate versions.
• lock-analyzer — lock-analyzer/ analyzes wgpu-core's lock acquisition order from a recording.

CI workflows

.github/workflows/:

Workflow	File	Trigger	What it does
CI	ci.yml	push, PR, merge_group	The main pipeline. Build, clippy, test, fmt, taplo, typos, doc, MSRV checks across Linux/Windows/macOS.
CTS	cts.yml	scheduled / manual	Runs the full CTS, not just test.lst.
Docs	docs.yml	push to trunk	Publishes API docs to https://wgpu.rs/doc/.
Generate	generate.yml	manual	Regenerates web-sys WebGPU bindings (calls cargo xtask vendor-web-sys).
Lazy	lazy.yml	scheduled	Slow / less-frequent checks (full build matrix).
Publish	publish.yml	tag	Publishes crates on a new release.
Shaders	shaders.yml	scheduled	Re-validates shader snapshots against the latest external compilers.
Changelog	changelog.yml	PR	Runs cargo xtask changelog --allow-released-changes.

.github/actions/ contains composite actions used by the workflows (caching, install-rust, install-vulkan-sdk, install-mesa, etc.).

Bot ecosystem

Browse git log --format='%an' | sort | uniq -c | sort -rn:

• bors[bot] — historical merge bot, ~1,600 commits. Replaced by GitHub's merge queue.
• dependabot[bot] — dependency updates.
• renovate[bot] — additional dependency updates (renovate.json config). Mostly used for Cargo.lock and CTS revision bumps.
• factory-droid[bot] — appears in the contributor stats but with very low volume.

Editor / IDE setup

• rust-analyzer is the recommended LSP. Some workspace members have feature-flag-heavy lib.rs; if you're working on naga it can help to temporarily enable a single backend in naga/Cargo.toml's default = [...] so analyzer reports errors clearly. naga/README.md mentions this trick.
• The .cargo/ directory at the workspace root has machine-specific cargo config; a smaller naga/.cargo/ exists for naga.

Cargo workspace structure

The workspace has 25+ members declared in the root Cargo.toml. default-members excludes cts_runner and deno_webgpu from default builds because they pull heavyweight Deno deps. To build them, name them explicitly:

cargo build -p cts_runner
cargo build -p deno_webgpu

Patches in [patch.crates-io] pin a couple of dependencies to git revisions (a hot-fixed env_logger and libtest-mimic). wgpu itself is patched to a path dependency so the example crates always pull in the in-tree version.

Build-time configuration

Several crates use cfg_aliases (cfg-aliases) to expose convenient cfg flags:

• wgpu/build.rs, wgpu-core/build.rs, wgpu-hal/build.rs, naga/build.rs, wgpu-types/build.rs define cfgs like wgpu_core, webgpu, web, send_sync, windows, apple, vulkan, metal, dx12, gles, noop, std.
• These shape the conditional compilation in each crate. New code that needs a cfg should reuse one of these aliases rather than spelling out target predicates.

Where to look

• Build / dependency questions: Cargo.toml and per-crate Cargo.toml. The big shared [workspace.dependencies] table at the root pins versions for every crate in the workspace.
• CI failures: .github/workflows/ci.yml. Steps reference .github/actions/.
• A new lint rule: clippy.toml plus the [workspace.lints.clippy] table in Cargo.toml.
• Adding a new test crate: register it in the root Cargo.toml's members and default-members, then teach xtask test (xtask/src/test.rs) about it if it needs special handling.