Making build script API bit by bit

Author: tuguzT

Cargo.lock

@@ -11,6 +11,7 @@ license.workspace = true
 rustc_codegen_spirv-cache.workspace = true
 thiserror.workspace = true
 semver.workspace = true
+dunce.workspace = true
 log.workspace = true
 
 [lints]

crates/cargo-gpu-build/Cargo.toml

@@ -0,0 +1,94 @@
+//! 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::SpirvBuilder,
+    spirv_cache::{
+        command::CommandExecError,
+        install::{Install, InstallError, InstallParams, InstalledBackend},
+        toolchain::HaltToolchainInstallation,
+    },
+};
+
+/// 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 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>>
+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::from_shader_crate_with_params(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,
+}
+
+/// An error indicating what went wrong when creating a [`ShaderCrateBuilder`].
+#[derive(Debug, thiserror::Error)]
+#[non_exhaustive]
+pub enum MakeShaderBuilderError<E> {
+    /// 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),
+}

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

@@ -1,5 +1,3 @@
-#![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,
@@ -8,14 +6,16 @@
 //! # How it works
 //!
 //! This library manages installations of `rustc_codegen_spirv`
-//! using [`rustc_codegen_spirv-cache`](cache) crate.
+//! using [`rustc_codegen_spirv-cache`](spirv_cache) crate.
 //!
-//! Then is uses [`spirv-builder`](cache::spirv_builder) crate
+//! Then is uses [`spirv-builder`](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.
 
-pub use rustc_codegen_spirv_cache as cache;
+#![expect(clippy::pub_use, reason = "pub use for build scripts")]
 
-pub mod lockfile;
+pub use rustc_codegen_spirv_cache as spirv_cache;
+pub use rustc_codegen_spirv_cache::spirv_builder;
 
-// TODO build script API without shader crate path repetitions
+pub mod build;
+pub mod lockfile;

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

@@ -228,7 +228,7 @@ impl LockfileMismatchHandler {
     /// Returns an error if there was a problem reverting any of the lockfiles.
     /// See [`LockfileMismatchError`] for details.
     #[inline]
-    pub fn revert_cargo_lock_manifest_versions(&self) -> Result<(), LockfileMismatchError> {
+    pub fn revert_cargo_lock_manifest_versions(&mut self) -> Result<(), LockfileMismatchError> {
         for offending_cargo_lock in &self.cargo_lock_files_with_changed_manifest_versions {
             log::debug!("Reverting: {}", offending_cargo_lock.display());
             Self::replace_cargo_lock_manifest_version(offending_cargo_lock, "3", "4")?;
@@ -282,7 +282,7 @@ impl Drop for LockfileMismatchHandler {
     fn drop(&mut self) {
         let result = self.revert_cargo_lock_manifest_versions();
         if let Err(error) = result {
-            log::error!("Couldn't revert some or all of the shader `Cargo.lock` files ({error})");
+            log::error!("could not revert some or all of the shader `Cargo.lock` files ({error})");
         }
     }
 }
@@ -335,7 +335,7 @@ pub enum LockfileMismatchError {
     /// Conflicting lockfile manifest versions detected, with advice on how to resolve them
     /// by setting the [`force_overwrite_lockfiles_v4_to_v3`] flag.
     ///
-    /// [`force_overwrite_lockfiles_v4_to_v3`]: crate::cache::install::InstallParams::force_overwrite_lockfiles_v4_to_v3
+    /// [`force_overwrite_lockfiles_v4_to_v3`]: crate::spirv_cache::install::InstallParams::force_overwrite_lockfiles_v4_to_v3
     #[error(
         r#"conflicting `Cargo.lock` versions detected ⚠️
 

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

@@ -1,8 +1,5 @@
 //! `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")]
-
 use core::convert::Infallible;
 use std::{
     io::{self, Write as _},
@@ -11,9 +8,11 @@ use std::{
 };
 
 use anyhow::Context as _;
-use cargo_gpu_build::lockfile::LockfileMismatchHandler;
-use rustc_codegen_spirv_cache::install::Install;
-use spirv_builder::{CompileResult, ModuleResult, SpirvBuilder, Watch};
+use cargo_gpu_build::{
+    build::shader_crate_builder,
+    spirv_builder::{CompileResult, ModuleResult, SpirvBuilder, SpirvBuilderError, Watch},
+    spirv_cache::install::Install,
+};
 
 use crate::{linkage::Linkage, user_consent::ask_for_user_consent};
 
@@ -73,19 +72,20 @@ impl Build {
     /// Returns an error if the build process fails somehow.
     #[inline]
     pub fn run(&mut self) -> anyhow::Result<()> {
-        let skip_consent = self.install.params.auto_install_rust_toolchain;
-        let halt_installation = ask_for_user_consent(skip_consent);
-        let installed_backend = self.install.run(io::stdout(), halt_installation)?;
-
-        let _lockfile_mismatch_handler = LockfileMismatchHandler::new(
-            &self.install.shader_crate,
-            &installed_backend.toolchain_channel,
-            self.install.params.force_overwrite_lockfiles_v4_to_v3,
+        let crate_builder = shader_crate_builder(
+            self.install.shader_crate.clone(),
+            self.build
+                .spirv_builder
+                .target
+                .as_deref()
+                .ok_or(SpirvBuilderError::MissingTarget)?,
+            self.build.spirv_builder.clone(),
+            self.install.params.clone(),
+            io::stdout(),
+            ask_for_user_consent(self.install.params.auto_install_rust_toolchain),
         )?;
-
-        let builder = &mut self.build.spirv_builder;
-        builder.path_to_crate = Some(self.install.shader_crate.clone());
-        installed_backend.configure_spirv_builder(builder)?;
+        self.install = crate_builder.installed_backend_args;
+        self.build.spirv_builder = crate_builder.builder;
 
         // Ensure the shader output dir exists
         log::debug!(
@@ -97,15 +97,6 @@ impl Build {
         log::debug!("canonicalized output dir: {}", canonicalized.display());
         self.build.output_dir = canonicalized;
 
-        // Ensure the shader crate exists
-        self.install.shader_crate = dunce::canonicalize(&self.install.shader_crate)?;
-        anyhow::ensure!(
-            self.install.shader_crate.exists(),
-            "shader crate '{}' does not exist. (Current dir is '{}')",
-            self.install.shader_crate.display(),
-            std::env::current_dir()?.display()
-        );
-
         if self.build.watch {
             let never = self.watch()?;
             match never {}
@@ -127,17 +118,21 @@ impl Build {
     /// Watches shader crate for changes using [`SpirvBuilder`].
     fn watch(&self) -> 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 {
             first_compile,
             watch_thread,
             ..
-        } = 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);
-            }
-        })?;
-
+        } = watch;
         first_compile
             .context("should always return the first compile result")
             .flatten()?;