Make build script API

Author: tuguzT

Cargo.lock

@@ -22,7 +22,7 @@ keywords = ["gpu", "compiler", "rust-gpu"]
 license = "MIT OR Apache-2.0"
 
 [workspace.dependencies]
-spirv-builder = { git = "https://github.com/Rust-GPU/rust-gpu", rev = "929112a325335c3acd520ceca10e54596c3be93e", default-features = false }
+spirv-builder = { git = "https://github.com/Rust-GPU/rust-gpu", rev = "e5e56df456ee44f9864076fea19529206ea7b29b", default-features = false }
 anyhow = "1.0.98"
 thiserror = "2.0.12"
 clap = { version = "4.5.41", features = ["derive"] }

Cargo.toml

@@ -10,6 +10,7 @@ license.workspace = true
 [dependencies]
 rustc_codegen_spirv-cache = { path = "../rustc_codegen_spirv-cache" }
 spirv-builder.workspace = true
+dunce.workspace = true
 thiserror.workspace = true
 semver.workspace = true
 log.workspace = true

crates/cargo-gpu-build/Cargo.toml

@@ -0,0 +1,152 @@
+//! This module provides a `rust-gpu` shader crate builder
+//! usable inside of build scripts or as a part of CLI.
+
+use std::{io, path::Path};
+
+use crate::{
+    lockfile::{LockfileMismatchError, LockfileMismatchHandler},
+    spirv_builder::{CompileResult, SpirvBuilder, SpirvBuilderError},
+    spirv_cache::{
+        backend::{Install, InstallError, InstallParams, InstalledBackend},
+        command::CommandExecError,
+        toolchain::HaltToolchainInstallation,
+        user_output,
+    },
+};
+
+#[cfg(feature = "watch")]
+use crate::spirv_builder::SpirvWatcher;
+
+/// Creates shader crate builder, allowing to modify install and build parameters separately.
+///
+/// # Errors
+///
+/// Returns an error if:
+///
+/// * the shader crate path is not valid,
+/// * the backend installation fails,
+/// * there is a lockfile version mismatch that cannot be resolved automatically.
+#[inline]
+#[expect(clippy::unreachable, reason = "target was already set")]
+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, MakeShaderCrateBuilderError<E>>
+where
+    P: AsRef<Path>,
+    S: Into<String>,
+    W: io::Write,
+    E: From<CommandExecError>,
+    T: FnOnce(&str) -> Result<(), E>,
+    C: FnOnce(&str) -> Result<(), E>,
+{
+    let shader_crate_path = dunce::canonicalize(shader_crate)?;
+    let backend_args = Install::new(shader_crate_path, install);
+    let backend = backend_args.run(writer, halt_toolchain_installation)?;
+
+    let lockfile_mismatch_handler = LockfileMismatchHandler::new(
+        &backend_args.shader_crate,
+        &backend.toolchain_channel,
+        backend_args.params.force_overwrite_lockfiles_v4_to_v3,
+    )?;
+
+    build.path_to_crate = Some(backend_args.shader_crate.clone());
+    build.target = Some(target.into());
+    backend
+        .configure_spirv_builder(&mut build)
+        .unwrap_or_else(|_| unreachable!("we set target before calling this function"));
+
+    Ok(ShaderCrateBuilder {
+        builder: build,
+        installed_backend_args: backend_args,
+        installed_backend: backend,
+        lockfile_mismatch_handler,
+    })
+}
+
+/// A builder for compiling a `rust-gpu` shader crate.
+#[derive(Debug, Clone)]
+#[non_exhaustive]
+pub struct ShaderCrateBuilder {
+    /// The underlying builder for compiling the shader crate.
+    pub builder: SpirvBuilder,
+    /// The arguments used to install the backend.
+    pub installed_backend_args: Install,
+    /// The installed backend.
+    pub installed_backend: InstalledBackend,
+    /// The lockfile mismatch handler.
+    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>(&self, writer: W) -> Result<SpirvWatcher<&SpirvBuilder>, ShaderCrateBuildError>
+    where
+        W: io::Write,
+    {
+        let shader_crate = self.installed_backend_args.shader_crate.display();
+        user_output!(
+            writer,
+            "Watching shaders for changes at {shader_crate}...\n"
+        )?;
+
+        let watcher = self.builder.watch()?;
+        Ok(watcher)
+    }
+}
+
+/// An error indicating what went wrong when creating a [`ShaderCrateBuilder`].
+#[derive(Debug, thiserror::Error)]
+#[non_exhaustive]
+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),
+    /// The backend installation failed.
+    #[error("could not install backend: {0}")]
+    Install(#[from] InstallError<E>),
+    /// There is a lockfile version mismatch that cannot be resolved automatically.
+    #[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

@@ -12,9 +12,62 @@
 //! 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.
 
-#![expect(clippy::pub_use, reason = "part of public API")]
+#![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::{backend::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::noop(),
+    )?;
+    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

@@ -11,18 +11,17 @@ default-run = "cargo-gpu"
 
 [dependencies]
 cargo-gpu-build = { path = "../cargo-gpu-build", features = ["clap", "watch"] }
+spirv-builder = { workspace = true, features = ["clap", "watch"] }
 cargo_metadata.workspace = true
 anyhow.workspace = true
 thiserror.workspace = true
-spirv-builder = { workspace = true, features = ["clap", "watch"] }
 clap.workspace = true
 env_logger.workspace = true
 log.workspace = true
 relative-path.workspace = true
 serde.workspace = true
 serde_json.workspace = true
 crossterm.workspace = true
-semver.workspace = true
 dunce.workspace = true
 
 [dev-dependencies]