> Cinder 0.1.0 documentation: ADR-0004: Building wgpu-native from source through CMake
> Canonical page: https://cinder.ash10.dev/docs/adr/0004-wgpu-native-build/ · Source: `docs/adr/0004-wgpu-native-build.md` in the engine repository (engine commit 47c9352, imported 2026-11-09)
> Index of every page for agents: https://cinder.ash10.dev/llms.txt

# ADR-0004: Building wgpu-native from source through CMake

Status: Accepted, 2026-11-08

## Context

The mission requires every dependency to be vendored as a submodule and built from source with CMake
in `native/`. wgpu-native is a Rust crate (`cargo` build) that exposes `webgpu.h` and `wgpu.h`. It
cannot be compiled by CMake directly.

## Decision

- `third_party/wgpu-native` is pinned to tag `v29.0.1.1`.
- `native/CMakeLists.txt` adds an `ExternalProject` step that invokes `cargo build --release --locked`
  in the submodule using the Rust toolchain pinned by the submodule's own `rust-toolchain.toml` (or,
  when absent at that tag, the version recorded in `docs/TOOLCHAIN.md`), with `--locked` so the vendored
  `Cargo.lock` is authoritative. The produced `libwgpu_native.{so,dylib}` and the two headers are
  installed into the native build tree and linked by `libcinder_native`.
- Prebuilt release binaries from GitHub are not used, so that the exact source is auditable and
  sanitizer or debug builds can be produced when needed.

## Consequences

- The Linux CI image and the macOS runner need `rustup`; the docker toolchain image installs it.
- Build time for wgpu-native (several minutes cold) is cached in CI by `target/` hash of `Cargo.lock`.
- This is the only non-CMake build step in the tree, and it is driven by CMake, which satisfies the
  intent of the rule: one `cmake --build` builds all native code.