diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml index 11148a5eba..189aa16832 100644 --- a/.github/workflows/ci.yaml +++ b/.github/workflows/ci.yaml @@ -149,6 +149,10 @@ jobs: run: rustfmt --check tests/ui/**/*.rs - name: Check docs are valid run: RUSTDOCFLAGS=-Dwarnings cargo doc --no-deps + - name: Check docs for `spirv-std` and `spirv-builder` on stable (for docs.rs) + run: | + RUSTDOCFLAGS=-Dwarnings cargo +stable doc --no-deps -p spirv-std + RUSTDOCFLAGS=-Dwarnings cargo +stable doc --no-deps -p spirv-builder --no-default-features - name: Clippy & custom lints run: .github/workflows/lint.sh diff --git a/CHANGELOG.md b/CHANGELOG.md index c7b610616a..b87e50487a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -30,6 +30,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] ### Changed 🛠 +- [PR#1079](https://github.com/EmbarkStudios/rust-gpu/pull/1079) revised `spirv-builder`'s `README.md`, + and added a way for `docs.rs` to be able to build it (via `cargo +stable doc --no-default-features`) - [PR#1070](https://github.com/EmbarkStudios/rust-gpu/pull/1070) made panics (via the `abort` intrinsic) early-exit (i.e. `return` from) the shader entry-point, instead of looping infinitely - [PR#1071](https://github.com/EmbarkStudios/rust-gpu/pull/1071) updated toolchain to `nightly-2023-05-27` diff --git a/Cargo.lock b/Cargo.lock index 536c8b4f07..71873d0fc0 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1055,9 +1055,9 @@ dependencies = [ [[package]] name = "hermit-abi" -version = "0.3.1" +version = "0.3.2" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "fed44880c466736ef9a5c5b5facefb5ed0785676d0c02d612db14e54f0d84286" +checksum = "443144c8cdadd93ebf52ddb4056d257f5b52c04d3c804e657d19eb73fc33668b" [[package]] name = "hexf-parse" @@ -1135,7 +1135,7 @@ version = "0.4.5" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "8687c819457e979cc940d09cb16e42a1bf70aa6b60a549de6d3a62a0ee90c69e" dependencies = [ - "hermit-abi 0.3.1", + "hermit-abi 0.3.2", "io-lifetimes", "rustix", "windows-sys 0.45.0", diff --git a/crates/rustc_codegen_spirv/build.rs b/crates/rustc_codegen_spirv/build.rs index 0ddd6b78ec..c3de9b5924 100644 --- a/crates/rustc_codegen_spirv/build.rs +++ b/crates/rustc_codegen_spirv/build.rs @@ -8,7 +8,7 @@ use std::process::{Command, ExitCode}; /// Current `rust-toolchain.toml` file /// Unfortunately, directly including the actual workspace `rust-toolchain.toml` doesn't work together with /// `cargo publish`. We need to figure out a way to do this properly, but let's hardcode it for now :/ -//const REQUIRED_RUST_TOOLCHAIN: &str = include_str!("../../rust-toolchain"); +//const REQUIRED_RUST_TOOLCHAIN: &str = include_str!("../../rust-toolchain.toml"); const REQUIRED_RUST_TOOLCHAIN: &str = r#"[toolchain] channel = "nightly-2023-05-27" components = ["rust-src", "rustc-dev", "llvm-tools-preview"] @@ -65,7 +65,7 @@ fn check_toolchain_version() -> Result<(), Box> { return Err(Box::::from(format!( r#"error: wrong toolchain detected (found commit hash `{current_hash}`, expected `{required_hash}`). -Make sure your `rust-toolchain` file contains the following: +Make sure your `rust-toolchain.toml` file contains the following: ------------- {stripped_toolchain} -------------"# diff --git a/crates/spirv-builder/Cargo.toml b/crates/spirv-builder/Cargo.toml index b40aa59fe7..0b52ffd739 100644 --- a/crates/spirv-builder/Cargo.toml +++ b/crates/spirv-builder/Cargo.toml @@ -1,26 +1,39 @@ [package] name = "spirv-builder" description = "Helper for building shaders with rust-gpu" -# Documentation currently fails on docs.rs, but it doesn't have to. See https://github.com/EmbarkStudios/rust-gpu/issues/970 -documentation = "https://embarkstudios.github.io/rust-gpu/api/spirv_builder/index.html" version.workspace = true authors.workspace = true edition.workspace = true license.workspace = true repository.workspace = true -# See rustc_codegen_spirv/Cargo.toml for details on these features +# HACK(eddyb) allow `docs.rs` to build this crate by making `rustc_codegen_spirv` +# dependency optional in a way that will always result in it being enabled +# during normal builds (as `use-{installed,compiled}-tools` both require it), +# and produces a compile-time error if it's missing and `cfg(doc)` isn't set. +[package.metadata.docs.rs] +no-default-features = true + +# NOTE(eddyb) the `dep:` prefixes used here prevents a feature with the name as +# that optional dependency, from being automatically created by Cargo, see: +# https://doc.rust-lang.org/cargo/reference/features.html#optional-dependencies [features] +# See `rustc_codegen_spirv/Cargo.toml` for details on these features. default = ["use-compiled-tools"] -use-installed-tools = ["rustc_codegen_spirv/use-installed-tools"] -use-compiled-tools = ["rustc_codegen_spirv/use-compiled-tools"] -skip-toolchain-check = ["rustc_codegen_spirv/skip-toolchain-check"] -watch = ["notify"] +use-installed-tools = ["dep:rustc_codegen_spirv", "rustc_codegen_spirv?/use-installed-tools"] +use-compiled-tools = ["dep:rustc_codegen_spirv", "rustc_codegen_spirv?/use-compiled-tools"] +skip-toolchain-check = ["rustc_codegen_spirv?/skip-toolchain-check"] + +watch = ["dep:notify"] [dependencies] -rustc_codegen_spirv-types.workspace = true -# See comment in lib.rs invoke_rustc for why this is here +# See comment in `src/lib.rs` `invoke_rustc` regarding `rustc_codegen_spirv` dep. rustc_codegen_spirv.workspace = true +# HACK(eddyb) see `docs.rs`-related comment above for why this is optional. +rustc_codegen_spirv.optional = true + +rustc_codegen_spirv-types.workspace = true + memchr = "2.4" raw-string = "0.3.5" serde = { version = "1.0", features = ["derive"] } diff --git a/crates/spirv-builder/README.md b/crates/spirv-builder/README.md index 62a52e6f03..7914757079 100644 --- a/crates/spirv-builder/README.md +++ b/crates/spirv-builder/README.md @@ -29,23 +29,26 @@ const SHADER: &[u8] = include_bytes!(env!("my_shaders.spv")); ## Building with `spirv-builder` -Because of its nature, `rustc_codegen_spirv`, and therefore `spirv-builder` by extension, require the use of a very specific nightly toolchain of Rust. +As `spirv-builder` relies on `rustc_codegen_spirv` being built for it (by Cargo, as a direct dependency), and due to the special nature of the latter (as a `rustc` codegen backend "plugin"), both end up sharing the requirement for a very specific nightly toolchain version of Rust. -**The current toolchain is: `nightly-2023-05-27`.** +**The current Rust toolchain version is: `nightly-2023-05-27`.** -Toolchains for previous versions of `spirv-builder`: +Rust toolchain version history across [rust-gpu releases](https://github.com/EmbarkStudios/rust-gpu/releases) (since `0.4`): -|Version|Toolchain| -|-:|-| -|`0.8.0`|`nightly-2023-04-15`| -|`0.7.0`|`nightly-2023-03-04`| -|`0.6.*`|`nightly-2023-01-21`| -|`0.5.0`|`nightly-2022-12-18`| -|`0.4.0`|`nightly-2022-10-29`| -|`0.4.0-alpha.16` - `0.4.0-alpha.17`|`nightly-2022-10-01`| -|`0.4.0-alpha.15`|`nightly-2022-08-29`| -|`0.4.0-alpha.13` - `0.4.0-alpha.14`|`nightly-2022-04-11`| +|`spirv-builder`
version|Rust toolchain
version| +|:-:|:-:| +|`0.8`|`nightly-2023-04-15`| +|`0.7`|`nightly-2023-03-04`| +|`0.6`|`nightly-2023-01-21`| +|`0.5`|`nightly-2022-12-18`| +|`0.4`|`nightly-2022-10-29`| -The nightly toolchain has to match *exactly*. Starting with `0.4.0-alpha.15`, the commit hash of your local toolchain is checked and you'll get a build error when building `rustc_codegen_spirv` with the wrong toolchain. If you want to experiment with different versions, this check can be omitted by defining the environment variable `RUSTGPU_SKIP_TOOLCHAIN_CHECK`since `0.4.0-alpha.16`. Keep in mind that, as `rustc_codegen_spirv` is heavily dependent on `rustc`'s internal API, diverging too much from the required toolchain will quickly result in compile errors. +*As patch versions must be semver-compatible, they will always require the +same toolchain (for example, `0.6.0` and `0.6.1` both use `nightly-2023-01-21`).* + +Only that *exact* Rust nightly toolchain version is **supported**. Since `0.4`, the commit hash of your current Rust toolchain is checked and you'll get a build error when building `rustc_codegen_spirv` with the wrong toolchain. +Notably, the error will also show what the `rust-toolchain.toml` file *should* contain (to get the expected toolchain), which you can rely on when updating to a new release. + +If you want to experiment with _different, **unsupported**_, Rust toolchain versions, this check can be omitted by defining the environment variable `RUSTGPU_SKIP_TOOLCHAIN_CHECK`. Keep in mind that, as `rustc_codegen_spirv` is *heavily* dependent on `rustc`'s internal APIs, diverging too much from the supported toolchain version will quickly result in compile errors (or worse, e.g. spurious errors and/or incorrect behavior, when compiling shaders with it). [rustgpu]: https://github.com/EmbarkStudios/rust-gpu/ diff --git a/crates/spirv-builder/src/lib.rs b/crates/spirv-builder/src/lib.rs index b38579fff8..b926dc6285 100644 --- a/crates/spirv-builder/src/lib.rs +++ b/crates/spirv-builder/src/lib.rs @@ -71,6 +71,31 @@ // #![allow()] #![doc = include_str!("../README.md")] +// HACK(eddyb) try to catch misuse of Cargo package features very early on +// (see `spirv-builder/Cargo.toml` for why we go through all of this). +#[cfg(all( + not(any(feature = "use-compiled-tools", feature = "use-installed-tools")), + not(doc) +))] +compile_error!( + "at least one of `use-compiled-tools` or `use-installed-tools` features must be enabled +(outside of documentation builds, which require disabling both to build on stable)" +); + +#[cfg(doc)] +fn _ensure_cfg_doc_means_rustdoc() { + // HACK(eddyb) this relies on specific `rustdoc` behavior (i.e. it skips + // type-checking function bodies, so we trigger a compile-time `panic! from + // a type) to check that we're in fact under `rustdoc`, not just `--cfg doc`. + #[rustfmt::skip] + let _: [(); panic!(" + + `--cfg doc` was set outside of `rustdoc` + (if you are running `rustdoc` or `cargo doc`, please file an issue) + +")]; +} + mod depfile; #[cfg(feature = "watch")] mod watch; diff --git a/crates/spirv-std/README.md b/crates/spirv-std/README.md index 48dfb221dd..7cba186be4 100644 --- a/crates/spirv-std/README.md +++ b/crates/spirv-std/README.md @@ -4,10 +4,6 @@ Core functions, traits, and more that make up a “standard library” for SPIR- This crate gives a `rust-gpu` shader access to the required `#![spirv(..)]` attribute, as well as povide all kinds of APIs that allows a shader to access GPU resources such as textures and buffers. Optionally, through the use of the `"glam"` feature, it includes some boilerplate trait implementations to make `glam` vector types compatible with these APIs. -## 🚨 BREAKING 🚨 - -As of `0.4.0-alpha.16`, your shaders will require a different preamble. See [this migration guide][migration] for more information. - ## Example ![Sky shader](https://github.com/EmbarkStudios/rust-gpu/raw/b12a2f3f6a54bc841d05a9224bc577909d519228/docs/assets/sky.jpg)