wgpu-c-backend integration test rig (v30)

inner-daemons · claude · inner-daemons · commit c8f6a8332251 · 2026-07-10T14:25:31.000-05:00
Over wgpu v30.0.0, wires wgpu's own examples/tests to run through
wgpu-native's C backend so its adapter reporting can be compared to
wgpu-core:

- wgpu Instance::new: when built with `--cfg wgpu_custom_backend`, defer to
  wgpu-native's `__wgpu_custom_backend_new_instance` symbol, unless
  WGPU_NO_CUSTOM_BACKEND=1 selects normal wgpu. wgpu calls out to the backend
  explicitly; the backend does not register itself.
- wgpu-info: restore `custom_backend_matches_wgpu_core`, which asserts the C
  backend reports identical adapter info/features/limits/downlevel/texture
  formats as wgpu-core (catches unimplemented features / unexposed limits).
  `generate(skip_custom)` toggles via the env var.
- workspace glue: add wgpu-c-backend as a member, redirect the gfx-rs git dep
  to local paths, and inject the dep + `extern crate` into crates that use
  wgpu (so the backend symbol is linked). Applied by run-wgpu-tests.py.

Co-Authored-By: Claude Opus 4.8 &lt;noreply@anthropic.com&gt;
diff --git a/Cargo.toml b/Cargo.toml
@@ -1,6 +1,6 @@
 [workspace]
 resolver = "2"
