Re-export public dependencies (#5063)

CHANGELOG.md

@@ -39,6 +39,20 @@ Bottom level categories:
 
 ## Unreleased
 
+### All Public Dependencies Are Re-Exported
+
+All of wgpu's public dependencies are now re-exported at the top level so that users don't need to take their own dependencies.
+This includes:
+- wgpu-core
+- wgpu-hal
+- naga
+- raw_window_handle
+- web_sys
+
+### `naga-ir` Shaders Have Dedicated Feature
+
+The `naga-ir` feature has been added to allow you to add naga module shaders without guessing about what other features needed to be enabled to get access to it.
+
 ### Direct3D 11 backend removal
 
 This backend had no functionality, and with the recent support for GL on Desktop, which allows wgpu to run on older devices, there is no need to keep the backend.

wgpu-core/src/lib.rs

@@ -105,6 +105,7 @@ mod track;
 pub mod validation;
 
 pub use hal::{api, MAX_BIND_GROUPS, MAX_COLOR_ATTACHMENTS, MAX_VERTEX_BUFFERS};
+pub use naga;
 
 use std::{borrow::Cow, os::raw::c_char};
 

wgpu/Cargo.toml

@@ -45,7 +45,7 @@ angle = ["wgc?/gles"]
 vulkan-portability = ["wgc?/vulkan"]
 
 ## Enables the WebGPU backend on Wasm. Disabled when targeting `emscripten`.
-webgpu = []
+webgpu = ["naga?/wgsl-out"]
 
 ## Enables the GLES backend on Wasm
 ##
@@ -64,6 +64,9 @@ glsl = ["naga/glsl-in"]
 ## Enable accepting WGSL shaders as input.
 wgsl = ["wgc?/wgsl"]
 
+## Enable accepting naga IR shaders as input.
+naga-ir = ["naga"]
+
 #! ### Logging & Tracing
 # --------------------------------------------------------------------
 #! The following features do not have any effect on the WebGPU backend.
@@ -178,10 +181,6 @@ cfg_aliases.workspace = true
 workspace = true
 features = ["wgsl-in"]
 
-[target.'cfg(target_arch = "wasm32")'.dependencies.naga]
-workspace = true
-features = ["wgsl-out"]
-
 [target.'cfg(target_arch = "wasm32")'.dependencies]
 web-sys = { workspace = true, features = [
     "Document",

wgpu/build.rs

@@ -10,6 +10,9 @@ fn main() {
             all(feature = "fragile-send-sync-non-atomic-wasm", not(target_feature = "atomics"))
         ) },
         dx12: { all(target_os = "windows", feature = "dx12") },
-        metal: { all(any(target_os = "ios", target_os = "macos"), feature = "metal") }
+        metal: { all(any(target_os = "ios", target_os = "macos"), feature = "metal") },
+        // This alias is _only_ if _we_ need naga in the wrapper. wgpu-core provides
+        // its own re-export of naga, which can be used in other situations
+        naga: { any(feature = "naga-ir", feature = "spirv", feature = "glsl") },
     }
 }

wgpu/src/backend/webgpu.rs

@@ -1400,7 +1400,7 @@ impl crate::context::Context for ContextWebGpu {
             feature = "spirv",
             feature = "glsl",
             feature = "wgsl",
-            feature = "naga"
+            feature = "naga-ir"
         )),
         allow(unreachable_code, unused_variables)
     )]
