Add methods for shader crate builder, add build script entry

Author: tuguzT

Cargo.lock

@@ -26,7 +26,7 @@ license = "MIT OR Apache-2.0"
 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 = "ad2a34abb0576e1cf032237d191e8e63de1c3cea", default-features = false }
+spirv-builder = { git = "https://github.com/Rust-GPU/rust-gpu", rev = "c5fbc8b712e96ad689643293b7d80ebe8af480d2", default-features = false }
 anyhow = "1.0.98"
 thiserror = "2.0.12"
 clap = { version = "4.5.41", features = ["derive"] }

Cargo.toml

@@ -9,10 +9,17 @@ license.workspace = true
 
 [dependencies]
 rustc_codegen_spirv-cache.workspace = true
+spirv-builder.workspace = true
 thiserror.workspace = true
 semver.workspace = true
 dunce.workspace = true
 log.workspace = true
 
+[features]
+# Rebuilds target shader crate upon changes
+watch = ["spirv-builder/watch"]
+# Enables `clap` support for public structs
+clap = ["spirv-builder/clap", "rustc_codegen_spirv-cache/clap"]
+
 [lints]
 workspace = true

crates/cargo-gpu-build/Cargo.toml

@@ -5,14 +5,18 @@ use std::{io, path::Path};
 
 use crate::{
     lockfile::{LockfileMismatchError, LockfileMismatchHandler},
-    spirv_builder::SpirvBuilder,
+    spirv_builder::{CompileResult, SpirvBuilder, SpirvBuilderError},
     spirv_cache::{
         command::CommandExecError,
         install::{Install, InstallError, InstallParams, InstalledBackend},
         toolchain::HaltToolchainInstallation,
+        user_output,
     },
 };
 
+#[cfg(feature = "watch")]
+use crate::spirv_builder::{AcceptFirstCompile, Watch};
+
 /// Creates shader crate builder, allowing to modify install and build parameters separately.
 ///
 /// # Errors
