Move binary-specific code into its library

Author: tuguzT

.gitignore

@@ -21,7 +21,7 @@ flamegraph.svg
 # Compiled shader assets from running tests
 crates/shader-crate-template/shaders
 
-# Build artefacts used by CI tests
+# Build artifacts used by CI tests
 tmp/*
 crates/shader-crate-template/manifest.json
 crates/shader-crate-template/rust_gpu_shader_crate_template.spv

Cargo.lock

@@ -2,7 +2,7 @@
 members = [
 	"crates/rustc_codegen_spirv-cache",
 	"crates/cargo-gpu-test-utils",
-	"crates/cargo-gpu-cache",
+	"crates/cargo-gpu-build",
 	"crates/cargo-gpu",
 	"crates/xtask",
 ]
@@ -23,6 +23,9 @@ keywords = ["gpu", "compiler", "rust-gpu"]
 license = "MIT OR Apache-2.0"
 
 [workspace.dependencies]
+cargo-gpu-build = { path = "crates/cargo-gpu-build", default-features = false }
+cargo-gpu-test-utils = { path = "crates/cargo-gpu-test-utils", default-features = false }
+rustc_codegen_spirv-cache = { path = "crates/rustc_codegen_spirv-cache", default-features = false }
 spirv-builder = { git = "https://github.com/Rust-GPU/rust-gpu", rev = "3a897aa96c83b7caede692cbf8da7e58d7014ec8", default-features = false }
 anyhow = "1.0.98"
 thiserror = "2.0.12"

Cargo.toml

@@ -0,0 +1,15 @@
+[package]
+name = "cargo-gpu-build"
+description = "Builder of `rust-gpu` shader crates"
+version.workspace = true
+edition.workspace = true
+repository.workspace = true
+keywords.workspace = true
+license.workspace = true
+
+[dependencies]
+rustc_codegen_spirv-cache.workspace = true
+thiserror.workspace = true
+
+[lints]
+workspace = true

crates/cargo-gpu-build/Cargo.toml

@@ -0,0 +1,42 @@
+#![expect(clippy::pub_use, reason = "pub use for build scripts")]
+
+//! Rust GPU shader crate builder.
+//!
+//! This library allows you to easily compile your rust-gpu shaders,
+//! without requiring you to fix your entire project to a specific toolchain.
+//!
+//! # How it works
+//!
+//! This library manages installations of `rustc_codegen_spirv`
+//! using rust-gpu's [`rustc_codegen_spirv-cache`](cache) crate.
+//!
+//! Then we continue to use rust-gpu's [`spirv-builder`](cache::spirv_builder) crate
+//! to pass the many additional parameters required to configure rustc and our codegen backend,
+//! but provide you with a toolchain agnostic version that you may use from stable rustc.
+//! And a `cargo gpu` command line utility to simplify shader building even more.
+//!
+//! ## How we build the backend
+//!
+//! * retrieve the version of rust-gpu you want to use based on the version of the
+//!   `spirv-std` dependency in your shader crate.
+//! * create a dummy project at `<cache_dir>/codegen/<version>/` that depends on
+//!   `rustc_codegen_spirv`
+//! * use `cargo metadata` to `cargo update` the dummy project, which downloads the
+//!   `rustc_codegen_spirv` crate into cargo's cache, and retrieve the path to the
+//!   download location.
+//! * search for the required toolchain in `build.rs` of `rustc_codegen_spirv`
+//! * build it with the required toolchain version
+//! * copy out the binary and clean the target dir
+//!
+//! ## Building shader crates
+//!
+//! `cargo-gpu` takes a path to a shader crate to build, as well as a path to a directory
+//! to put the compiled `spv` source files. It also takes a path to an output manifest
+//! file where all shader entry points will be mapped to their `spv` source files. This
+//! manifest file can be used by build scripts (`build.rs` files) to generate linkage or
+//! conduct other post-processing, like converting the `spv` files into `wgsl` files,
+//! for example.
+
+pub use rustc_codegen_spirv_cache as cache;
+
+// TODO build script API without shader crate path repetitions

crates/cargo-gpu-build/src/lib.rs

@@ -10,11 +10,27 @@ license.workspace = true
 default-run = "cargo-gpu"
 
 [dependencies]
-cargo-gpu-cache = { path = "../cargo-gpu-cache", features = ["watch", "clap"] }
+cargo-gpu-build.workspace = true
+rustc_codegen_spirv-cache = { workspace = true, features = ["clap"] }
+spirv-builder = { workspace = true, features = ["clap", "watch"] }
+cargo_metadata.workspace = true
+anyhow.workspace = true
+thiserror.workspace = true
 clap.workspace = true
 log.workspace = true
 env_logger.workspace = true
-anyhow.workspace = true
+relative-path.workspace = true
+serde.workspace = true
+serde_json.workspace = true
+crossterm.workspace = true
+semver.workspace = true
+dunce.workspace = true
+
+[dev-dependencies]
+cargo-gpu-test-utils.workspace = true
+test-log.workspace = true
+cargo_metadata = { workspace = true, features = ["builder"] }
+cargo-util-schemas.workspace = true
 
 [lints]
 workspace = true

crates/cargo-gpu-cache/Cargo.toml

@@ -1,38 +1,39 @@
+//! `cargo gpu build`, analogous to `cargo build`
+
 #![allow(clippy::shadow_reuse, reason = "let's not be silly")]
 #![allow(clippy::unwrap_used, reason = "this is basically a test")]
-//! `cargo gpu build`, analogous to `cargo build`
 
-use anyhow::Context as _;
-use spirv_builder::{CompileResult, ModuleResult, SpirvBuilder};
 use std::io::{self, Write as _};
 use std::path::PathBuf;
 
-use crate::user_consent::ask_for_user_consent;
-use crate::Install;
+use anyhow::Context as _;
+use rustc_codegen_spirv_cache::install::Install;
+use spirv_builder::{CompileResult, ModuleResult, SpirvBuilder};
 
 use crate::linkage::Linkage;
 use crate::lockfile::LockfileMismatchHandler;
+use crate::user_consent::ask_for_user_consent;
 
 /// Args for just a build
-#[derive(Debug, Clone, serde::Deserialize, serde::Serialize)]
-#[cfg_attr(feature = "clap", derive(clap::Parser))]
+#[derive(Debug, Clone, clap::Parser, serde::Deserialize, serde::Serialize)]
+#[non_exhaustive]
+#[expect(clippy::module_name_repetitions, reason = "it is intended")]
 pub struct BuildArgs {
     /// Path to the output directory for the compiled shaders.
-    #[cfg_attr(feature = "clap", clap(long, short, default_value = "./"))]
+    #[clap(long, short, default_value = "./")]
     pub output_dir: PathBuf,
 
     /// Watch the shader crate directory and automatically recompile on changes.
-    #[cfg(feature = "watch")]
-    #[cfg_attr(feature = "clap", clap(long, short, action))]
+    #[clap(long, short, action)]
     pub watch: bool,
 
-    /// the flattened [`SpirvBuilder`]
-    #[cfg_attr(feature = "clap", clap(flatten))]
+    /// The flattened [`SpirvBuilder`]
+    #[clap(flatten)]
     #[serde(flatten)]
     pub spirv_builder: SpirvBuilder,
 
-    ///Renames the manifest.json file to the given name
-    #[cfg_attr(feature = "clap", clap(long, short, default_value = "manifest.json"))]
+    /// Renames the manifest.json file to the given name
+    #[clap(long, short, default_value = "manifest.json")]
     pub manifest_file: String,
 }
 
@@ -41,7 +42,6 @@ impl Default for BuildArgs {
     fn default() -> Self {
         Self {
             output_dir: PathBuf::from("./"),
-            #[cfg(feature = "watch")]
             watch: false,
             spirv_builder: SpirvBuilder::default(),
             manifest_file: String::from("manifest.json"),
@@ -50,20 +50,25 @@ impl Default for BuildArgs {
 }
 
 /// `cargo build` subcommands
-#[derive(Clone, Debug, serde::Deserialize, serde::Serialize)]
-#[cfg_attr(feature = "clap", derive(clap::Parser))]
+#[derive(Clone, Debug, clap::Parser, serde::Deserialize, serde::Serialize)]
+#[non_exhaustive]
 pub struct Build {
     /// CLI args for install the `rust-gpu` compiler and components
-    #[cfg_attr(feature = "clap", clap(flatten))]
+    #[clap(flatten)]
     pub install: Install,
 
     /// CLI args for configuring the build of the shader
-    #[cfg_attr(feature = "clap", clap(flatten))]
+    #[clap(flatten)]
     pub build: BuildArgs,
 }
 
 impl Build {
-    /// Entrypoint
+    /// Builds the shader crate.
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if the build process fails somehow.
+    #[inline]
     pub fn run(&mut self) -> anyhow::Result<()> {
         let skip_consent = self.install.auto_install_rust_toolchain;
         let halt_installation = ask_for_user_consent(skip_consent);
@@ -98,14 +103,9 @@ impl Build {
             std::env::current_dir()?.display()
         );
 
-        #[cfg(feature = "watch")]
-        let watching = self.build.watch;
-        #[cfg(not(feature = "watch"))]
-        let watching = false;
-        if watching {
+        if self.build.watch {
             return self.watch();
         }
-
         self.build()
     }
 
@@ -123,24 +123,18 @@ impl Build {
     /// Watches shader crate for changes using [`SpirvBuilder`]
     /// or returns an error depending on presence of `watch` feature.
     fn watch(&self) -> anyhow::Result<()> {
-        #[cfg(feature = "watch")]
-        {
-            let this = self.clone();
-            self.build
-                .spirv_builder
-                .watch(move |result, accept| {
-                    let parse_result = this.parse_compilation_result(&result);
-                    if let Some(accept) = accept {
-                        accept.submit(parse_result);
-                    }
-                })?
-                .context("should always return the first compile result")
-                .flatten()?;
-            anyhow::bail!("unexpected end of watch")
-        }
-
-        #[cfg(not(feature = "watch"))]
-        anyhow::bail!("cannot watch for changes without the `watch` feature")
+        let this = self.clone();
+        self.build
+            .spirv_builder
+            .watch(move |result, accept| {
+                let parse_result = this.parse_compilation_result(&result);
+                if let Some(accept) = accept {
+                    accept.submit(parse_result);
+                }
+            })?
+            .context("should always return the first compile result")
+            .flatten()?;
+        anyhow::bail!("unexpected end of watch")
     }
 
     /// Parses compilation result from [`SpirvBuilder`] and writes it out to a file
@@ -206,8 +200,6 @@ impl Build {
 
 #[cfg(test)]
 mod test {
-    #![cfg(feature = "clap")]
-
     use cargo_gpu_test_utils::{shader_crate_template_path, tests_teardown};
     use clap::Parser as _;
 

crates/cargo-gpu/Cargo.toml

@@ -1,7 +1,5 @@
 //! Manage and merge the various sources of config: shader crate's `Cargo.toml`(s) and CLI args.
 
-#![cfg(feature = "clap")]
-
 use anyhow::Context as _;
 use clap::Parser as _;