@@ -1411,7 +1411,7 @@ impl crate::context::Context for ContextWebGpu {
         desc: crate::ShaderModuleDescriptor<'_>,
         _shader_bound_checks: wgt::ShaderBoundChecks,
     ) -> (Self::ShaderModuleId, Self::ShaderModuleData) {
-        let mut descriptor = match desc.source {
+        let mut descriptor: web_sys::GpuShaderModuleDescriptor = match desc.source {
             #[cfg(feature = "spirv")]
             crate::ShaderSource::SpirV(ref spv) => {
                 use naga::{back, front, valid};
@@ -1465,7 +1465,7 @@ impl crate::context::Context for ContextWebGpu {
             }
             #[cfg(feature = "wgsl")]
             crate::ShaderSource::Wgsl(ref code) => web_sys::GpuShaderModuleDescriptor::new(code),
-            #[cfg(feature = "naga")]
+            #[cfg(feature = "naga-ir")]
             crate::ShaderSource::Naga(module) => {
                 use naga::{back, valid};
 

wgpu/src/backend/wgpu_core.rs

@@ -820,7 +820,7 @@ impl crate::Context for ContextWgpuCore {
             feature = "spirv",
             feature = "glsl",
             feature = "wgsl",
-            feature = "naga"
+            feature = "naga-ir"
         )),
         allow(unreachable_code, unused_variables)
     )]
@@ -866,7 +866,7 @@ impl crate::Context for ContextWgpuCore {
             }
             #[cfg(feature = "wgsl")]
             ShaderSource::Wgsl(ref code) => wgc::pipeline::ShaderModuleSource::Wgsl(Borrowed(code)),
-            #[cfg(feature = "naga")]
+            #[cfg(feature = "naga-ir")]
             ShaderSource::Naga(module) => wgc::pipeline::ShaderModuleSource::Naga(module),
             ShaderSource::Dummy(_) => panic!("found `ShaderSource::Dummy`"),
         };

wgpu/src/lib.rs

@@ -7,25 +7,28 @@
 //!
 //! ### Backends
 //!
-//! ⚠️ WIP: Not all backends can be manually configured today. On Windows & Linux the Vulkan & GLES
-//! backends are always enabled. See [#3514](https://github.com/gfx-rs/wgpu/issues/3514) for more
+//! ⚠️ WIP: Not all backends can be manually configured today. On Windows & Linux the **Vulkan & GLES
+//! backends are always enabled**. See [#3514](https://github.com/gfx-rs/wgpu/issues/3514) for more
 //! details.
 //!
 //! - **`dx12`** _(enabled by default)_ ---   Enables the DX12 backend on Windows.
 //! - **`metal`** _(enabled by default)_ --- Enables the Metal backend on macOS & iOS.
-//! - **`angle`** --- Enables the GLES backend via [ANGLE](https://github.com/google/angle) on macOS
-//!   using.
+//! - **`webgpu`** _(enabled by default)_ --- Enables the WebGPU backend on Wasm. Disabled when targeting `emscripten`.
+//! - **`angle`** --- Enables the GLES backend via [ANGLE](https://github.com/google/angle) on macOS.
 //! - **`vulkan-portability`** --- Enables the Vulkan backend on macOS & iOS.
-//! - **`webgpu`** --- Enables the WebGPU backend on Wasm. Disabled when targeting `emscripten`.
-//! - **`webgl`** --- Enables the GLES backend on Wasm
-//!
+//! - **`webgl`** --- Enables the GLES backend on Wasm.
 //!     - ⚠️ WIP: Currently will also enable GLES dependencies on any other targets.
 //!
+//! **Note:** In the documentation, if you see that an item depends on a backend,
+//! it means that the item is only available when that backend is enabled _and_ the backend
+//! is supported on the current platform.
+//!
 //! ### Shading language support
 //!
+//! - **`wgsl`** _(enabled by default)_ --- Enable accepting WGSL shaders as input.
 //! - **`spirv`** --- Enable accepting SPIR-V shaders as input.
 //! - **`glsl`** --- Enable accepting GLSL shaders as input.
-//! - **`wgsl`** _(enabled by default)_ --- Enable accepting WGSL shaders as input.
+//! - **`naga-ir`** --- Enable accepting Naga IR shaders as input.
 //!
 //! ### Logging & Tracing
 //!
@@ -49,6 +52,14 @@
 //!   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.
 //!
+//! ### Feature Aliases
+//!
+//! These features aren't actually features on the crate itself, but a convenient shorthand for
+//! complicated cases.
+//!
+//! - **`wgpu_core`** --- Enabled when there is any non-webgpu backend enabled on the platform.
+//! - **`naga`** ---- Enabled when any non-wgsl shader input is enabled.
+//!
 
 #![cfg_attr(docsrs, feature(doc_cfg, doc_auto_cfg))]
 #![doc(html_logo_url = "https://raw.githubusercontent.com/gfx-rs/wgpu/trunk/logo.png")]
@@ -100,15 +111,45 @@ pub use wgt::{
     QUERY_SIZE, VERTEX_STRIDE_ALIGNMENT,
 };
 
-#[cfg(not(webgpu))]
-#[doc(hidden)]
-pub use ::hal;
-#[cfg(feature = "naga")]
-pub use ::naga;
-#[cfg(not(webgpu))]
-#[doc(hidden)]
+/// Re-export of our `wgpu-core` dependency.
+///
+#[cfg(wgpu_core)]
+#[doc(inline)]
 pub use ::wgc as core;
 
+/// Re-export of our `wgpu-hal` dependency.
+///
+///
+#[cfg(wgpu_core)]
+#[doc(inline)]
+pub use ::hal;
+
+/// Re-export of our `naga` dependency.
+///
+#[cfg(wgpu_core)]
+#[cfg_attr(docsrs, doc(cfg(any(wgpu_core, naga))))]
+#[doc(inline)]
+// We re-export wgpu-core's re-export of naga, as we may not have direct access to it.
+pub use ::wgc::naga;
+/// Re-export of our `naga` dependency.
+///
+#[cfg(all(not(wgpu_core), naga))]
+#[cfg_attr(docsrs, doc(cfg(any(wgpu_core, naga))))]
+#[doc(inline)]
+// If that's not available, we re-export our own.
+pub use naga;
+
+#[doc(inline)]
+/// Re-export of our `raw-window-handle` dependency.
+///
+pub use raw_window_handle as rwh;
+
+/// Re-export of our `web-sys` dependency.
+///
+#[cfg(any(webgl, webgpu))]
+#[doc(inline)]
+pub use web_sys;
+
 // wasm-only types, we try to keep as many types non-platform
 // specific, but these need to depend on web-sys.
 #[cfg(any(webgpu, webgl))]
@@ -644,7 +685,7 @@ impl Drop for ShaderModule {
 ///
 /// This type is unique to the Rust API of `wgpu`. In the WebGPU specification,
 /// only WGSL source code strings are accepted.
-#[cfg_attr(feature = "naga", allow(clippy::large_enum_variant))]
+#[cfg_attr(feature = "naga-ir", allow(clippy::large_enum_variant))]
 #[derive(Clone, Debug)]
 #[non_exhaustive]
 pub enum ShaderSource<'a> {
@@ -669,7 +710,7 @@ pub enum ShaderSource<'a> {
     #[cfg(feature = "wgsl")]
     Wgsl(Cow<'a, str>),
     /// Naga module.
-    #[cfg(feature = "naga")]
+    #[cfg(feature = "naga-ir")]
     Naga(Cow<'static, naga::Module>),
     /// Dummy variant because `Naga` doesn't have a lifetime and without enough active features it
     /// could be the last one active.

wgpu/src/util/init.rs

@@ -2,13 +2,13 @@ use wgt::{Backends, PowerPreference, RequestAdapterOptions};
 
 use crate::{Adapter, Instance, Surface};
 
-#[cfg(not(webgpu))]
+#[cfg(wgpu_core)]
 #[cfg_attr(docsrs, doc(cfg(all())))]
 pub use wgc::instance::parse_backends_from_comma_list;
-/// Always returns WEBGPU on wasm over webgpu.
-#[cfg(webgpu)]
+/// Just return ALL, if wgpu_core is not enabled.
+#[cfg(not(wgpu_core))]
 pub fn parse_backends_from_comma_list(_string: &str) -> Backends {
-    Backends::BROWSER_WEBGPU
+    Backends::all()
 }
 
 /// Get a set of backend bits from the environment variable WGPU_BACKEND.