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 = "13a80b7ed9fbd5738746ef31ab8ddfee3f403551", default-features = false }
 anyhow = "1.0.98"
 thiserror = "2.0.12"
 clap = { version = "4.5.41", features = ["derive"] }

Cargo.toml

@@ -9,16 +9,16 @@ 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
 
 [features]
 # Rebuilds target shader crate upon changes
-watch = ["spirv-builder/watch"]
+watch = ["rustc_codegen_spirv-cache/watch"]
 # Enables `clap` support for public structs
-clap = ["spirv-builder/clap", "rustc_codegen_spirv-cache/clap"]
+clap = ["rustc_codegen_spirv-cache/clap"]
 
 [lints]
 workspace = true

crates/cargo-gpu-build/Cargo.toml

@@ -0,0 +1,294 @@
+//! This module provides a `rust-gpu` shader crate builder
+//! usable inside of build scripts or as a part of CLI.
+
+use std::{io, process::Stdio};
+
+use crate::{
+    lockfile::{LockfileMismatchError, LockfileMismatchHandler},
+    spirv_builder::{CompileResult, SpirvBuilder, SpirvBuilderError},
+    spirv_cache::{
+        backend::{Install, InstallError, InstallParams, InstallRunParams, InstalledBackend},
+        command::CommandExecError,
+        toolchain::{
+            HaltToolchainInstallation, InheritStderr, InheritStdout, NoopOnComponentsInstall,
+            NoopOnToolchainInstall, StdioCfg,
+        },
+        user_output,
+    },
+};
+
+#[cfg(feature = "watch")]
+use crate::spirv_builder::SpirvWatcher;
+
+/// Parameters for [`ShaderCrateBuilder::new()`].
+#[derive(Debug, Clone)]
+#[non_exhaustive]
+pub struct ShaderCrateBuilderParams<W, T, C, O, E> {
+    /// Parameters of the shader crate build.
+    pub build: SpirvBuilder,
+    /// Parameters of the codegen backend installation for the shader crate.
+    pub install: InstallParams,
+    /// Writer of user output.
+    pub writer: W,
+    /// Callbacks to halt toolchain installation.
+    pub halt: HaltToolchainInstallation<T, C>,
+    /// Configuration of [`Stdio`] for commands run during installation.
+    pub stdio_cfg: StdioCfg<O, E>,
+}
+
+impl<W, T, C, O, E> ShaderCrateBuilderParams<W, T, C, O, E> {
+    /// Replaces build parameters of the shader crate.
+    #[inline]
+    #[must_use]
+    pub fn build(self, build: SpirvBuilder) -> Self {
+        Self {
+            build,
+            install: self.install,
+            writer: self.writer,
+            halt: self.halt,
+            stdio_cfg: self.stdio_cfg,
+        }
+    }
+
+    /// Replaces codegen backend installation parameters of the shader crate.
+    #[inline]
+    #[must_use]
+    pub fn install(self, install: InstallParams) -> Self {
+        Self {
+            build: self.build,
+            install,
+            writer: self.writer,
+            halt: self.halt,
+            stdio_cfg: self.stdio_cfg,
+        }
+    }
+
+    /// Replaces the writer of user output.
+    #[inline]
+    #[must_use]
+    pub fn writer<NW>(self, writer: NW) -> ShaderCrateBuilderParams<NW, T, C, O, E> {
+        ShaderCrateBuilderParams {
+            build: self.build,
+            install: self.install,
+            writer,
+            halt: self.halt,
+            stdio_cfg: self.stdio_cfg,
+        }
+    }
+
+    /// Replaces the callbacks to halt toolchain installation.
+    #[inline]
+    #[must_use]
+    pub fn halt<NT, NC>(
+        self,
+        halt: HaltToolchainInstallation<NT, NC>,
+    ) -> ShaderCrateBuilderParams<W, NT, NC, O, E> {
+        ShaderCrateBuilderParams {
+            build: self.build,
+            install: self.install,
+            writer: self.writer,
+            halt,
+            stdio_cfg: self.stdio_cfg,
+        }
+    }
+
+    /// Replaces the [`Stdio`] configuration for commands run during installation.
+    #[inline]
+    #[must_use]
+    pub fn stdio_cfg<NO, NE>(
+        self,
+        stdio_cfg: StdioCfg<NO, NE>,
+    ) -> ShaderCrateBuilderParams<W, T, C, NO, NE> {
+        ShaderCrateBuilderParams {
+            build: self.build,
+            install: self.install,
+            writer: self.writer,
+            halt: self.halt,
+            stdio_cfg,
+        }
+    }
+}
+
+/// [`Default`] parameters for [`ShaderCrateBuilder::new()`].
+pub type DefaultShaderCrateBuilderParams = ShaderCrateBuilderParams<
+    io::Stdout,
+    NoopOnToolchainInstall,
+    NoopOnComponentsInstall,
+    InheritStdout,
+    InheritStderr,
+>;
+
+impl DefaultShaderCrateBuilderParams {
+    /// Creates default parameters with the given build parameters.
+    #[inline]
+    #[must_use]
+    pub fn from_build(build: SpirvBuilder) -> Self {
+        Self {
+            build,
+            ..Default::default()
+        }
+    }
+}
+
+impl Default for DefaultShaderCrateBuilderParams {
+    #[inline]
+    fn default() -> Self {
+        Self {
+            build: SpirvBuilder::default(),
+            install: InstallParams::default(),
+            writer: io::stdout(),
+            halt: HaltToolchainInstallation::noop(),
+            stdio_cfg: StdioCfg::inherit(),
+        }
+    }
+}
+
+/// A builder for compiling a `rust-gpu` shader crate.
+#[derive(Debug, Clone)]
+#[non_exhaustive]
+pub struct ShaderCrateBuilder<W = io::Stdout> {
+    /// 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,
+    /// Writer of user output.
+    pub writer: W,
+}
+
+impl<W> ShaderCrateBuilder<W>
+where
+    W: io::Write,
+{
+    /// Creates shader crate builder, allowing to modify install and build parameters separately.
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if:
+    ///
+    /// * the shader crate path / target was not set,
+    /// * the shader crate path is not valid,
+    /// * the backend installation fails,
+    /// * there is a lockfile version mismatch that cannot be resolved automatically.
+    #[inline]
+    pub fn new<R, T, C, O, E>(
+        mut params: ShaderCrateBuilderParams<W, T, C, O, E>,
+    ) -> Result<Self, NewShaderCrateBuilderError<R>>
+    where
+        R: From<CommandExecError>,
+        T: FnOnce(&str) -> Result<(), R>,
+        C: FnOnce(&str) -> Result<(), R>,
+        O: FnMut() -> Stdio,
+        E: FnMut() -> Stdio,
+    {
+        if params.build.target.is_none() {
+            return Err(NewShaderCrateBuilderError::MissingTarget);
+        }
+        let shader_crate = params
+            .build
+            .path_to_crate
+            .as_ref()
+            .ok_or(NewShaderCrateBuilderError::MissingCratePath)?;
+        let shader_crate_path = dunce::canonicalize(shader_crate)?;
+
+        let backend_to_install = Install::new(shader_crate_path, params.install);
+        let backend_install_params = InstallRunParams::default()
+            .writer(&mut params.writer)
+            .halt(HaltToolchainInstallation {
+                on_toolchain_install: |channel: &str| (params.halt.on_toolchain_install)(channel),
+                on_components_install: |channel: &str| (params.halt.on_components_install)(channel),
+            })
+            .stdio_cfg(StdioCfg {
+                stdout: || (params.stdio_cfg.stdout)(),
+                stderr: || (params.stdio_cfg.stderr)(),
+            });
+        let backend = backend_to_install.run(backend_install_params)?;
+
+        let lockfile_mismatch_handler = LockfileMismatchHandler::new(
+            &backend_to_install.shader_crate,
+            &backend.toolchain_channel,
+            backend_to_install.params.force_overwrite_lockfiles_v4_to_v3,
+        )?;
+
+        #[expect(clippy::unreachable, reason = "target was already set")]
+        backend
+            .configure_spirv_builder(&mut params.build)
+            .unwrap_or_else(|_| unreachable!("target was checked before calling this function"));
+
+        Ok(Self {
+            builder: params.build,
+            installed_backend_args: backend_to_install,
+            installed_backend: backend,
+            lockfile_mismatch_handler,
+            writer: params.writer,
+        })
+    }
+
+    /// Builds the shader crate using the configured [`SpirvBuilder`].
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if building the shader crate failed.
+    #[inline]
+    pub fn build(&mut self) -> Result<CompileResult, ShaderCrateBuildError> {
+        let shader_crate = self.installed_backend_args.shader_crate.display();
+        user_output!(&mut self.writer, "Compiling shaders at {shader_crate}...\n")?;
+
+        let result = self.builder.build()?;
+        Ok(result)
+    }
+
+    /// Watches the shader crate for changes using the configured [`SpirvBuilder`].
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if watching shader crate for changes failed.
+    #[cfg(feature = "watch")]
+    #[inline]
+    pub fn watch(&mut self) -> Result<SpirvWatcher, ShaderCrateBuildError> {
+        let shader_crate = self.installed_backend_args.shader_crate.display();
+        user_output!(
+            &mut self.writer,
+            "Watching shaders for changes at {shader_crate}...\n"
+        )?;
+
+        let watcher = self.builder.clone().watch()?;
+        Ok(watcher)
+    }
+}
+
+/// An error indicating what went wrong when creating a [`ShaderCrateBuilder`].
+#[derive(Debug, thiserror::Error)]
+#[non_exhaustive]
+pub enum NewShaderCrateBuilderError<E = CommandExecError> {
+    /// Shader crate target is missing from parameters of the build.
+    #[error("shader crate target must be set, for example `spirv-unknown-vulkan1.2`")]
+    MissingTarget,
+    /// Shader path is missing from parameters of the build.
+    #[error("path to shader crate must be set")]
+    MissingCratePath,
+    /// 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,10 @@
 //! 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")]
 
 pub use rustc_codegen_spirv_cache as spirv_cache;
 pub use rustc_codegen_spirv_cache::spirv_builder;
 
+pub mod build;
 pub mod lockfile;

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]