Target Specific Compilation

CHANGELOG.md

@@ -40,6 +40,14 @@ Bottom level categories:
 
 ## Unreleased
 
+### Major Changes
+
+#### 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).
+
 ### New Features
 
 #### Naga

Cargo.toml

@@ -16,6 +16,7 @@ members = [
     "player",
     "tests",
     "wgpu-core",
+    "wgpu-core/platform-features/*",
     "wgpu-hal",
     "wgpu-info",
     "wgpu-macros",
@@ -35,6 +36,7 @@ default-members = [
     "player",
     "tests",
     "wgpu-core",
+    "wgpu-core/platform-features/*",
     "wgpu-hal",
     "wgpu-info",
     "wgpu-macros",
@@ -72,6 +74,10 @@ 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-platform-windows-linux-android-emscripten = { version = "24.0.0", path = "./wgpu-core/platform-features/windows-linux-android-emscripten" }
+wgpu-core-platform-apple = { version = "24.0.0", path = "./wgpu-core/platform-features/apple" }
+wgpu-core-platform-wasm = { version = "24.0.0", path = "./wgpu-core/platform-features/wasm" }
+
 anyhow = { version = "1.0.95", default-features = false }
 approx = "0.5"
 argh = "0.1.13"

wgpu-core/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,41 +94,58 @@ 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"]
-
-## Enable the `dx12` backend.
-dx12 = ["wgpu-hal/dx12"]
+#! ### 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-platform-windows-linux-android-emscripten/dx12"]
+## Metal backend
+metal = ["wgpu-core-platform-apple/metal"]
+## Vulkan backend, only available on Windows, Linux, Android
+vulkan = ["wgpu-core-platform-windows-linux-android-emscripten/vulkan"]
+## OpenGL backend, only available on Windows, Linux, Android, and Emscripten
+gles = ["wgpu-core-platform-windows-linux-android-emscripten/gles"]
+
+## WebGL backend, only available on Emscripten
+webgl = ["wgpu-core-platform-wasm/webgl"]
+## OpenGL backend, on macOS only
+angle = ["wgpu-core-platform-apple/angle"]
+## Vulkan portability backend, only available on macOS
+vulkan-portability = ["wgpu-core-platform-apple/vulkan-portability"]
+## Renderdoc integration, only available on Windows, Linux, and Android
+renderdoc = ["wgpu-core-platform-windows-linux-android-emscripten/renderdoc"]
 
 [dependencies]
 naga.workspace = true
 wgpu-hal.workspace = true
 wgpu-types.workspace = true
 
+wgpu-core-platform-windows-linux-android-emscripten = { workspace = true, optional = true }
+wgpu-core-platform-apple = { workspace = true, optional = true }
+wgpu-core-platform-wasm = { workspace = true, optional = true }
+
 arrayvec.workspace = true
 bit-vec.workspace = true
 bitflags.workspace = true

wgpu-core/build.rs

@@ -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/platform-features/apple/Cargo.toml

@@ -0,0 +1,25 @@
+[package]
+name = "wgpu-core-platform-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
+
+# 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-features/apple/src/lib.rs

@@ -0,0 +1 @@
+

wgpu-core/platform-features/wasm/Cargo.toml

@@ -0,0 +1,23 @@
+[package]
+name = "wgpu-core-platform-wasm"
+version.workspace = true
+authors.workspace = true
+edition.workspace = true
+description = "Feature unification helper crate for the WebAssembly platform"
+homepage.workspace = true
+repository.workspace = true
+keywords.workspace = true
+license.workspace = true
+
+# 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]
+webgl = ["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_arch = "wasm32")'.dependencies]
+wgpu-hal.workspace = true

wgpu-core/platform-features/wasm/src/lib.rs

@@ -0,0 +1 @@
+

wgpu-core/platform-features/windows-linux-android-emscripten/Cargo.toml

@@ -0,0 +1,26 @@
+[package]
+name = "wgpu-core-platform-windows-linux-android-emscripten"
+version.workspace = true
+authors.workspace = true
+edition.workspace = true
+description = "Feature unification helper crate for the Windows/Linux/Android platforms"
+homepage.workspace = true
+repository.workspace = true
+keywords.workspace = true
+license.workspace = true
+
+# 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"]
+vulkan = ["wgpu-hal/vulkan"]
+dx12 = ["wgpu-hal/dx12"]
+renderdoc = ["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(any(windows, target_os = "linux", target_os = "emscripten", target_os = "android"))'.dependencies]
+wgpu-hal.workspace = true

wgpu-core/platform-features/windows-linux-android-emscripten/src/lib.rs

@@ -0,0 +1 @@
+