Add install params which implement Default

Author: tuguzT

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

@@ -2,31 +2,17 @@
 
 //! Rust GPU shader crate builder.
 //!
-//! This library allows you to easily compile your rust-gpu shaders,
+//! 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.
+//! using [`rustc_codegen_spirv-cache`](cache) crate.
 //!
-//! Then we continue to use rust-gpu's [`spirv-builder`](cache::spirv_builder) crate
+//! Then is uses [`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
+//! but provide you with a toolchain-agnostic version that you may use from stable rustc.
 //!
 //! ## Building shader crates
 //!

crates/cargo-gpu/src/build.rs

@@ -70,14 +70,14 @@ impl Build {
     /// 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 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.force_overwrite_lockfiles_v4_to_v3,
+            self.install.params.force_overwrite_lockfiles_v4_to_v3,
         )?;
 
         let builder = &mut self.build.spirv_builder;

crates/cargo-gpu/src/config.rs

@@ -106,7 +106,7 @@ mod test {
         )
         .unwrap();
         assert!(!args.build.spirv_builder.release);
-        assert!(args.install.auto_install_rust_toolchain);
+        assert!(args.install.params.auto_install_rust_toolchain);
     }
 
     #[test_log::test]
@@ -127,7 +127,7 @@ mod test {
 
         let args = Config::clap_command_with_cargo_config(&shader_crate_path, vec![]).unwrap();
         assert!(!args.build.spirv_builder.release);
-        assert!(args.install.auto_install_rust_toolchain);
+        assert!(args.install.params.auto_install_rust_toolchain);
     }
 
     fn update_cargo_output_dir() -> std::path::PathBuf {

crates/cargo-gpu/src/lib.rs

@@ -67,7 +67,7 @@ impl Command {
                     command.install
                 );
 
-                let skip_consent = command.install.auto_install_rust_toolchain;
+                let skip_consent = command.install.params.auto_install_rust_toolchain;
                 let halt_installation = ask_for_user_consent(skip_consent);
                 command.install.run(std::io::stdout(), halt_installation)?;
             }

crates/rustc_codegen_spirv-cache/src/install.rs

@@ -1,4 +1,17 @@
-//! Install a dedicated per-shader crate that has the `rust-gpu` compiler in it.
+//! This module deals with an installation a dedicated per-shader crate
+//! that has the `rust-gpu` codegen backend in it.
+//!
+//! This process could be described as follows:
+//! * first retrieve the version of rust-gpu you want to use based on the version of the
+//!   `spirv-std` dependency in your shader crate,
+//! * then 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 resulting dylib and clean the target directory.
 
 use std::{
     fs, io,
@@ -20,8 +33,7 @@ use crate::{
     user_output,
 };
 
-/// Settings for an installation of `rustc_codegen_spirv`.
-#[expect(clippy::struct_excessive_bools, reason = "expected to have many bools")]
+/// Settings for an installation of the codegen backend.
 #[derive(Debug, Clone, serde::Deserialize, serde::Serialize)]
 #[cfg_attr(feature = "clap", derive(clap::Parser))]
 #[non_exhaustive]
@@ -34,17 +46,32 @@ pub struct Install {
     #[serde(alias = "package")]
     pub shader_crate: PathBuf,
 
+    /// Parameters of the codegen backend installation.
+    #[cfg_attr(feature = "clap", clap(flatten))]
+    #[serde(flatten)]
+    pub params: InstallParams,
+}
+
+/// Parameters of the codegen backend installation.
+#[expect(clippy::struct_excessive_bools, reason = "expected to have many bools")]
+#[expect(clippy::module_name_repetitions, reason = "this is intended")]
+#[derive(Debug, Clone, serde::Deserialize, serde::Serialize)]
+#[cfg_attr(feature = "clap", derive(clap::Parser))]
+#[non_exhaustive]
+pub struct InstallParams {
     #[expect(
         rustdoc::bare_urls,
         clippy::doc_markdown,
         reason = "The URL should appear literally like this. But Clippy & rustdoc want a markdown clickable link"
     )]
-    /// Source of `spirv-builder` dependency
-    /// Eg: "https://github.com/Rust-GPU/rust-gpu"
+    /// Source of [`spirv-builder`](spirv_builder) dependency.
+    ///
+    /// E.g. "https://github.com/Rust-GPU/rust-gpu".
     #[cfg_attr(feature = "clap", clap(long))]
     pub spirv_builder_source: Option<String>,
 
-    /// Version of `spirv-builder` dependency.
+    /// Version of [`spirv-builder`](spirv_builder) dependency.
+    ///
     /// * If `--spirv-builder-source` is not set, then this is assumed to be a crates.io semantic
     ///   version such as "0.9.0".
     /// * If `--spirv-builder-source` is set, then this is assumed to be a Git "commitsh", such