-members = [
+members = ["wgpu-c-backend",
     "cts_runner",
     "deno_webgpu",
 
@@ -30,7 +30,7 @@ members = [
     "xtask",
 ]
 exclude = []
-default-members = [
+default-members = ["wgpu-c-backend",
     "benches",
     "examples/features",
     "examples/standalone/*",
@@ -341,3 +341,10 @@ debug = true
 # Speed up image comparison even in debug builds
 [profile.dev.package."nv-flip-sys"]
 opt-level = 3
+
+# PATCH
+[patch."https://github.com/gfx-rs/wgpu.git"]
+wgpu-core = { path = "./wgpu-core" }
+wgpu-hal = { path = "./wgpu-hal" }
+wgpu-types = { path = "./wgpu-types" }
+naga = { path = "./naga" }
diff --git a/benches/Cargo.toml b/benches/Cargo.toml
@@ -50,3 +50,6 @@ serde_json.workspace = true
 termcolor.workspace = true
 tracy-client = { workspace = true, optional = true }
 wgpu.workspace = true
+
+[dependencies]
+wgpu-c-backend = { path = "../wgpu-c-backend" }
diff --git a/benches/src/lib.rs b/benches/src/lib.rs
@@ -23,6 +23,7 @@
 //!
 //! By default all tests run for 2 seconds, but this can be overridden
 //! by individual tests.
+extern crate wgpu_c_backend;
 
 use std::{collections::HashMap, io::IsTerminal, time::Duration};
 
diff --git a/examples/bug-repro/01_texture_atomic_bug/Cargo.toml b/examples/bug-repro/01_texture_atomic_bug/Cargo.toml
@@ -5,6 +5,7 @@ rust-version = "1.87"
 publish = false
 
 [dependencies]
+wgpu-c-backend = { path = "../../../wgpu-c-backend" }
 env_logger = "0.11"
 pollster = "0.4"
 wgpu = { path = "../../../wgpu" }
diff --git a/examples/bug-repro/01_texture_atomic_bug/src/main.rs b/examples/bug-repro/01_texture_atomic_bug/src/main.rs
@@ -4,6 +4,7 @@
 //! The bug does not reproduce with `MTL_SHADER_VALIDATION=1`.
 //! Known to reproduce on Apple M4 Max, macOS 26.3 (Tahoe).
 //! Dropped writes appear as various tile-shaped black holes that flicker around each frame.
+extern crate wgpu_c_backend;
 
 use std::sync::Arc;
 
diff --git a/examples/bug-repro/02_present_bugs/Cargo.toml b/examples/bug-repro/02_present_bugs/Cargo.toml
@@ -5,6 +5,7 @@ rust-version = "1.87"
 publish = false
 
 [dependencies]
+wgpu-c-backend = { path = "../../../wgpu-c-backend" }
 env_logger = "0.11"
 pollster = "0.4"
 wgpu.workspace = true
diff --git a/examples/bug-repro/02_present_bugs/src/main.rs b/examples/bug-repro/02_present_bugs/src/main.rs
@@ -2,6 +2,7 @@
 //!
 //! The 2 current bugs being tested are presentation after no usage of surface texture
 //! and queue destruction immediately after present
+extern crate wgpu_c_backend;
 
 use std::sync::Arc;
 
diff --git a/examples/features/Cargo.toml b/examples/features/Cargo.toml
@@ -28,6 +28,7 @@ webgpu = ["wgpu/webgpu"]
 exhaust = ["wgpu/exhaust"]
 
 [dependencies]
+wgpu-c-backend = { path = "../../wgpu-c-backend" }
 bytemuck.workspace = true
 cfg-if.workspace = true
 encase = { workspace = true }
diff --git a/examples/features/src/lib.rs b/examples/features/src/lib.rs
@@ -1,5 +1,6 @@
 #![allow(clippy::arc_with_non_send_sync, reason = "False positive on wasm")]
 #![warn(clippy::allow_attributes)]
+extern crate wgpu_c_backend;
 
 pub mod framework;
 pub mod utils;
diff --git a/examples/features/src/main.rs b/examples/features/src/main.rs
@@ -1,3 +1,4 @@
+extern crate wgpu_c_backend;
 struct ExampleDesc {
     name: &'static str,
     function: fn(),
diff --git a/examples/standalone/01_hello_compute/Cargo.toml b/examples/standalone/01_hello_compute/Cargo.toml
@@ -5,6 +5,7 @@ rust-version = "1.87"
 publish = false
 
 [dependencies]
+wgpu-c-backend = { path = "../../../wgpu-c-backend" }
 bytemuck = { version = "1.22.0", features = ["extern_crate_alloc"] }
 env_logger = "0.11"
 pollster = "0.4"
diff --git a/examples/standalone/01_hello_compute/src/main.rs b/examples/standalone/01_hello_compute/src/main.rs
@@ -1,3 +1,4 @@
+extern crate wgpu_c_backend;
 /// To serve as an introduction to the wgpu api, we will implement a simple
 /// compute shader which takes a list of numbers on the CPU and doubles them on the GPU.
 ///
diff --git a/examples/standalone/02_hello_window/Cargo.toml b/examples/standalone/02_hello_window/Cargo.toml
@@ -5,6 +5,7 @@ rust-version = "1.87"
 publish = false
 
 [dependencies]
+wgpu-c-backend = { path = "../../../wgpu-c-backend" }
 env_logger = "0.11"
 pollster = "0.4"
 wgpu = "30.0.0"
diff --git a/examples/standalone/02_hello_window/src/main.rs b/examples/standalone/02_hello_window/src/main.rs
@@ -1,3 +1,4 @@
+extern crate wgpu_c_backend;
 use std::sync::Arc;
 
 use winit::{
diff --git a/examples/standalone/03_hdr_surface/Cargo.toml b/examples/standalone/03_hdr_surface/Cargo.toml
@@ -5,6 +5,7 @@ rust-version = "1.87"
 publish = false
 
 [dependencies]
+wgpu-c-backend = { path = "../../../wgpu-c-backend" }
 wgpu = "30.0.0"
 winit = { version = "0.30.8", features = ["android-native-activity"] }
 
diff --git a/examples/standalone/03_hdr_surface/src/main.rs b/examples/standalone/03_hdr_surface/src/main.rs
@@ -18,6 +18,7 @@
 //! hdr10`; on the web: a `?mode=` query parameter) — to force a particular color
 //! space instead of auto-picking.
 //! Set `WGPU_BACKEND=vulkan` to force the backend.
+extern crate wgpu_c_backend;
 
 use std::sync::Arc;
 
diff --git a/examples/standalone/custom_backend/Cargo.toml b/examples/standalone/custom_backend/Cargo.toml
@@ -9,6 +9,7 @@ default = ["web"]
 web = ["wgpu/web"]
 
 [dependencies]
+wgpu-c-backend = { path = "../../../wgpu-c-backend" }
 wgpu = { version = "30.0.0", features = [
     "custom",
     "wgsl",
diff --git a/examples/standalone/custom_backend/src/main.rs b/examples/standalone/custom_backend/src/main.rs
@@ -1,3 +1,4 @@
+extern crate wgpu_c_backend;
 use std::marker::PhantomData;
 
 use custom::{Counter, CustomShaderModule};
diff --git a/tests/Cargo.toml b/tests/Cargo.toml
@@ -43,6 +43,7 @@ test-build-with-profiling = ["profiling/type-check"]
 # dev-dependencies will make the dependency graph just a bit shallower, and makes
 # `cargo clippy -- -Wunused-crate-dependencies` give fewer false positives.
 [dependencies]
+wgpu-c-backend = { path = "../wgpu-c-backend" }
 # Passthrough backend uses as_hal for the GLES backend, and there's not a great way to cfg-gate that.
 # These are all enabled for any testing on CI anyway, and won't do anything if no devices are detected.
 wgpu = { workspace = true, features = ["noop", "gles", "webgl", "angle"] }
diff --git a/tests/src/lib.rs b/tests/src/lib.rs
@@ -1,6 +1,7 @@
 //! Test utilities for the wgpu repository.
 
 #![allow(clippy::arc_with_non_send_sync, reason = "False positive on wasm")]
+extern crate wgpu_c_backend;
 
 mod config;
 mod expectations;
diff --git a/wgpu-info/Cargo.toml b/wgpu-info/Cargo.toml
@@ -11,6 +11,7 @@ license.workspace = true
 rust-version.workspace = true
 
 [dependencies]
+wgpu-c-backend = { path = "../wgpu-c-backend" }
 anyhow.workspace = true
 bitflags.workspace = true
 env_logger.workspace = true
diff --git a/wgpu-info/src/cli.rs b/wgpu-info/src/cli.rs
@@ -84,7 +84,7 @@ pub fn main() -> anyhow::Result<()> {
             crate::report::GpuReport::from_json(&json).context("Could not parse JSON")?
         }
         // Generate the report natively
-        None => crate::report::GpuReport::generate(),
+        None => crate::report::GpuReport::generate(false),
     };
 
     // Setup output writer
diff --git a/wgpu-info/src/main.rs b/wgpu-info/src/main.rs
@@ -1,5 +1,6 @@
 #![cfg_attr(target_arch = "wasm32", no_main)]
 #![cfg(not(target_arch = "wasm32"))]
+extern crate wgpu_c_backend;
 
 mod cli;
 mod human;
diff --git a/wgpu-info/src/report.rs b/wgpu-info/src/report.rs
@@ -17,7 +17,17 @@ pub struct GpuReport {
 }
 
 impl GpuReport {
-    pub fn generate() -> Self {
+    pub fn generate(skip_custom: bool) -> Self {
+        // The patched `wgpu::Instance::new` (built with `--cfg wgpu_custom_backend`)
+        // routes through wgpu-native's C backend unless `WGPU_NO_CUSTOM_BACKEND=1`.
+        // Toggle it here so a single process can produce both the custom-backend
+        // and wgpu-core reports for `custom_backend_matches_wgpu_core`. No-op on
+        // an unpatched wgpu.
+        if skip_custom {
+            std::env::set_var("WGPU_NO_CUSTOM_BACKEND", "1");
+        } else {
+            std::env::remove_var("WGPU_NO_CUSTOM_BACKEND");
+        }
         let instance = wgpu::Instance::new({
             let mut desc = wgpu::InstanceDescriptor::new_without_display_handle();
             desc.backend_options.dx12.shader_compiler = Dx12Compiler::StaticDxc;
diff --git a/wgpu-info/src/tests.rs b/wgpu-info/src/tests.rs
@@ -1,4 +1,122 @@
-use std::{fs::File, io::BufWriter};
+use std::{collections::BTreeMap, fs::File, io::BufWriter};
+
+/// Prints a pretty diff of two JSON strings via the system `diff`.
+fn unified_diff(label: &str, a: &str, b: &str) -> String {
+    use std::{fs, process::Command};
+    let dir = std::env::temp_dir();
+    let a_path = dir.join(format!("wgpu-info-{label}-custom.json"));
+    let b_path = dir.join(format!("wgpu-info-{label}-core.json"));
+    fs::write(&a_path, a).unwrap();
+    fs::write(&b_path, b).unwrap();
+    let out = Command::new("diff")
+        .args(["-u", "--label", "with-custom", "--label", "without-custom"])
+        .args([&a_path, &b_path])
+        .output()
+        .unwrap();
+    String::from_utf8(out.stdout).unwrap()
+}
+
+fn adapter_key(info: &wgpu::AdapterInfo) -> String {
+    format!("{:?}/{}", info.backend, info.name)
+}
+
+/// Normalized view of an adapter for comparison. Texture-format features are
+/// sorted by format name for deterministic JSON (HashMap order is random).
+#[derive(serde::Serialize)]
+struct NormalizedAdapter<'a> {
+    info: &'a wgpu::AdapterInfo,
+    features: &'a wgpu::Features,
+    limits: &'a wgpu::Limits,
+    downlevel_caps: &'a wgpu::DownlevelCapabilities,
+    texture_format_features: BTreeMap<String, &'a wgpu::TextureFormatFeatures>,
+}
+
+fn normalize(dev: &crate::report::AdapterReport) -> NormalizedAdapter<'_> {
+    let texture_format_features = dev
+        .texture_format_features
+        .iter()
+        .map(|(fmt, feats)| (format!("{fmt:?}"), feats))
+        .collect();
+    NormalizedAdapter {
+        info: &dev.info,
+        features: &dev.features,
+        limits: &dev.limits,
+        downlevel_caps: &dev.downlevel_caps,
+        texture_format_features,
+    }
+}
+
+fn to_json(value: &impl serde::Serialize) -> String {
+    serde_json::to_string_pretty(value).unwrap()
+}
+
+/// Guards against the wgpu-native C backend silently drifting from wgpu-core:
+/// it must report the exact same adapter info, features, limits, downlevel
+/// capabilities and texture-format features. A mismatch means the C backend
+/// hasn't yet implemented or exposed something (e.g. a new feature or limit).
+///
+/// Only meaningful when this crate is built with `--cfg wgpu_custom_backend`
+/// (and wgpu-native linked): then `generate(false)` runs through the C backend
+/// and `generate(true)` through wgpu-core. On an unpatched wgpu both runs are
+/// identical and the test trivially passes.
+#[test]
+fn custom_backend_matches_wgpu_core() {
+    use std::collections::HashMap;
+
+    let with_custom = crate::report::GpuReport::generate(false);
+    let without_custom = crate::report::GpuReport::generate(true);
+
+    let without_map: HashMap<String, &crate::report::AdapterReport> = without_custom
+        .devices
+        .iter()
+        .map(|d| (adapter_key(&d.info), d))
+        .collect();
+    let custom_map: HashMap<String, &crate::report::AdapterReport> = with_custom
+        .devices
+        .iter()
+        .map(|d| (adapter_key(&d.info), d))
+        .collect();
+
+    let mut failures: Vec<String> = Vec::new();
+
+    // Every custom-backend adapter must exist in wgpu-core and match it.
+    for custom_dev in &with_custom.devices {
+        let key = adapter_key(&custom_dev.info);
+        let Some(core_dev) = without_map.get(&key) else {
+            failures.push(format!(
+                "Adapter '{key}' present in custom-backend run but missing from wgpu-core run"
+            ));
+            continue;
+        };
+        let a = to_json(&normalize(custom_dev));
+        let b = to_json(&normalize(core_dev));
+        if a != b {
+            failures.push(format!(
+                "Adapter '{}' differs:\n{}",
+                key,
+                unified_diff(&key.replace('/', "_"), &a, &b)
+            ));
+        }
+    }
+
+    // Every wgpu-core adapter must also be present in the custom-backend run.
+    for core_dev in &without_custom.devices {
+        let key = adapter_key(&core_dev.info);
+        if !custom_map.contains_key(&key) {
+            failures.push(format!(
+                "Adapter '{key}' present in wgpu-core run but missing from custom-backend run"
+            ));
+        }
+    }
+
+    if !failures.is_empty() {
+        panic!(
+            "GpuReport differs for {} adapter(s):\n{}",
+            failures.len(),
+            failures.join("\n")
+        );
+    }
+}
 
 const ENV_VAR_SAVE: &str = "WGPU_INFO_SAVE_GPUCONFIG_REPORT";
 
@@ -10,7 +128,7 @@ const ENV_VAR_SAVE: &str = "WGPU_INFO_SAVE_GPUCONFIG_REPORT";
 // Needs to be kept in sync with the test in xtask/src/test.rs
 #[test]
 fn generate_gpuconfig_report() {
-    let report = crate::report::GpuReport::generate();
+    let report = crate::report::GpuReport::generate(false);
 
     // If we don't get the env var, just test that we can generate the report, but don't save it
     // to avoid a race condition when other tests are reading the file.
diff --git a/wgpu/src/api/instance.rs b/wgpu/src/api/instance.rs
@@ -61,6 +61,36 @@ impl Instance {
     ///   this method will panic; see [`Instance::enabled_backend_features()`].
     #[allow(clippy::allow_attributes, unreachable_code)]
     pub fn new(desc: InstanceDescriptor) -> Self {
+        // wgpu-native C-backend integration testing.
+        //
+        // When this crate is built with `--cfg wgpu_custom_backend`, route
+        // `Instance::new` through wgpu-native's C backend, which provides the
+        // `__wgpu_custom_backend_new_instance` symbol. Setting
+        // `WGPU_NO_CUSTOM_BACKEND=1` selects the normal wgpu path instead, so the
+        // two can be compared in one process (see `wgpu-info`'s
+        // `custom_backend_matches_wgpu_core` test). wgpu-native is unaware of this
+        // wiring; wgpu decides here whether to defer to it. Requires `std` (for
+        // the env read); the C backend is native-only anyway.
+        #[cfg(all(wgpu_custom_backend, std))]
+        let desc = {
+            if std::env::var("WGPU_NO_CUSTOM_BACKEND").as_deref() != Ok("1") {
+                extern "Rust" {
+                    fn __wgpu_custom_backend_new_instance(
+                        desc: InstanceDescriptor,
+                    ) -> Result<Instance, InstanceDescriptor>;
+                }
+                // SAFETY: the symbol is provided by wgpu-native (wgpu-c-backend)
+                // with exactly this Rust-ABI signature, and is only linked in the
+                // integration build.
+                match unsafe { __wgpu_custom_backend_new_instance(desc) } {
+                    Ok(instance) => return instance,
+                    Err(returned) => returned,
+                }
+            } else {
+                desc
+            }
+        };
+
         if Self::enabled_backend_features().is_empty() {
             panic!(
                 "No wgpu backend feature that is implemented for the target platform was enabled. \

Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+extern crate wgpu_c_backend;`
`1`	`2`	`struct ExampleDesc {`
`2`	`3`	`name: &'static str,`
`3`	`4`	`function: fn(),`