Target Specific Compilation (#7076)

Author: cwfitzgerald

CHANGELOG.md

@@ -51,6 +51,12 @@ also allows more easily creating these structures inline.
 
 By @cwfitzgerald in [#7133](https://github.com/gfx-rs/wgpu/pull/7133)
 
+#### All Backends Now Have Features
+
+Previously, the `vulkan` and `gles` backends were non-optional on windows, linux, and android and there was no way to disable them. We have now figured out how to properly make them disablable! Additionally, if you turn on the `webgl` feature, you will only get the GLES backend on WebAssembly, it won't leak into native builds, like previously it might have.
+
+By @cwfitzgerald in [#7076](https://github.com/gfx-rs/wgpu/pull/7076).
+
 #### `device.poll` Api Reworked
 
 This release reworked the poll api significantly to allow polling to return errors when polling hits internal timeout limits.

Cargo.lock

@@ -16,6 +16,7 @@ members = [
     "player",
     "tests",
     "wgpu-core",
+    "wgpu-core/platform-deps/*",
     "wgpu-hal",
     "wgpu-info",
     "wgpu-macros",
@@ -35,6 +36,7 @@ default-members = [
     "player",
     "tests",
     "wgpu-core",
+    "wgpu-core/platform-deps/*",
     "wgpu-hal",
     "wgpu-info",
     "wgpu-macros",
@@ -74,6 +76,11 @@ wgpu-macros = { version = "24.0.0", path = "./wgpu-macros" }
 wgpu-test = { version = "24.0.0", path = "./tests" }
 wgpu-types = { version = "24.0.0", path = "./wgpu-types" }
 
+wgpu-core-deps-windows-linux-android = { version = "24.0.0", path = "./wgpu-core/platform-deps/windows-linux-android" }
+wgpu-core-deps-apple = { version = "24.0.0", path = "./wgpu-core/platform-deps/apple" }
+wgpu-core-deps-wasm = { version = "24.0.0", path = "./wgpu-core/platform-deps/wasm" }
+wgpu-core-deps-emscripten = { version = "24.0.0", path = "./wgpu-core/platform-deps/emscripten" }
+
 anyhow = { version = "1.0.95", default-features = false }
 approx = "0.5"
 argh = "0.1.13"

Cargo.toml

@@ -35,10 +35,10 @@ unexpected_cfgs = { level = "warn", check-cfg = ['cfg(wgpu_validate_locks)'] }
 [lib]
 
 [features]
-## Internally count resources and events for debugging purposes. If the counters
-## feature is disabled, the counting infrastructure is removed from the build and
-## the exposed counters always return 0.
-counters = ["wgpu-types/counters"]
+#! See docuemntation for the `wgpu` crate for more in-depth information on these features.
+
+#! ### Logging Configuration
+# --------------------------------------------------------------------
 
 ## Log all API entry points at info instead of trace level.
 ## Also, promotes certain debug log calls to info.
@@ -47,33 +47,44 @@ api_log_info = []
 ## Log resource lifecycle management at info instead of trace level.
 resource_log_info = []
 
-## Support the Renderdoc graphics debugger:
-## <https://renderdoc.org/>
-renderdoc = ["wgpu-hal/renderdoc"]
+#! ### Runtime Checks
+# --------------------------------------------------------------------
+
+## Validates indirect draw/dispatch calls. This will also enable naga's
+## WGSL frontend since we use a WGSL compute shader to do the validation.
+indirect-validation = ["naga/wgsl-in"]
 
 ## Apply run-time checks, even in release builds. These are in addition
 ## to the validation carried out at public APIs in all builds.
 strict_asserts = ["wgpu-types/strict_asserts"]
 
-## Validates indirect draw/dispatch calls. This will also enable naga's
-## WGSL frontend since we use a WGSL compute shader to do the validation.
-indirect-validation = ["naga/wgsl-in"]
+#! ### Debugging
+# --------------------------------------------------------------------
+
+## Enable lock order observation.
+observe_locks = ["dep:ron", "serde/serde_derive"]
+
+#! ### Serialization
+# --------------------------------------------------------------------
 
 ## Enables serialization via `serde` on common wgpu types.
 serde = ["dep:serde", "wgpu-types/serde", "arrayvec/serde", "hashbrown/serde"]
 
 ## Enable API tracing.
 trace = ["dep:ron", "serde", "naga/serialize"]
 
-## Enable lock order observation.
-observe_locks = ["dep:ron", "serde/serde_derive"]
-
 ## Enable API replaying
 replay = ["serde", "naga/deserialize"]
 
-## Enable creating instances using raw-window-handle
+#! ### Surface Support
+# --------------------------------------------------------------------
+
+## Enable creating surfaces using raw-window-handle
 raw-window-handle = ["dep:raw-window-handle"]
 
+#! ### Shading Language Support
+# --------------------------------------------------------------------
+
 ## Enable `ShaderModuleSource::Wgsl`
 wgsl = ["naga/wgsl-in"]
 
@@ -83,40 +94,68 @@ glsl = ["naga/glsl-in"]
 ## Enable `ShaderModuleSource::SpirV`
 spirv = ["naga/spv-in", "dep:bytemuck"]
 
+#! ### Other
+# --------------------------------------------------------------------
+
+## Internally count resources and events for debugging purposes. If the counters
+## feature is disabled, the counting infrastructure is removed from the build and
+## the exposed counters always return 0.
+counters = ["wgpu-types/counters"]
+
 ## Implement `Send` and `Sync` on Wasm, but only if atomics are not enabled.
-##
-## WebGL/WebGPU objects can not be shared between threads.
-## However, it can be useful to artificially mark them as `Send` and `Sync`
-## anyways to make it easier to write cross-platform code.
-## This is technically *very* unsafe in a multithreaded environment,
-## but on a wasm binary compiled without atomics we know we are definitely
-## not in a multithreaded environment.
 fragile-send-sync-non-atomic-wasm = [
     "wgpu-hal/fragile-send-sync-non-atomic-wasm",
-    "wgpu-types/fragile-send-sync-non-atomic-wasm",
 ]
 
-#! ### Backends, passed through to wgpu-hal
+#! ### External libraries
 # --------------------------------------------------------------------
+#! The following features facilitate integration with third-party supporting libraries.
 
-## Enable the `metal` backend.
-metal = ["wgpu-hal/metal"]
+## Enable using the `mach-dxcompiler-rs` crate to compile DX12 shaders.
+static-dxc = ["wgpu-hal/static-dxc"]
 
-## Enable the `vulkan` backend.
-vulkan = ["wgpu-hal/vulkan"]
-
-## Enable the `GLES` backend.
-##
-## This is used for all of GLES, OpenGL, and WebGL.
-gles = ["wgpu-hal/gles"]
+#! ### Target Conditional Features
+# --------------------------------------------------------------------
+# Look to wgpu-hal's Cargo.toml for explaination how these features and the wgpu-core
+# platform crates collude to provide platform-specific behavior.
+
+## DX12 backend
+dx12 = ["wgpu-core-deps-windows-linux-android/dx12"]
+## Metal backend
+metal = ["wgpu-core-deps-apple/metal"]
+## Vulkan backend, only available on Windows, Linux, Android
+vulkan = ["wgpu-core-deps-windows-linux-android/vulkan"]
+## OpenGL backend, only available on Windows, Linux, Android, and Emscripten
+gles = [
+    "wgpu-core-deps-windows-linux-android/gles",
+    "wgpu-core-deps-emscripten/gles",
+]
 
-## Enable the `dx12` backend.
-dx12 = ["wgpu-hal/dx12"]
+## WebGL backend, only available on Emscripten
+webgl = ["wgpu-core-deps-wasm/webgl"]
+## OpenGL backend, on macOS only
+angle = ["wgpu-core-deps-apple/angle"]
+## Vulkan portability backend, only available on macOS
+vulkan-portability = ["wgpu-core-deps-apple/vulkan-portability"]
+## Renderdoc integration, only available on Windows, Linux, and Android
+renderdoc = ["wgpu-core-deps-windows-linux-android/renderdoc"]
 
 ## Enable the `noop` backend.
 # TODO(https://github.com/gfx-rs/wgpu/issues/7120): there should be a hal feature
 noop = []
 
+# The target limitation here isn't needed, but prevents more than one of these
+# platform crates from being included in the build at a time, preventing users
+# from getting confused by seeing them in the list of crates.
+[target.'cfg(target_vendor = "apple")'.dependencies]
+wgpu-core-deps-apple = { workspace = true, optional = true }
+[target.'cfg(target_os = "emscripten")'.dependencies]
+wgpu-core-deps-emscripten = { workspace = true, optional = true }
+[target.'cfg(all(target_arch = "wasm32", not(target_os = "emscripten")))'.dependencies]
+wgpu-core-deps-wasm = { workspace = true, optional = true }
+[target.'cfg(any(windows, target_os = "linux", target_os = "android"))'.dependencies]
+wgpu-core-deps-windows-linux-android = { workspace = true, optional = true }
+
 [dependencies]
 naga.workspace = true
 wgpu-hal.workspace = true

wgpu-core/Cargo.toml

@@ -1,13 +1,22 @@
 fn main() {
     cfg_aliases::cfg_aliases! {
+        windows_linux_android: { any(windows, target_os = "linux", target_os = "android") },
         send_sync: { any(
             not(target_arch = "wasm32"),
             all(feature = "fragile-send-sync-non-atomic-wasm", not(target_feature = "atomics"))
         ) },
-        webgl: { all(target_arch = "wasm32", not(target_os = "emscripten"), gles) },
         dx12: { all(target_os = "windows", feature = "dx12") },
-        gles: { all(feature = "gles") },
+        webgl: { all(target_arch = "wasm32", not(target_os = "emscripten"), feature = "webgl") },
+        gles: { any(
+            all(windows_linux_android, feature = "gles"), // Regular GLES
+            all(webgl), // WebGL
+            all(target_os = "emscripten", feature = "gles"), // Emscripten GLES
+            all(target_vendor = "apple", feature = "angle") // ANGLE on Apple
+        ) },
+        vulkan: { any(
+            all(windows_linux_android, feature = "vulkan"), // Regular Vulkan
+            all(target_vendor = "apple", feature = "vulkan-portability") // Vulkan Portability on Apple
+        ) },
         metal: { all(target_vendor = "apple", feature = "metal") },
-        vulkan: { all(not(target_arch = "wasm32"), feature = "vulkan") }
     }
 }

wgpu-core/build.rs

@@ -0,0 +1,26 @@
+[package]
+name = "wgpu-core-deps-apple"
+version.workspace = true
+authors.workspace = true
+edition.workspace = true
+description = "Feature unification helper crate for Apple platforms"
+homepage.workspace = true
+repository.workspace = true
+keywords.workspace = true
+license.workspace = true
+readme = "README.md"
+
+# Override the workspace's `rust-version` key. Firefox uses `cargo vendor` to
+# copy the crates it actually uses out of the workspace, so it's meaningful for
+# them to have less restrictive MSRVs individually than the workspace as a
+# whole, if their code permits. See `../README.md` for details.
+rust-version = "1.76"
+
+[features]
+metal = ["wgpu-hal/metal"]
+angle = ["wgpu-hal/gles", "wgpu-hal/renderdoc"]
+vulkan-portability = ["wgpu-hal/vulkan", "wgpu-hal/renderdoc"]
+
+# Depend on wgpu-hal conditionally, so that the above features only apply to wgpu-hal on this set of platforms.
+[target.'cfg(target_vendor = "apple")'.dependencies]
+wgpu-hal.workspace = true

wgpu-core/platform-deps/apple/Cargo.toml

@@ -0,0 +1,3 @@
+This crate exists to allow platform and feature specific features work correctly. The features
+enabled on this crate are only enabled on `target_vendor = "apple"` platforms. See wgpu-hal's `Cargo.toml`
+for more information.

wgpu-core/platform-deps/apple/README.md

@@ -0,0 +1,3 @@
+//! This crate exists to allow platform and feature specific features work correctly. The features
+//! enabled on this crate are only enabled on `target_vendor = "apple"` platforms. See wgpu-hal's `Cargo.toml`
+//! for more information.

wgpu-core/platform-deps/apple/src/lib.rs

@@ -0,0 +1,24 @@
+[package]
+name = "wgpu-core-deps-emscripten"
+version.workspace = true
+authors.workspace = true
+edition.workspace = true
+description = "Feature unification helper crate for the Emscripten platform"
+homepage.workspace = true
+repository.workspace = true
+keywords.workspace = true
+license.workspace = true
+readme = "README.md"
+
+# Override the workspace's `rust-version` key. Firefox uses `cargo vendor` to
+# copy the crates it actually uses out of the workspace, so it's meaningful for
+# them to have less restrictive MSRVs individually than the workspace as a
+# whole, if their code permits. See `../README.md` for details.
+rust-version = "1.76"
+
+[features]
+gles = ["wgpu-hal/gles"]
+
+# Depend on wgpu-hal conditionally, so that the above features only apply to wgpu-hal on this set of platforms.
+[target.'cfg(target_os = "emscripten")'.dependencies]
+wgpu-hal.workspace = true

wgpu-core/platform-deps/emscripten/Cargo.toml

@@ -0,0 +1,3 @@
+This crate exists to allow platform and feature specific features work correctly. The features
+enabled on this crate are only enabled on `target_os = "emscripten"` platforms.
+See wgpu-hal's `Cargo.toml` for more information.