build_script: replace enum MetadataPrintout with struct BuildScriptConfig for more flexibility

Author: Firestar99

crates/spirv-builder/src/lib.rs

@@ -123,8 +123,10 @@ pub enum SpirvBuilderError {
     MissingTargetSpec,
     #[error("build failed")]
     BuildFailed,
-    #[error("multi-module build cannot be used with print_metadata = MetadataPrintout::Full")]
-    MultiModuleWithPrintMetadata,
+    #[error(
+        "`multimodule: true` build cannot be used together with `build_script.env_shader_spv_path: true`"
+    )]
+    MultiModuleWithEnvShaderSpvPath,
     #[error("multi-module metadata file missing")]
     MetadataFileMissing(#[from] std::io::Error),
     #[error("unable to parse multi-module metadata file")]
@@ -138,21 +140,6 @@ pub enum SpirvBuilderError {
 
 const SPIRV_TARGET_PREFIX: &str = "spirv-unknown-";
 
-#[derive(Debug, PartialEq, Eq, Clone, Copy, Default, serde::Deserialize, serde::Serialize)]
-#[cfg_attr(feature = "clap", derive(clap::ValueEnum))]
-#[non_exhaustive]
-pub enum MetadataPrintout {
-    /// Print no cargo metadata.
-    #[default]
-    None,
-    /// Print only dependency information (eg for multiple modules).
-    DependencyOnly,
-    /// Print all cargo metadata.
-    ///
-    /// Includes dependency information and spirv environment variable.
-    Full,
-}
-
 #[derive(Debug, PartialEq, Eq, Clone, Copy, Default, serde::Deserialize, serde::Serialize)]
 #[cfg_attr(feature = "clap", derive(clap::ValueEnum))]
 #[non_exhaustive]
@@ -396,6 +383,48 @@ impl Default for ShaderCrateFeatures {
     }
 }
 
+/// Configuration for build scripts
+#[derive(Clone, Debug, Default)]
+#[non_exhaustive]
+pub struct BuildScriptConfig {
+    /// Enable this if you are using `spirv-builder` from a build script to apply some recommended default options, such
+    /// as [`Self::dependency_info`].
+    pub defaults: bool,
+
+    /// Print dependency information for cargo build scripts (with `cargo::rerun-if-changed={}` and such).
+    /// Dependency information makes cargo rerun the build script is rerun when shader source files change, thus
+    /// rebuilding the shader.
+    ///
+    /// Default: [`Self::defaults`]
+    pub dependency_info: Option<bool>,
+
+    /// Whether to emit the env var `SHADER_SPV_PATH` pointing to the shader module file  (via `cargo::rustc-env={}`).
+    /// Not supported together with `multimodule=true` or `.watch()`.
+    ///
+    /// Some examples on how to include the shader module in the source code:
+    /// * wgpu:
+    /// ```norun
+    /// let shader: ShaderModuleDescriptorPassthrough = include_spirv_raw!(env!("SHADER_SPV_PATH"));
+    /// ```
+    /// * ash
+    /// ```norun
+    /// let bytes: &[u8] = include_bytes!(env!("SHADER_SPV_PATH"))
+    /// let words = ash::util::read_spv(&mut std::io::Cursor::new(bytes)).unwrap();
+    /// ```
+    ///
+    /// Default: `false`
+    pub env_shader_spv_path: Option<bool>,
+}
+
+impl BuildScriptConfig {
+    fn dependency_info(&self) -> bool {
+        self.dependency_info.unwrap_or(self.defaults)
+    }
+    fn env_shader_spv_path(&self) -> bool {
+        self.env_shader_spv_path.unwrap_or(false)
+    }
+}
+
 #[derive(Clone, Debug, serde::Deserialize, serde::Serialize)]
 #[cfg_attr(feature = "clap", derive(clap::Parser))]
 #[non_exhaustive]
@@ -410,10 +439,10 @@ pub struct SpirvBuilder {
     /// `--crate-type dylib`. Defaults to true if `cargo_cmd` is `None` or `Some("rustc")`.
     #[cfg_attr(feature = "clap", clap(skip))]
     pub cargo_cmd_like_rustc: Option<bool>,
-    /// Whether to print build.rs cargo metadata (e.g. cargo:rustc-env=var=val). Defaults to [`MetadataPrintout::None`].
-    /// Within build scripts, set it to [`MetadataPrintout::DependencyOnly`] or [`MetadataPrintout::Full`] to ensure the build script is rerun on code changes.
+    /// Configuration for build scripts
     #[cfg_attr(feature = "clap", clap(skip))]
-    pub print_metadata: MetadataPrintout,
+    #[serde(skip)]
+    pub build_script: BuildScriptConfig,
     /// Build in release. Defaults to true.
     #[cfg_attr(feature = "clap", clap(long = "debug", default_value = "true", action = clap::ArgAction::SetFalse))]
     pub release: bool,
@@ -507,7 +536,7 @@ impl Default for SpirvBuilder {
             path_to_crate: None,
             cargo_cmd: None,
             cargo_cmd_like_rustc: None,
-            print_metadata: MetadataPrintout::default(),
+            build_script: BuildScriptConfig::default(),
             release: true,
             target: None,
             deny_warnings: false,
@@ -548,13 +577,6 @@ impl SpirvBuilder {
         self
     }
 
-    /// Whether to print build.rs cargo metadata (e.g. cargo:rustc-env=var=val). Defaults to [`MetadataPrintout::Full`].
-    #[must_use]
-    pub fn print_metadata(mut self, v: MetadataPrintout) -> Self {
-        self.print_metadata = v;
-        self
-    }
-
     #[must_use]
     pub fn deny_warnings(mut self, v: bool) -> Self {
         self.deny_warnings = v;
@@ -704,15 +726,12 @@ impl SpirvBuilder {
     /// in the result, as the environment variable for the path to the module will already be set.
     pub fn build(&self) -> Result<CompileResult, SpirvBuilderError> {
         let metadata_file = invoke_rustc(self)?;
-        match self.print_metadata {
-            MetadataPrintout::Full | MetadataPrintout::DependencyOnly => {
-                leaf_deps(&metadata_file, |artifact| {
-                    println!("cargo:rerun-if-changed={artifact}");
-                })
-                // Close enough
-                .map_err(SpirvBuilderError::MetadataFileMissing)?;
-            }
-            MetadataPrintout::None => (),
+        if self.build_script.dependency_info() {
+            leaf_deps(&metadata_file, |artifact| {
+                println!("cargo:rerun-if-changed={artifact}");
+            })
+            // Close enough
+            .map_err(SpirvBuilderError::MetadataFileMissing)?;
         }
         let metadata = self.parse_metadata_file(&metadata_file)?;
 
@@ -731,17 +750,11 @@ impl SpirvBuilder {
         match &metadata.module {
             ModuleResult::SingleModule(spirv_module) => {
                 assert!(!self.multimodule);
-                let env_var = format!(
-                    "{}.spv",
-                    at.file_name()
-                        .unwrap()
-                        .to_str()
-                        .unwrap()
-                        .strip_suffix(ARTIFACT_SUFFIX)
-                        .unwrap()
-                );
-                if self.print_metadata == MetadataPrintout::Full {
-                    println!("cargo:rustc-env={}={}", env_var, spirv_module.display());
+                if self.build_script.env_shader_spv_path() {
+                    println!(
+                        "cargo::rustc-env=SHADER_SPV_PATH={}",
+                        spirv_module.display()
+                    );
                 }
             }
             ModuleResult::MultiModule(_) => {
@@ -839,8 +852,8 @@ fn invoke_rustc(builder: &SpirvBuilder) -> Result<PathBuf, SpirvBuilderError> {
             }
         }
 
-        if (builder.print_metadata == MetadataPrintout::Full) && builder.multimodule {
-            return Err(SpirvBuilderError::MultiModuleWithPrintMetadata);
+        if builder.build_script.env_shader_spv_path() && builder.multimodule {
+            return Err(SpirvBuilderError::MultiModuleWithEnvShaderSpvPath);
         }
         if !path_to_crate.is_dir() {
             return Err(SpirvBuilderError::CratePathDoesntExist(
@@ -905,7 +918,7 @@ fn invoke_rustc(builder: &SpirvBuilder) -> Result<PathBuf, SpirvBuilderError> {
 
     // Wrapper for `env::var` that appropriately informs Cargo of the dependency.
     let tracked_env_var_get = |name| {
-        if let MetadataPrintout::Full | MetadataPrintout::DependencyOnly = builder.print_metadata {
+        if builder.build_script.dependency_info() {
             println!("cargo:rerun-if-env-changed={name}");
         }
         env::var(name)

crates/spirv-builder/src/watch.rs

@@ -55,7 +55,7 @@ impl SpirvWatcher {
             .as_ref()
             .ok_or(SpirvBuilderError::MissingCratePath)?
             .clone();
-        if !matches!(builder.print_metadata, crate::MetadataPrintout::None) {
+        if builder.build_script.env_shader_spv_path() {
             return Err(SpirvWatcherError::WatchWithPrintMetadata.into());
         }
 

examples/runners/ash/src/main.rs

@@ -78,7 +78,7 @@ use ash::util::read_spv;
 use clap::{Parser, ValueEnum};
 use raw_window_handle::HasDisplayHandle as _;
 use shared::ShaderConstants;
-use spirv_builder::{MetadataPrintout, SpirvBuilder};
+use spirv_builder::SpirvBuilder;
 use std::{
     fs::File,
     path::PathBuf,
@@ -259,7 +259,6 @@ pub fn compile_shaders(shader: &RustGPUShader) -> anyhow::Result<Vec<u32>> {
         .collect::<PathBuf>();
 
     let compile_result = SpirvBuilder::new(crate_path, "spirv-unknown-vulkan1.3")
-        .print_metadata(MetadataPrintout::None)
         .shader_panic_strategy(spirv_builder::ShaderPanicStrategy::DebugPrintfThenExit {
             print_inputs: true,
             print_backtrace: true,

examples/runners/wgpu/src/lib.rs

@@ -124,7 +124,7 @@ fn maybe_watch(
 ) -> CompiledShaderModules {
     #[cfg(not(any(target_os = "android", target_arch = "wasm32")))]
     {
-        use spirv_builder::{CompileResult, MetadataPrintout, SpirvBuilder};
+        use spirv_builder::{CompileResult, SpirvBuilder};
         use std::path::PathBuf;
 
         let crate_name = match options.shader {
@@ -142,7 +142,6 @@ fn maybe_watch(
         let has_debug_printf = options.force_spirv_passthru;
 
         let builder = SpirvBuilder::new(crate_path, "spirv-unknown-vulkan1.1")
-            .print_metadata(MetadataPrintout::None)
             .shader_panic_strategy(if has_debug_printf {
                 spirv_builder::ShaderPanicStrategy::DebugPrintfThenExit {
                     print_inputs: true,