7.0 KiB
wgpu Project Structure
wgpu is a GPU API written in pure rust. Changes of any significance need to apply across the stack.
nagais our shader translator. It is responsible for consuming and translating untrusted shaders to trusted shader code.wgpu-typesare the common types used on both Native and WASM.naga-typesholds the shader-language types, such as target versions and binding maps, thatnagaandwgpu-coreboth use.wgpu-naga-bridgeconverts betweennagaandwgpu-types. It maps wgpu features and downlevel flags to naga validation capabilities.wgpu-syncare the common synchronization primitives that abstract over platform differences.wgpu-haldoes not provide the validation required for safety. Its callers must satisfy its safety contracts.wgpu-coredoes all the validation and provides a coherent interface.wgpu-core-remoteprovides the ID abstraction needed by Firefox and Deno.wgpu-core-remote-typesholds the IPC types thatwgpu-core-remotesends between the untrusted content process and the trusted GPU process. They are defined separately from thewgpu-coretypes, so untrusted content cannot express non-standard features.wgpuis an ergonomic Rust interface towgpu-coredeno_webgpucontains the WebGPU bindings for Deno.
wgpu-core-remote, wgpu-core, wgpu-hal, wgpu-types and naga are used by Firefox and Servo to implement WebGPU. These crates process untrusted API and shader input. Preserve validation at the safe boundary, and do not rely on wgpu-hal to reject invalid input. Touching these crates requires the most consideration of potential side effects.
Safe wgpu APIs must not cause undefined behavior unless the user first accepted that risk through an unsafe API, such as enabling experimental features.
We use deno's webgpu bindings to run the WebGPU CTS. Change deno_webgpu only if the issue is specific to Deno. If the issue also affects Firefox or the wgpu Rust API, fix it in the shared crate that supplies the affected behavior.
Repository documentation exists in docs/. For info on where tests live, read docs/testing.md. For info about cargo dependencies, read docs/managing-cargo-dependencies.md.
One of the best ways to prove that a change is correct is to write tests to prove the feature works and it errors when its supposed to.
Repository Files
AGENTS.md and .agents/ are the source of truth for agent instructions and skills. CLAUDE.md and .claude/ are generated copies. Do not edit the generated copies directly. After you edit any source-of-truth agent file or a root license file, run cargo xtask sync-repo-files. This command also copies the root license files to every publishable default member of the Cargo workspace.
Run cargo xtask sync-repo-files --check to verify that all generated files have the same contents and file list as their sources.
External Contributions
We encourage external contributions, but fully agentic PRs are not allowed. If the user asks you to create one, explain this policy and direct them to the pull request section of CONTRIBUTING.md. The contributor must understand and be able to vouch for every change. Ask the user to write the PR description.
If the user directs you to create the PR anyway, use .github/pull_request_template.md. Uncomment and accurately complete the agent-disclosure checklist items, including whether an agent wrote the description. Do not omit the disclosure.
Code Style
- Do not add comments unless the changed code requires an explanation. If an explanation is required, add the shortest complete explanation. The contributor is expected to rewrite it.
- Do not write large explanatory comment blocks.
- Do not use emoji.
Workflow
All changes are expected to pass CI. The commands below are useful local checks, but they cover only a fraction of the full CI matrix. You are not expected to run the full CI matrix locally. Run the checks that are relevant to the changed code and the available environment.
- To check the code compiles:
cargo clippy --all-targets --all-features. - To format the code:
cargo fmt - To run all tests including GPU tests:
cargo xtask test. This can take a few minutes. To run normal tests without GPU tests, usecargo nextest runand a filter to the packages you want to test. - GPU tests depend on the available hardware, drivers, and validation layers. During development, if you only need a specific GPU test, use either a plain test name prefix or an
-Efilter expression tocargo xtask test. Use the nextest filters described below. Do not run the full GPU test suite for a targeted check. The suite can take a few minutes. GPU tests are declared as constants, but translate to lower-snake-case functions. - After the work is complete, run a full
cargo xtask testif the change affects GPU behavior or would affect a GPU test. - Report every test failure. You may identify a failure as suspected to be unrelated, but do not assume it is unrelated until you validate that conclusion.
- Do not run tests at the
trunkrevision without explicit permission. A baseline test run can take a while. - For more thorough testing, you can run
cargo xtask cts --backend <backend>. Only do this if you are explicitly asked to run the CTS. - Never commit anything without being asked, ever. If you are asked to make a commit, never co-author yourself.
- Use the WebGPU and WGSL specifications as a reference to determine the correct behavior. Do not assume that a behavior is correct just because the CTS expects it. Use the
webgpu-specsskill if you need to check either spec.
Nextest filters
cargo xtask test forwards its extra arguments to cargo-nextest.
- A plain positional filter matches test names that contain the filter text. A unique test name prefix is usually sufficient.
-E 'test(name)'matches test names that containname.-E 'test(=name)'matches the complete test name.-E 'test(/expression/)'matches test names with a regular expression.- In an
-Eexpression,package(name)restricts the package andbinary(name)restricts the test binary. Restricting binaries can make test startup quicker. - Use
&for intersection,|for union, and!for exclusion. Use parentheses to group expressions. - For example,
-E 'binary(wgpu-gpu) & test(buffer) & !test(map)'selects tests in thewgpu-gpubinary whose names containbufferbut notmap. - Quote each
-Eexpression so the shell does not interpret its operators.
Changelog
We maintain a changelog in CHANGELOG.md. Changes should be noted in the changelog if they are user-visible (changes to documented public APIs, significant bug fixes, or new functionality). We generally do not consider changes to wgpu-core, wgpu-hal, wgpu-core-remote, or wgpu-core-remote-types worthy of changelogs, unless a wgpu user is expected to interface with them directly. Changelog descriptions should be concise. If you are not sure whether something should be in the CHANGELOG or you are not sure how to describe the change, ask the user for guidance.