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.