@@ -24,14 +28,14 @@ use crate::{
 /// * there is a lockfile version mismatch that cannot be resolved automatically.
 #[inline]
 #[expect(clippy::unreachable, reason = "target was already set")]
-pub fn shader_crate_builder<P, S, E, T, C, W>(
+pub fn make_shader_crate_builder<P, S, E, T, C, W>(
     shader_crate: P,
     target: S,
     mut build: SpirvBuilder,
     install: InstallParams,
     writer: W,
     halt_toolchain_installation: HaltToolchainInstallation<T, C>,
-) -> Result<ShaderCrateBuilder, MakeShaderBuilderError<E>>
+) -> Result<ShaderCrateBuilder, MakeShaderCrateBuilderError<E>>
 where
     P: AsRef<Path>,
     S: Into<String>,
@@ -78,10 +82,57 @@ pub struct ShaderCrateBuilder {
     pub lockfile_mismatch_handler: LockfileMismatchHandler,
 }
 
+impl ShaderCrateBuilder {
+    /// Builds the shader crate using the configured [`SpirvBuilder`].
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if building the shader crate failed.
+    #[inline]
+    pub fn build<W>(&self, writer: W) -> Result<CompileResult, ShaderCrateBuildError>
+    where
+        W: io::Write,
+    {
+        let shader_crate = self.installed_backend_args.shader_crate.display();
+        user_output!(writer, "Compiling shaders at {shader_crate}...\n")?;
+
+        let result = self.builder.build()?;
+        Ok(result)
+    }
+
+    /// Watches the shader crate for changes using the configured [`SpirvBuilder`].
+    ///
+    /// Calls `on_compilation_finishes` after each successful compilation.
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if watching shader crate for changes failed.
+    #[cfg(feature = "watch")]
+    #[inline]
+    pub fn watch<W, T, F>(
+        &self,
+        writer: W,
+        on_compilation_finishes: F,
+    ) -> Result<Watch<T>, ShaderCrateBuildError>
+    where
+        W: io::Write,
+        F: FnMut(CompileResult, Option<AcceptFirstCompile<'_, T>>) + Send + 'static,
+    {
+        let shader_crate = self.installed_backend_args.shader_crate.display();
+        user_output!(
+            writer,
+            "Watching shaders for changes at {shader_crate}...\n"
+        )?;
+
+        let watch = self.builder.watch(on_compilation_finishes)?;
+        Ok(watch)
+    }
+}
+
 /// An error indicating what went wrong when creating a [`ShaderCrateBuilder`].
 #[derive(Debug, thiserror::Error)]
 #[non_exhaustive]
-pub enum MakeShaderBuilderError<E> {
+pub enum MakeShaderCrateBuilderError<E = CommandExecError> {
     /// The given shader crate path is not valid.
     #[error("shader crate path is not valid: {0}")]
     InvalidCratePath(#[from] io::Error),
@@ -92,3 +143,15 @@ pub enum MakeShaderBuilderError<E> {
     #[error(transparent)]
     LockfileMismatch(#[from] LockfileMismatchError),
 }
+
+/// An error indicating what went wrong when building the shader crate.
+#[derive(Debug, thiserror::Error)]
+#[non_exhaustive]
+pub enum ShaderCrateBuildError {
+    /// Failed to write user output.
+    #[error("failed to write user output: {0}")]
+    IoWrite(#[from] io::Error),
+    /// Failed to build shader crate.
+    #[error("failed to build shader crate: {0}")]
+    Build(#[from] SpirvBuilderError),
+}

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

@@ -14,8 +14,60 @@
 
 #![expect(clippy::pub_use, reason = "pub use for build scripts")]
 
+use std::{io, path::Path};
+
+use self::{
+    build::{make_shader_crate_builder, MakeShaderCrateBuilderError, ShaderCrateBuildError},
+    spirv_builder::{CompileResult, SpirvBuilder},
+    spirv_cache::{install::InstallParams, toolchain::HaltToolchainInstallation},
+};
+
 pub use rustc_codegen_spirv_cache as spirv_cache;
 pub use rustc_codegen_spirv_cache::spirv_builder;
 
 pub mod build;
 pub mod lockfile;
+
+/// Builds a `rust-gpu` shader crate, allowing to modify install and build parameters separately.
+///
+/// This function is intended to be used from a build script.
+///
+/// # Errors
+///
+/// Returns an error if the codegen backend for the shader crate could not be installed
+/// or this shader crate could not be built.
+#[inline]
+pub fn build_shader_crate<P, S>(
+    shader_crate: P,
+    target: S,
+    build: SpirvBuilder,
+    install: InstallParams,
+) -> Result<CompileResult, BuildScriptError>
+where
+    P: AsRef<Path>,
+    S: Into<String>,
+{
+    let mut writer = io::stdout();
+    let shader_crate_builder = make_shader_crate_builder(
+        shader_crate,
+        target,
+        build,
+        install,
+        &mut writer,
+        HaltToolchainInstallation::fallthrough(),
+    )?;
+    let result = shader_crate_builder.build(&mut writer)?;
+    Ok(result)
+}
+
+/// An error indicating that building a shader crate from a build script failed.
+#[derive(Debug, thiserror::Error)]
+#[non_exhaustive]
+pub enum BuildScriptError {
+    /// Failed to create a shader crate builder.
+    #[error(transparent)]
+    MakeBuilder(#[from] MakeShaderCrateBuilderError),
+    /// Failed to build the shader crate.
+    #[error(transparent)]
+    Build(#[from] ShaderCrateBuildError),
+}

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

@@ -10,9 +10,7 @@ license.workspace = true
 default-run = "cargo-gpu"
 
 [dependencies]
-cargo-gpu-build.workspace = true
-rustc_codegen_spirv-cache = { workspace = true, features = ["clap"] }
-spirv-builder = { workspace = true, features = ["clap", "watch"] }
+cargo-gpu-build = { workspace = true, features = ["clap", "watch"] }
 cargo_metadata.workspace = true
 anyhow.workspace = true
 thiserror.workspace = true

crates/cargo-gpu/Cargo.toml

@@ -9,7 +9,7 @@ use std::{
 
 use anyhow::Context as _;
 use cargo_gpu_build::{
-    build::shader_crate_builder,
+    build::{make_shader_crate_builder, ShaderCrateBuilder},
     spirv_builder::{CompileResult, ModuleResult, SpirvBuilder, SpirvBuilderError, Watch},
     spirv_cache::install::Install,
 };
@@ -72,7 +72,7 @@ impl Build {
     /// Returns an error if the build process fails somehow.
     #[inline]
     pub fn run(&mut self) -> anyhow::Result<()> {
-        let crate_builder = shader_crate_builder(
+        let crate_builder = make_shader_crate_builder(
             self.install.shader_crate.clone(),
             self.build
                 .spirv_builder
@@ -84,8 +84,8 @@ impl Build {
             io::stdout(),
             ask_for_user_consent(self.install.params.auto_install_rust_toolchain),
         )?;
-        self.install = crate_builder.installed_backend_args;
-        self.build.spirv_builder = crate_builder.builder;
+        self.install = crate_builder.installed_backend_args.clone();
+        self.build.spirv_builder = crate_builder.builder.clone();
 
         // Ensure the shader output dir exists
         log::debug!(
@@ -98,35 +98,30 @@ impl Build {
         self.build.output_dir = canonicalized;
 
         if self.build.watch {
-            let never = self.watch()?;
+            let never = self.watch(crate_builder)?;
             match never {}
         }
-        self.build()
+        self.build(crate_builder)
     }
 
-    /// Builds shader crate using [`SpirvBuilder`].
-    fn build(&self) -> anyhow::Result<()> {
-        crate::user_output!(
-            "Compiling shaders at {}...\n",
-            self.install.shader_crate.display()
-        )?;
-        let result = self.build.spirv_builder.build()?;
+    /// Builds shader crate using [`ShaderCrateBuilder`].
+    #[expect(clippy::needless_pass_by_value, reason = "move of responsibility")]
+    fn build(&self, crate_builder: ShaderCrateBuilder) -> anyhow::Result<()> {
+        let result = crate_builder.build(io::stdout())?;
         self.parse_compilation_result(&result)?;
         Ok(())
     }
 
-    /// Watches shader crate for changes using [`SpirvBuilder`].
-    fn watch(&self) -> anyhow::Result<Infallible> {
+    /// Watches shader crate for changes using [`ShaderCrateBuilder`].
+    #[expect(clippy::needless_pass_by_value, reason = "move of responsibility")]
+    fn watch(&self, crate_builder: ShaderCrateBuilder) -> anyhow::Result<Infallible> {
         let this = self.clone();
-        let watch = self
-            .build
-            .spirv_builder
-            .watch(move |result, maybe_accept| {
-                let parse_result = this.parse_compilation_result(&result);
-                if let Some(accept) = maybe_accept {
-                    accept.submit(parse_result);
-                }
-            })?;
+        let watch = crate_builder.watch(io::stdout(), move |result, maybe_accept| {
+            let parse_result = this.parse_compilation_result(&result);
+            if let Some(accept) = maybe_accept {
+                accept.submit(parse_result);
+            }
+        })?;
 
         let Watch {
             first_compile,

crates/cargo-gpu/src/build.rs

@@ -87,6 +87,7 @@ impl Config {
 mod test {
     use std::io::Write as _;
 
+    use cargo_gpu_build::spirv_builder::Capability;
     use cargo_gpu_test_utils::{overwrite_shader_cargo_toml, shader_crate_test_path};
 
     use super::*;
@@ -191,10 +192,7 @@ mod test {
         let args = Config::clap_command_with_cargo_config(&shader_crate_path, vec![]).unwrap();
         assert_eq!(
             args.build.spirv_builder.capabilities,
-            vec![
-                spirv_builder::Capability::AtomicStorage,
-                spirv_builder::Capability::Matrix
-            ]
+            vec![Capability::AtomicStorage, Capability::Matrix]
         );
     }
 

crates/cargo-gpu/src/config.rs

@@ -15,12 +15,12 @@
 //!
 //! ## Where the binaries are
 //!
-//! Prebuilt binaries are stored in the [cache directory](rustc_codegen_spirv_cache::cache::cache_dir()),
+//! Prebuilt binaries are stored in the [cache directory](cargo_gpu_build::spirv_cache::cache::cache_dir()),
 //! which path differs by OS you are using.
 
 #![expect(clippy::pub_use, reason = "part of public interface")]
 
-pub use rustc_codegen_spirv_cache::install::Install;
+pub use cargo_gpu_build::spirv_cache::install::Install;
 
 use self::{
     build::Build, dump_usage::dump_full_usage_for_readme, show::Show,
@@ -39,7 +39,7 @@ mod user_consent;
 /// Central function to write to the user.
 #[macro_export]
 macro_rules! user_output {
-    ($($args: tt)*) => { ::rustc_codegen_spirv_cache::user_output!(::std::io::stdout(), $($args)*) };
+    ($($args: tt)*) => { cargo_gpu_build::spirv_cache::user_output!(::std::io::stdout(), $($args)*) };
 }
 
 /// All of the available subcommands for `cargo gpu`