From e1baa5a56e3f73c586cd001623dea2872ac609fd Mon Sep 17 00:00:00 2001 From: Erich Gubler Date: Thu, 21 Dec 2023 20:33:35 -0500 Subject: [PATCH] docs: inline `document-features` usage, remove dep. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Re-implements https://github.com/gfx-rs/wgpu/pull/4886 (CC @Wumpf) without the `document-features` crate, which has issues integrating into Firefox builds after being `cargo vendor`ed into its repository. This issue is being tracked against https://github.com/slint-ui/document-features/issues/20. Once resolved, I expect that we will want to revert this PR in its entirety, since `document-features` is still a good addition to `wgpu`'s documentation story. Internally, consensus has already been achieved for this change. Firefox's ability to build unfortunately take priority over this particular convenience. Hopefully, we won't have to compromise shortly! I tested this by ensuring that the HTML output of our existing `document_features::document_features!(…)` usage was exactly the same. There should be exactly zero regressions in the current state of documentation for users. For maintainers, I have added a disclaimer that one needs to keep changes in sync. with the relevant `Cargo.toml` manifests. --- Cargo.lock | 17 ---------------- Cargo.toml | 1 - wgpu-core/Cargo.toml | 1 - wgpu-core/src/lib.rs | 30 +++++++++++++++++++++++++++- wgpu/Cargo.toml | 1 - wgpu/src/lib.rs | 47 +++++++++++++++++++++++++++++++++++++++++++- 6 files changed, 75 insertions(+), 22 deletions(-) diff --git a/Cargo.lock b/Cargo.lock index bfc1b4a9db..027d8fa0f5 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1100,15 +1100,6 @@ dependencies = [ "libloading 0.8.1", ] -[[package]] -name = "document-features" -version = "0.2.7" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "e493c573fce17f00dcab13b6ac057994f3ce17d1af4dc39bfd482b83c6eb6157" -dependencies = [ - "litrs", -] - [[package]] name = "downcast-rs" version = "1.2.0" @@ -1948,12 +1939,6 @@ version = "0.4.11" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "969488b55f8ac402214f3f5fd243ebb7206cf82de60d3172994707a4bcc2b829" -[[package]] -name = "litrs" -version = "0.2.3" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "f9275e0933cf8bb20f008924c0cb07a0692fe54d8064996520bf998de9eb79aa" - [[package]] name = "lock_api" version = "0.4.11" @@ -4009,7 +3994,6 @@ version = "0.18.0" dependencies = [ "arrayvec 0.7.4", "cfg-if", - "document-features", "js-sys", "log", "naga", @@ -4035,7 +4019,6 @@ dependencies = [ "bit-vec", "bitflags 2.4.1", "codespan-reporting", - "document-features", "log", "naga", "parking_lot", diff --git a/Cargo.toml b/Cargo.toml index dd908db6f5..95b1dca71e 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -77,7 +77,6 @@ cfg_aliases = "0.1" cfg-if = "1" codespan-reporting = "0.11" ctor = "0.2" -document-features = "0.2" encase = "0.6" env_logger = "0.10" fern = "0.6" diff --git a/wgpu-core/Cargo.toml b/wgpu-core/Cargo.toml index 987e9d0420..a9f6319873 100644 --- a/wgpu-core/Cargo.toml +++ b/wgpu-core/Cargo.toml @@ -94,7 +94,6 @@ arrayvec = "0.7" bit-vec = "0.6" bitflags = "2" codespan-reporting = "0.11" -document-features.workspace = true log = "0.4" # parking_lot 0.12 switches from `winapi` to `windows`; permit either parking_lot = ">=0.11,<0.13" diff --git a/wgpu-core/src/lib.rs b/wgpu-core/src/lib.rs index 3355c0155f..b44248fdae 100644 --- a/wgpu-core/src/lib.rs +++ b/wgpu-core/src/lib.rs @@ -3,8 +3,36 @@ //! into other language-specific user-friendly libraries. //! //! ## Feature flags -#![doc = document_features::document_features!()] +// NOTE: feature docs. below should be kept in sync. with `Cargo.toml`! //! +//! - **`api_log_info`** --- Log all API entry points at info instead of trace level. +//! - **`resource_log_info`** --- Log resource lifecycle management at info instead of trace level. +//! - **`link`** _(enabled by default)_ --- Use static linking for libraries. Disale to manually +//! link. Enabled by default. +//! - **`renderdoc`** --- Support the Renderdoc graphics debugger: +//! [https://renderdoc.org/](https://renderdoc.org/) +//! - **`strict_asserts`** --- Apply run-time checks, even in release builds. These are in addition +//! to the validation carried out at public APIs in all builds. +//! - **`trace`** --- Enable API tracing. +//! - **`replay`** --- Enable API replaying +//! - **`serial-pass`** --- Enable serializable compute/render passes, and bundle encoders. +//! - **`wgsl`** --- Enable `ShaderModuleSource::Wgsl` +//! - **`fragile-send-sync-non-atomic-wasm`** --- 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. +//! +//! ### Backends, passed through to wgpu-hal +//! +//! - **`metal`** --- Enable the `metal` backend. +//! - **`vulkan`** --- Enable the `vulkan` backend. +//! - **`gles`** --- Enable the `GLES` backend. +//! +//! This is used for all of GLES, OpenGL, and WebGL. +//! - **`dx12`** --- Enable the `dx12` backend. // When we have no backends, we end up with a lot of dead or otherwise unreachable code. #![cfg_attr( diff --git a/wgpu/Cargo.toml b/wgpu/Cargo.toml index ef199068e1..5418879df0 100644 --- a/wgpu/Cargo.toml +++ b/wgpu/Cargo.toml @@ -155,7 +155,6 @@ optional = true [dependencies] arrayvec.workspace = true cfg-if.workspace = true -document-features.workspace = true log.workspace = true parking_lot.workspace = true profiling.workspace = true diff --git a/wgpu/src/lib.rs b/wgpu/src/lib.rs index 7dd0dc6c10..c7266d9bfb 100644 --- a/wgpu/src/lib.rs +++ b/wgpu/src/lib.rs @@ -3,7 +3,52 @@ //! To start using the API, create an [`Instance`]. //! //! ## Feature flags -#![doc = document_features::document_features!()] +// NOTE: feature docs. below should be kept in sync. with `Cargo.toml`! +//! +//! ### 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 +//! 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. +//! - **`vulkan-portability`** --- Enables the Vulkan backend on macOS & iOS. +//! - **`webgl`** --- Enables the GLES backend on Wasm +//! +//! - ⚠️ WIP: Currently will also enable GLES dependencies on any other targets. +//! - ⚠️ WIP: This automatically disables use of WebGPU. See +//! [#2804](https://github.com/gfx-rs/wgpu/issues/3514). +//! +//! ### Shading language support +//! +//! - **`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. +//! +//! ### Logging & Tracing +//! +//! The following features do not have any effect on the WebGPU backend. +//! +//! - **`strict_asserts`** --- Apply run-time checks, even in release builds. These are in addition +//! to the validation carried out at public APIs in all builds. +//! - **`api_log_info`** --- Log all API entry points at info instead of trace level. +//! - **`trace`** --- Allow writing of trace capture files. See [`Adapter::request_device`]. +//! - **`replay`** --- Allow deserializing of trace capture files that were written with the `trace` +//! feature. To replay a trace file use the [wgpu +//! player](https://github.com/gfx-rs/wgpu/tree/trunk/player). +//! +//! ### Other +//! +//! - **`fragile-send-sync-non-atomic-wasm`** --- 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. //! #![cfg_attr(docsrs, feature(doc_cfg, doc_auto_cfg))]