@@ -58,12 +85,12 @@ pub struct Install {
 
     /// Assume "yes" to "Install Rust toolchain: [y/n]" prompt.
     ///
-    /// Defaults to `false` in cli, `true` in [`Default`]
+    /// Defaults to `false` in cli, `true` in [`Default`] implementation.
     #[cfg_attr(feature = "clap", clap(long, action))]
     pub auto_install_rust_toolchain: bool,
 
-    /// Clear target dir of `rustc_codegen_spirv` build after a successful build, saves about
-    /// 200MiB of disk space.
+    /// Clear target dir of `rustc_codegen_spirv` build after a successful build,
+    /// saves about 200MiB of disk space.
     #[cfg_attr(feature = "clap", clap(long = "no-clear-target", default_value = "true", action = clap::ArgAction::SetFalse))]
     pub clear_target: bool,
 
@@ -92,16 +119,10 @@ pub struct Install {
     pub force_overwrite_lockfiles_v4_to_v3: bool,
 }
 
-impl Install {
-    /// Creates a default installation settings for a shader crate of the given path.
+impl Default for InstallParams {
     #[inline]
-    #[must_use]
-    pub fn from_shader_crate<P>(shader_crate: P) -> Self
-    where
-        P: Into<PathBuf>,
-    {
+    fn default() -> Self {
         Self {
-            shader_crate: shader_crate.into(),
             spirv_builder_source: None,
             spirv_builder_version: None,
             rebuild_codegen: false,
@@ -110,6 +131,33 @@ impl Install {
             force_overwrite_lockfiles_v4_to_v3: false,
         }
     }
+}
+
+impl Install {
+    /// Creates a default installation settings for a shader crate of the given path.
+    #[inline]
+    #[must_use]
+    pub fn from_shader_crate<C>(shader_crate: C) -> Self
+    where
+        C: Into<PathBuf>,
+    {
+        Self::from_shader_crate_with_params(shader_crate, InstallParams::default())
+    }
+
+    /// Creates an installation settings for a shader crate of the given path
+    /// and the given parameters.
+    #[inline]
+    #[must_use]
+    pub fn from_shader_crate_with_params<C, P>(shader_crate: C, params: P) -> Self
+    where
+        C: Into<PathBuf>,
+        P: Into<InstallParams>,
+    {
+        Self {
+            shader_crate: shader_crate.into(),
+            params: params.into(),
+        }
+    }
 
     /// Installs the binary pair and return the [`InstalledBackend`],
     /// from which you can create [`SpirvBuilder`] instances.
@@ -139,8 +187,8 @@ impl Install {
 
         let source = SpirvSource::new(
             &self.shader_crate,
-            self.spirv_builder_source.as_deref(),
-            self.spirv_builder_version.as_deref(),
+            self.params.spirv_builder_source.as_deref(),
+            self.params.spirv_builder_version.as_deref(),
         )?;
         let install_dir = source.install_dir()?;
 
@@ -167,7 +215,8 @@ impl Install {
         }
 
         // if `source` is a path, always rebuild
-        let skip_rebuild = !source.is_path() && dest_dylib_path.is_file() && !self.rebuild_codegen;
+        let skip_rebuild =
+            !source.is_path() && dest_dylib_path.is_file() && !self.params.rebuild_codegen;
         if skip_rebuild {
             log::info!("...and so we are aborting the install step.");
         } else {
@@ -220,7 +269,7 @@ impl Install {
                     fs::rename(&dylib_path, &dest_dylib_path)
                         .map_err(InstallError::MoveRustcCodegenSpirvDylib)?;
 
-                    if self.clear_target {
+                    if self.params.clear_target {
                         log::warn!("clearing target dir {}", target.display());
                         fs::remove_dir_all(&target)
                             .map_err(InstallError::RemoveRustcCodegenSpirvTargetDir)?;

crates/rustc_codegen_spirv-cache/src/toolchain.rs

@@ -5,7 +5,7 @@ use std::process::{Command, Stdio};
 
 use crate::command::{execute_command, CommandExecError};
 
-/// Allows to halt the installation process of toolchain or its required components.
+/// Allows to halt the installation process of toolchain or its [required components](REQUIRED_TOOLCHAIN_COMPONENTS).
 #[derive(Debug, Clone, Copy)]
 #[expect(clippy::exhaustive_structs, reason = "intended to be exhaustive")]
 pub struct HaltToolchainInstallation<T, C> {
@@ -16,7 +16,7 @@ pub struct HaltToolchainInstallation<T, C> {
 }
 
 impl HaltToolchainInstallation<(), ()> {
-    /// Do not halt the installation process of toolchain or its required components.
+    /// Do not halt the installation process of toolchain or its [required components](REQUIRED_TOOLCHAIN_COMPONENTS).
     ///
     /// Calling either [`on_toolchain_install`] or [`on_components_install`]
     /// returns [`Ok`] without any side effects.
@@ -134,7 +134,8 @@ pub fn install_toolchain(channel: &str) -> Result<(), CommandExecError> {
 /// Components which are required to be installed for a toolchain to be usable with `rust-gpu`.
 pub const REQUIRED_TOOLCHAIN_COMPONENTS: [&str; 3] = ["rust-src", "rustc-dev", "llvm-tools"];
 
-/// Checks if all the required components of the given toolchain are installed using `rustup`.
+/// Checks if all the [required components](REQUIRED_TOOLCHAIN_COMPONENTS)
+/// of the given toolchain are installed using `rustup`.
 ///
 /// # Errors
 ///
@@ -163,7 +164,8 @@ pub fn all_required_toolchain_components_installed(
     Ok(installed)
 }
 
-/// Installs all the required components for the given toolchain using `rustup`.
+/// Installs all the [required components](REQUIRED_TOOLCHAIN_COMPONENTS)
+/// for the given toolchain using `rustup`.
 ///
 /// # Errors
 ///