spirv_builder/
lib.rs

1// FIXME(eddyb) update/review these lints.
2//
3// BEGIN - Embark standard lints v0.4
4// do not change or add/remove here, but one can add exceptions after this section
5// for more info see: <https://github.com/EmbarkStudios/rust-ecosystem/issues/59>
6#![deny(unsafe_code)]
7#![warn(
8    clippy::all,
9    clippy::await_holding_lock,
10    clippy::char_lit_as_u8,
11    clippy::checked_conversions,
12    clippy::dbg_macro,
13    clippy::debug_assert_with_mut_call,
14    clippy::doc_markdown,
15    clippy::empty_enum,
16    clippy::enum_glob_use,
17    clippy::exit,
18    clippy::expl_impl_clone_on_copy,
19    clippy::explicit_deref_methods,
20    clippy::explicit_into_iter_loop,
21    clippy::fallible_impl_from,
22    clippy::filter_map_next,
23    clippy::float_cmp_const,
24    clippy::fn_params_excessive_bools,
25    clippy::if_let_mutex,
26    clippy::implicit_clone,
27    clippy::imprecise_flops,
28    clippy::inefficient_to_string,
29    clippy::invalid_upcast_comparisons,
30    clippy::large_types_passed_by_value,
31    clippy::let_unit_value,
32    clippy::linkedlist,
33    clippy::lossy_float_literal,
34    clippy::macro_use_imports,
35    clippy::manual_ok_or,
36    clippy::map_err_ignore,
37    clippy::map_flatten,
38    clippy::map_unwrap_or,
39    clippy::match_same_arms,
40    clippy::match_wildcard_for_single_variants,
41    clippy::mem_forget,
42    clippy::mut_mut,
43    clippy::mutex_integer,
44    clippy::needless_borrow,
45    clippy::needless_continue,
46    clippy::option_option,
47    clippy::path_buf_push_overwrite,
48    clippy::ptr_as_ptr,
49    clippy::ref_option_ref,
50    clippy::rest_pat_in_fully_bound_structs,
51    clippy::same_functions_in_if_condition,
52    clippy::semicolon_if_nothing_returned,
53    clippy::string_add_assign,
54    clippy::string_add,
55    clippy::string_lit_as_bytes,
56    clippy::string_to_string,
57    clippy::todo,
58    clippy::trait_duplication_in_bounds,
59    clippy::unimplemented,
60    clippy::unnested_or_patterns,
61    clippy::unused_self,
62    clippy::useless_transmute,
63    clippy::verbose_file_reads,
64    clippy::zero_sized_map_values,
65    future_incompatible,
66    nonstandard_style,
67    rust_2018_idioms
68)]
69// END - Embark standard lints v0.4
70// crate-specific exceptions:
71// #![allow()]
72#![doc = include_str!("../README.md")]
73
74pub mod cargo_cmd;
75mod depfile;
76#[cfg(feature = "watch")]
77mod watch;
78
79use raw_string::{RawStr, RawString};
80use semver::Version;
81use serde::Deserialize;
82use std::borrow::Borrow;
83use std::collections::HashMap;
84use std::env;
85use std::fs::File;
86use std::io::BufReader;
87use std::path::{Path, PathBuf};
88use std::process::{Command, Stdio};
89use thiserror::Error;
90
91pub use rustc_codegen_spirv_types::Capability;
92pub use rustc_codegen_spirv_types::{CompileResult, ModuleResult};
93
94#[cfg(feature = "watch")]
95pub use self::watch::Watch;
96
97#[cfg(feature = "include-target-specs")]
98pub use rustc_codegen_spirv_target_specs::TARGET_SPEC_DIR_PATH;
99
100#[derive(Debug, Error)]
101#[non_exhaustive]
102pub enum SpirvBuilderError {
103    #[error("`target` must be set, for example `spirv-unknown-vulkan1.2`")]
104    MissingTarget,
105    #[error("expected `{SPIRV_TARGET_PREFIX}...` target, found `{target}`")]
106    NonSpirvTarget { target: String },
107    #[error("SPIR-V target `{SPIRV_TARGET_PREFIX}-{target_env}` is not supported")]
108    UnsupportedSpirvTargetEnv { target_env: String },
109    #[error("`path_to_crate` must be set")]
110    MissingCratePath,
111    #[error("crate path '{0}' does not exist")]
112    CratePathDoesntExist(PathBuf),
113    #[error(
114        "Without feature `rustc_codegen_spirv`, you need to set the path of the dylib with `rustc_codegen_spirv_location`"
115    )]
116    MissingRustcCodegenSpirvDylib,
117    #[error("`rustc_codegen_spirv_location` path '{0}' is not a file")]
118    RustcCodegenSpirvDylibDoesNotExist(PathBuf),
119    #[error(
120        "Without feature `include-target-specs`, instead of setting a `target`, \
121        you need to set the path of the target spec file of your particular target with `path_to_target_spec`"
122    )]
123    MissingTargetSpec,
124    #[error("build failed")]
125    BuildFailed,
126    #[error("multi-module build cannot be used with print_metadata = MetadataPrintout::Full")]
127    MultiModuleWithPrintMetadata,
128    #[error("watching within build scripts will prevent build completion")]
129    WatchWithPrintMetadata,
130    #[error("multi-module metadata file missing")]
131    MetadataFileMissing(#[from] std::io::Error),
132    #[error("unable to parse multi-module metadata file")]
133    MetadataFileMalformed(#[from] serde_json::Error),
134    #[error("cargo metadata error")]
135    CargoMetadata(#[from] cargo_metadata::Error),
136}
137
138const SPIRV_TARGET_PREFIX: &str = "spirv-unknown-";
139
140#[derive(Debug, PartialEq, Eq, Clone, Copy, Default, serde::Deserialize, serde::Serialize)]
141#[cfg_attr(feature = "clap", derive(clap::ValueEnum))]
142#[non_exhaustive]
143pub enum MetadataPrintout {
144    /// Print no cargo metadata.
145    #[default]
146    None,
147    /// Print only dependency information (eg for multiple modules).
148    DependencyOnly,
149    /// Print all cargo metadata.
150    ///
151    /// Includes dependency information and spirv environment variable.
152    Full,
153}
154
155#[derive(Debug, PartialEq, Eq, Clone, Copy, Default, serde::Deserialize, serde::Serialize)]
156#[cfg_attr(feature = "clap", derive(clap::ValueEnum))]
157#[non_exhaustive]
158pub enum SpirvMetadata {
159    /// Strip all names and other debug information from SPIR-V output.
160    #[default]
161    None,
162    /// Only include `OpName`s for public interface variables (uniforms and the like), to allow
163    /// shader reflection.
164    NameVariables,
165    /// Include all `OpName`s for everything, and `OpLine`s. Significantly increases binary size.
166    Full,
167}
168
169/// Strategy used to handle Rust `panic!`s in shaders compiled to SPIR-V.
170#[derive(Debug, PartialEq, Eq, Clone, Copy, Default, serde::Deserialize, serde::Serialize)]
171#[cfg_attr(feature = "clap", derive(clap::ValueEnum))]
172#[non_exhaustive]
173pub enum ShaderPanicStrategy {
174    /// Return from shader entry-point with no side-effects **(default)**.
175    ///
176    /// While similar to the standard SPIR-V `OpTerminateInvocation`, this is
177    /// *not* limited to fragment shaders, and instead supports all shaders
178    /// (as it's handled via control-flow rewriting, instead of SPIR-V features).
179    #[default]
180    SilentExit,
181
182    /// Like `SilentExit`, but also using `debugPrintf` to report the panic in
183    /// a way that can reach the user, before returning from the entry-point.
184    ///
185    /// Quick setup for enabling `debugPrintf` output (to stdout) at runtime:
186    /// - **set these environment variables**:
187    ///   - `VK_LOADER_LAYERS_ENABLE=VK_LAYER_KHRONOS_validation`
188    ///   - `VK_LAYER_PRINTF_ONLY_PRESET=1`
189    ///   - `VK_LAYER_PRINTF_TO_STDOUT=1` (not always needed, but can help)
190    /// - if using `wgpu`, enable `wgpu::Features::SPIRV_SHADER_PASSTHROUGH`,
191    ///   and use `create_shader_module_passthrough` instead of `create_shader_module`
192    /// - in case of errors, or no output (from a `panic!()`/`debug_printf!()`),
193    ///   keep reading below for additional information and alternatives
194    ///
195    /// ---
196    ///
197    /// **Note**: enabling this automatically adds the `SPV_KHR_non_semantic_info`
198    /// extension, as `debugPrintf` is from a "non-semantic extended instruction set".
199    ///
200    /// **Note**: `debugPrintf` output reaching the user involves:
201    /// - being able to load the shader in the first place:
202    ///   - for `wgpu`, use "SPIR-V shader passthrough" (Naga lacks `debugPrintf`):
203    ///     - enable `wgpu::Features::SPIRV_SHADER_PASSTHROUGH`
204    ///     - replace `create_shader_module` calls with `create_shader_module_passthrough`
205    ///   - *in theory*, the `VK_KHR_shader_non_semantic_info` Vulkan *Device* extension
206    ///     (or requiring at least Vulkan 1.3, which incorporated it)
207    ///     - *however*, Validation Layers don't actually check this anymore,
208    ///       since Vulkan SDK version 1.4.313.0 (and drivers shouldn't care either)
209    /// - **general configurability** of [Vulkan SDK](https://vulkan.lunarg.com/sdk/home)
210    ///   and/or [Vulkan Loader](https://github.com/KhronosGroup/Vulkan-Loader)
211    ///   - *(this list doubles as a legend for shorthands used later below)*
212    ///   - **env**: setting environment variables on the fly
213    ///     - easiest for quick testing, no code changes/rebuilding needed
214    ///     - e.g. `FOO=1 cargo run ...` (in UNIX-style shells)
215    ///   - **instance**: programmatic control via `vkCreateInstance()` params
216    ///     - best for integration with app-specific debugging functionality
217    ///     - limited to direct Vulkan usage (e.g. `ash`, not `wgpu`)
218    ///     - `VK_EXT_layer_settings` as a `VK_LAYER_*` environment variables
219    ///       analogue, e.g. `VK_LAYER_FOO` controlled by a `VkLayerSettingEXT`
220    ///       with `"foo"` as `pSettingName` (and an appropriate `type`/value),
221    ///       included in `VkLayerSettingsCreateInfoEXT`'s `pSettings`
222    ///   - on-disk configuration and interactive tooling, e.g.:
223    ///     - `vk_layer_settings.txt` files, either hand-written, or generated by
224    ///       the "Vulkan Configurator" GUI tool (included with the Vulkan SDK)
225    ///     - third-party Vulkan debuggers like `RenderDoc`
226    /// - [Vulkan Validation Layers](https://github.com/KhronosGroup/Vulkan-ValidationLayers)
227    ///   - (they contain the `debugPrintf` implementation, a SPIR-V -> SPIR-V translation)
228    ///   - enabled by one of (as per "**general configurability**" above):
229    ///     - **env**: `VK_LOADER_LAYERS_ENABLE=VK_LAYER_KHRONOS_validation`
230    ///     - **instance**: `"VK_LAYER_KHRONOS_validation"` in the list of layers
231    ///     - via `wgpu`: `wgpu::InstanceFlags::VALIDATION`
232    /// - Validation Layers' `debugPrintf` support
233    ///   ([official docs](https://github.com/KhronosGroup/Vulkan-ValidationLayers/blob/main/docs/debug_printf.md)):
234    ///   - enabled by one of (as per "**general configurability**" above):
235    ///     - **env**: `VK_LAYER_PRINTF_ENABLE=1` (validation + `debugPrintf`)
236    ///     - **env**: `VK_LAYER_PRINTF_ONLY_PRESET=1` (*only* `debugPrintf`, no validation)
237    ///     - **instance**: `"printf_enable"` / `"printf_only_preset"` via `VkLayerSettingEXT`
238    ///       (i.e. analogues for the two environment variables)
239    ///     - **instance**: `VkValidationFeaturesEXT` with `pEnabledValidationFeatures`
240    ///       containing `VK_VALIDATION_FEATURE_ENABLE_DEBUG_PRINTF_EXT`
241    /// - outputting the `debugPrintf` messages sent back from the GPU:
242    ///   - defaults to common validation logging (itself defaulting to stdout)
243    ///   - **env**: `VK_LAYER_PRINTF_TO_STDOUT=1` (and its **instance** analogue)
244    ///     forces direct printing to stdout, bypassing `VK_EXT_debug_utils` etc.
245    ///   - validation logging can itself be controlled via `VK_EXT_debug_utils`
246    ///   - `wgpu` built in debug mode (and/or with debug-assertions enabled):
247    ///     - it uses `VK_EXT_debug_utils` internally, exposing it via `log`
248    ///     - with e.g. `env_logger`, `RUST_LOG=info` suffices for `debugPrintf`
249    ///       messages (as they specifically have the "info" level)
250    ///     - other `log`/`tracing` subscribers should be configured similarly
251    #[cfg_attr(feature = "clap", clap(skip))]
252    DebugPrintfThenExit {
253        /// Whether to also print the entry-point inputs (excluding buffers/resources),
254        /// which should uniquely identify the panicking shader invocation.
255        print_inputs: bool,
256
257        /// Whether to also print a "backtrace" (i.e. the chain of function calls
258        /// that led to the `panic!`).
259        ///
260        /// As there is no way to dynamically compute this information, the string
261        /// containing the full backtrace of each `panic!` is statically generated,
262        /// meaning this option could significantly increase binary size.
263        print_backtrace: bool,
264    },
265
266    /// **Warning**: this is _**unsound**_ (i.e. adds Undefined Behavior to *safe* Rust code)
267    ///
268    /// This option only exists for testing (hence the unfriendly name it has),
269    /// and more specifically testing whether conditional panics are responsible
270    /// for performance differences when upgrading from older Rust-GPU versions
271    /// (which used infinite loops for panics, that `spirv-opt`/drivers could've
272    /// sometimes treated as UB, and optimized as if they were impossible to reach).
273    ///
274    /// Unlike those infinite loops, however, this uses `OpUnreachable`, so it
275    /// forces the old worst-case (all `panic!`s become UB and are optimized out).
276    #[allow(non_camel_case_types)]
277    UNSOUND_DO_NOT_USE_UndefinedBehaviorViaUnreachable,
278}
279
280/// Options for specifying the behavior of the validator
281/// Copied from `spirv-tools/src/val.rs` struct `ValidatorOptions`, with some fields disabled.
282#[derive(Default, Debug, Clone, serde::Deserialize, serde::Serialize)]
283#[cfg_attr(feature = "clap", derive(clap::Parser))]
284#[non_exhaustive]
285pub struct ValidatorOptions {
286    /// Record whether or not the validator should relax the rules on types for
287    /// stores to structs.  When relaxed, it will allow a type mismatch as long as
288    /// the types are structs with the same layout.  Two structs have the same layout
289    /// if
290    ///
291    /// 1) the members of the structs are either the same type or are structs with
292    ///    same layout, and
293    ///
294    /// 2) the decorations that affect the memory layout are identical for both
295    ///    types.  Other decorations are not relevant.
296    #[cfg_attr(feature = "clap", arg(long, default_value = "false"))]
297    pub relax_struct_store: bool,
298    /// Records whether or not the validator should relax the rules on pointer usage
299    /// in logical addressing mode.
300    ///
301    /// When relaxed, it will allow the following usage cases of pointers:
302    /// 1) `OpVariable` allocating an object whose type is a pointer type
303    /// 2) `OpReturnValue` returning a pointer value
304    #[cfg_attr(feature = "clap", arg(long, default_value = "false"))]
305    pub relax_logical_pointer: bool,
306    // /// Records whether or not the validator should relax the rules because it is
307    // /// expected that the optimizations will make the code legal.
308    // ///
309    // /// When relaxed, it will allow the following:
310    // /// 1) It will allow relaxed logical pointers.  Setting this option will also
311    // ///    set that option.
312    // /// 2) Pointers that are pass as parameters to function calls do not have to
313    // ///    match the storage class of the formal parameter.
314    // /// 3) Pointers that are actaul parameters on function calls do not have to point
315    // ///    to the same type pointed as the formal parameter.  The types just need to
316    // ///    logically match.
317    // pub before_legalization: bool,
318    /// Records whether the validator should use "relaxed" block layout rules.
319    /// Relaxed layout rules are described by Vulkan extension
320    /// `VK_KHR_relaxed_block_layout`, and they affect uniform blocks, storage blocks,
321    /// and push constants.
322    ///
323    /// This is enabled by default when targeting Vulkan 1.1 or later.
324    /// Relaxed layout is more permissive than the default rules in Vulkan 1.0.
325    #[cfg_attr(feature = "clap", arg(long, default_value = "false"))]
326    pub relax_block_layout: Option<bool>,
327    /// Records whether the validator should use standard block layout rules for
328    /// uniform blocks.
329    #[cfg_attr(feature = "clap", arg(long, default_value = "false"))]
330    pub uniform_buffer_standard_layout: bool,
331    /// Records whether the validator should use "scalar" block layout rules.
332    /// Scalar layout rules are more permissive than relaxed block layout.
333    ///
334    /// See Vulkan extnesion `VK_EXT_scalar_block_layout`.  The scalar alignment is
335    /// defined as follows:
336    /// - scalar alignment of a scalar is the scalar size
337    /// - scalar alignment of a vector is the scalar alignment of its component
338    /// - scalar alignment of a matrix is the scalar alignment of its component
339    /// - scalar alignment of an array is the scalar alignment of its element
340    /// - scalar alignment of a struct is the max scalar alignment among its
341    ///   members
342    ///
343    /// For a struct in Uniform, `StorageClass`, or `PushConstant`:
344    /// - a member Offset must be a multiple of the member's scalar alignment
345    /// - `ArrayStride` or `MatrixStride` must be a multiple of the array or matrix
346    ///   scalar alignment
347    #[cfg_attr(feature = "clap", arg(long, default_value = "false"))]
348    pub scalar_block_layout: bool,
349    /// Records whether or not the validator should skip validating standard
350    /// uniform/storage block layout.
351    #[cfg_attr(feature = "clap", arg(long, default_value = "false"))]
352    pub skip_block_layout: bool,
353    // /// Applies a maximum to one or more Universal limits
354    // pub max_limits: Vec<(ValidatorLimits, u32)>,
355}
356
357/// Options for specifying the behavior of the optimizer
358/// Copied from `spirv-tools/src/opt.rs` struct `Options`, with some fields disabled.
359#[derive(Default, Debug, Clone, serde::Deserialize, serde::Serialize)]
360#[cfg_attr(feature = "clap", derive(clap::Parser))]
361#[non_exhaustive]
362pub struct OptimizerOptions {
363    // /// Records the validator options that should be passed to the validator,
364    // /// the validator will run with the options before optimizer.
365    // pub validator_options: Option<crate::val::ValidatorOptions>,
366    // /// Records the maximum possible value for the id bound.
367    // pub max_id_bound: Option<u32>,
368    /// Records whether all bindings within the module should be preserved.
369    #[cfg_attr(feature = "clap", arg(long, default_value = "false"))]
370    pub preserve_bindings: bool,
371    // /// Records whether all specialization constants within the module
372    // /// should be preserved.
373    // pub preserve_spec_constants: bool,
374}
375
376/// Cargo features specification for building the shader crate.
377#[derive(Clone, Debug, serde::Deserialize, serde::Serialize)]
378#[cfg_attr(feature = "clap", derive(clap::Parser))]
379#[non_exhaustive]
380pub struct ShaderCrateFeatures {
381    /// Set --default-features for the target shader crate.
382    #[cfg_attr(feature = "clap", clap(long = "no-default-features", default_value = "true", action = clap::ArgAction::SetFalse))]
383    pub default_features: bool,
384    /// Set --features for the target shader crate.
385    #[cfg_attr(feature = "clap", clap(long))]
386    pub features: Vec<String>,
387}
388
389impl Default for ShaderCrateFeatures {
390    fn default() -> Self {
391        Self {
392            default_features: true,
393            features: Vec::new(),
394        }
395    }
396}
397
398#[derive(Clone, Debug, serde::Deserialize, serde::Serialize)]
399#[cfg_attr(feature = "clap", derive(clap::Parser))]
400#[non_exhaustive]
401pub struct SpirvBuilder {
402    #[cfg_attr(feature = "clap", clap(skip))]
403    pub path_to_crate: Option<PathBuf>,
404    /// Whether to print build.rs cargo metadata (e.g. cargo:rustc-env=var=val). Defaults to [`MetadataPrintout::None`].
405    /// Within build scripts, set it to [`MetadataPrintout::DependencyOnly`] or [`MetadataPrintout::Full`] to ensure the build script is rerun on code changes.
406    #[cfg_attr(feature = "clap", clap(skip))]
407    pub print_metadata: MetadataPrintout,
408    /// Build in release. Defaults to true.
409    #[cfg_attr(feature = "clap", clap(long = "debug", default_value = "true", action = clap::ArgAction::SetFalse))]
410    pub release: bool,
411    /// The target triple, eg. `spirv-unknown-vulkan1.2`
412    #[cfg_attr(
413        feature = "clap",
414        clap(long, default_value = "spirv-unknown-vulkan1.2")
415    )]
416    pub target: Option<String>,
417    /// Cargo features specification for building the shader crate.
418    #[cfg_attr(feature = "clap", clap(flatten))]
419    #[serde(flatten)]
420    pub shader_crate_features: ShaderCrateFeatures,
421    /// Deny any warnings, as they may never be printed when building within a build script. Defaults to false.
422    #[cfg_attr(feature = "clap", arg(long, default_value = "false"))]
423    pub deny_warnings: bool,
424    /// Splits the resulting SPIR-V file into one module per entry point. This is useful in cases
425    /// where ecosystem tooling has bugs around multiple entry points per module - having all entry
426    /// points bundled into a single file is the preferred system.
427    #[cfg_attr(feature = "clap", arg(long, default_value = "false"))]
428    pub multimodule: bool,
429    /// Sets the level of metadata (primarily `OpName` and `OpLine`) included in the SPIR-V binary.
430    /// Including metadata significantly increases binary size.
431    #[cfg_attr(feature = "clap", arg(long, default_value = "none"))]
432    pub spirv_metadata: SpirvMetadata,
433    /// Adds a capability to the SPIR-V module. Checking if a capability is enabled in code can be
434    /// done via `#[cfg(target_feature = "TheCapability")]`.
435    #[cfg_attr(feature = "clap", arg(long, value_parser=Self::parse_spirv_capability))]
436    pub capabilities: Vec<Capability>,
437    /// Adds an extension to the SPIR-V module. Checking if an extension is enabled in code can be
438    /// done via `#[cfg(target_feature = "ext:the_extension")]`.
439    #[cfg_attr(feature = "clap", arg(long))]
440    pub extensions: Vec<String>,
441    /// Set additional "codegen arg". Note: the `RUSTGPU_CODEGEN_ARGS` environment variable
442    /// takes precedence over any set arguments using this function.
443    #[cfg_attr(feature = "clap", clap(skip))]
444    pub extra_args: Vec<String>,
445    // Location of a known `rustc_codegen_spirv` dylib, only required without feature `rustc_codegen_spirv`.
446    #[cfg_attr(feature = "clap", clap(skip))]
447    pub rustc_codegen_spirv_location: Option<PathBuf>,
448    // Overwrite the toolchain like `cargo +nightly`
449    #[cfg_attr(feature = "clap", clap(skip))]
450    pub toolchain_overwrite: Option<String>,
451    // Set the rustc version of the toolchain, used to adjust params to support older toolchains
452    #[cfg_attr(feature = "clap", clap(skip))]
453    pub toolchain_rustc_version: Option<Version>,
454
455    /// The path of the "target specification" file.
456    ///
457    /// For more info on "target specification" see
458    /// [this RFC](https://rust-lang.github.io/rfcs/0131-target-specification.html).
459    #[cfg_attr(feature = "clap", clap(skip))]
460    pub path_to_target_spec: Option<PathBuf>,
461    /// Set the target dir path to use for building shaders. Relative paths will be resolved
462    /// relative to the `target` dir of the shader crate, absolute paths are used as is.
463    /// Defaults to `spirv-builder`, resulting in the path `./target/spirv-builder`.
464    #[cfg_attr(feature = "clap", clap(skip))]
465    pub target_dir_path: Option<PathBuf>,
466
467    // `rustc_codegen_spirv::linker` codegen args
468    /// Change the shader `panic!` handling strategy (see [`ShaderPanicStrategy`]).
469    #[cfg_attr(feature = "clap", clap(skip))]
470    pub shader_panic_strategy: ShaderPanicStrategy,
471
472    /// spirv-val flags
473    #[cfg_attr(feature = "clap", clap(flatten))]
474    #[serde(flatten)]
475    pub validator: ValidatorOptions,
476
477    /// spirv-opt flags
478    #[cfg_attr(feature = "clap", clap(flatten))]
479    #[serde(flatten)]
480    pub optimizer: OptimizerOptions,
481}
482
483#[cfg(feature = "clap")]
484impl SpirvBuilder {
485    /// Clap value parser for `Capability`.
486    fn parse_spirv_capability(capability: &str) -> Result<Capability, clap::Error> {
487        use core::str::FromStr;
488        Capability::from_str(capability).map_or_else(
489            |()| Err(clap::Error::new(clap::error::ErrorKind::InvalidValue)),
490            Ok,
491        )
492    }
493}
494
495impl Default for SpirvBuilder {
496    fn default() -> Self {
497        Self {
498            path_to_crate: None,
499            print_metadata: MetadataPrintout::default(),
500            release: true,
501            target: None,
502            deny_warnings: false,
503            multimodule: false,
504            spirv_metadata: SpirvMetadata::default(),
505            capabilities: Vec::new(),
506            extensions: Vec::new(),
507            extra_args: Vec::new(),
508            rustc_codegen_spirv_location: None,
509            path_to_target_spec: None,
510            target_dir_path: None,
511            toolchain_overwrite: None,
512            toolchain_rustc_version: None,
513            shader_panic_strategy: ShaderPanicStrategy::default(),
514            validator: ValidatorOptions::default(),
515            optimizer: OptimizerOptions::default(),
516            shader_crate_features: ShaderCrateFeatures::default(),
517        }
518    }
519}
520
521impl SpirvBuilder {
522    pub fn new(path_to_crate: impl AsRef<Path>, target: impl Into<String>) -> Self {
523        Self {
524            path_to_crate: Some(path_to_crate.as_ref().to_owned()),
525            target: Some(target.into()),
526            ..SpirvBuilder::default()
527        }
528    }
529
530    /// Sets the path of the "target specification" file.
531    ///
532    /// For more info on "target specification" see
533    /// [this RFC](https://rust-lang.github.io/rfcs/0131-target-specification.html).
534    #[must_use]
535    pub fn target_spec(mut self, p: impl AsRef<Path>) -> Self {
536        self.path_to_target_spec = Some(p.as_ref().to_path_buf());
537        self
538    }
539
540    /// Whether to print build.rs cargo metadata (e.g. cargo:rustc-env=var=val). Defaults to [`MetadataPrintout::Full`].
541    #[must_use]
542    pub fn print_metadata(mut self, v: MetadataPrintout) -> Self {
543        self.print_metadata = v;
544        self
545    }
546
547    #[must_use]
548    pub fn deny_warnings(mut self, v: bool) -> Self {
549        self.deny_warnings = v;
550        self
551    }
552
553    /// Build in release. Defaults to true.
554    #[must_use]
555    pub fn release(mut self, v: bool) -> Self {
556        self.release = v;
557        self
558    }
559
560    /// Splits the resulting SPIR-V file into one module per entry point. This is useful in cases
561    /// where ecosystem tooling has bugs around multiple entry points per module - having all entry
562    /// points bundled into a single file is the preferred system.
563    #[must_use]
564    pub fn multimodule(mut self, v: bool) -> Self {
565        self.multimodule = v;
566        self
567    }
568
569    /// Sets the level of metadata (primarily `OpName` and `OpLine`) included in the SPIR-V binary.
570    /// Including metadata significantly increases binary size.
571    #[must_use]
572    pub fn spirv_metadata(mut self, v: SpirvMetadata) -> Self {
573        self.spirv_metadata = v;
574        self
575    }
576
577    /// Adds a capability to the SPIR-V module. Checking if a capability is enabled in code can be
578    /// done via `#[cfg(target_feature = "TheCapability")]`.
579    #[must_use]
580    pub fn capability(mut self, capability: Capability) -> Self {
581        self.capabilities.push(capability);
582        self
583    }
584
585    /// Adds an extension to the SPIR-V module. Checking if an extension is enabled in code can be
586    /// done via `#[cfg(target_feature = "ext:the_extension")]`.
587    #[must_use]
588    pub fn extension(mut self, extension: impl Into<String>) -> Self {
589        self.extensions.push(extension.into());
590        self
591    }
592
593    /// Change the shader `panic!` handling strategy (see [`ShaderPanicStrategy`]).
594    #[must_use]
595    pub fn shader_panic_strategy(mut self, shader_panic_strategy: ShaderPanicStrategy) -> Self {
596        self.shader_panic_strategy = shader_panic_strategy;
597        self
598    }
599
600    /// Allow store from one struct type to a different type with compatible layout and members.
601    #[must_use]
602    pub fn relax_struct_store(mut self, v: bool) -> Self {
603        self.validator.relax_struct_store = v;
604        self
605    }
606
607    /// Allow allocating an object of a pointer type and returning a pointer value from a function
608    /// in logical addressing mode
609    #[must_use]
610    pub fn relax_logical_pointer(mut self, v: bool) -> Self {
611        self.validator.relax_logical_pointer = v;
612        self
613    }
614
615    /// Enable `VK_KHR_relaxed_block_layout` when checking standard uniform, storage buffer, and
616    /// push constant layouts. This is the default when targeting Vulkan 1.1 or later.
617    #[must_use]
618    pub fn relax_block_layout(mut self, v: bool) -> Self {
619        self.validator.relax_block_layout = Some(v);
620        self
621    }
622
623    /// Enable `VK_KHR_uniform_buffer_standard_layout` when checking standard uniform buffer
624    /// layouts.
625    #[must_use]
626    pub fn uniform_buffer_standard_layout(mut self, v: bool) -> Self {
627        self.validator.uniform_buffer_standard_layout = v;
628        self
629    }
630
631    /// Enable `VK_EXT_scalar_block_layout` when checking standard uniform, storage buffer, and
632    /// push constant layouts. Scalar layout rules are more permissive than relaxed block layout so
633    /// in effect this will override the --relax-block-layout option.
634    #[must_use]
635    pub fn scalar_block_layout(mut self, v: bool) -> Self {
636        self.validator.scalar_block_layout = v;
637        self
638    }
639
640    /// Skip checking standard uniform/storage buffer layout. Overrides any --relax-block-layout or
641    /// --scalar-block-layout option.
642    #[must_use]
643    pub fn skip_block_layout(mut self, v: bool) -> Self {
644        self.validator.skip_block_layout = v;
645        self
646    }
647
648    /// Preserve unused descriptor bindings. Useful for reflection.
649    #[must_use]
650    pub fn preserve_bindings(mut self, v: bool) -> Self {
651        self.optimizer.preserve_bindings = v;
652        self
653    }
654
655    /// Set additional "codegen arg". Note: the `RUSTGPU_CODEGEN_ARGS` environment variable
656    /// takes precedence over any set arguments using this function.
657    #[must_use]
658    pub fn extra_arg(mut self, arg: impl Into<String>) -> Self {
659        self.extra_args.push(arg.into());
660        self
661    }
662
663    /// Set --default-features for the target shader crate.
664    #[must_use]
665    pub fn shader_crate_default_features(mut self, default_features: bool) -> Self {
666        self.shader_crate_features.default_features = default_features;
667        self
668    }
669
670    /// Set --features for the target shader crate.
671    #[must_use]
672    pub fn shader_crate_features(mut self, features: impl IntoIterator<Item = String>) -> Self {
673        self.shader_crate_features.features = features.into_iter().collect();
674        self
675    }
676
677    #[must_use]
678    pub fn rustc_codegen_spirv_location(mut self, path_to_dylib: impl AsRef<Path>) -> Self {
679        self.rustc_codegen_spirv_location = Some(path_to_dylib.as_ref().to_path_buf());
680        self
681    }
682
683    /// Set the target dir path to use for building shaders. Relative paths will be resolved
684    /// relative to the `target` dir of the shader crate, absolute paths are used as is.
685    /// Defaults to `spirv-builder`, resulting in the path `./target/spirv-builder`.
686    #[must_use]
687    pub fn target_dir_path(mut self, name: impl Into<PathBuf>) -> Self {
688        self.target_dir_path = Some(name.into());
689        self
690    }
691
692    /// Builds the module. If `print_metadata` is [`MetadataPrintout::Full`], you usually don't have to inspect the path
693    /// in the result, as the environment variable for the path to the module will already be set.
694    pub fn build(&self) -> Result<CompileResult, SpirvBuilderError> {
695        let metadata_file = invoke_rustc(self)?;
696        match self.print_metadata {
697            MetadataPrintout::Full | MetadataPrintout::DependencyOnly => {
698                leaf_deps(&metadata_file, |artifact| {
699                    println!("cargo:rerun-if-changed={artifact}");
700                })
701                // Close enough
702                .map_err(SpirvBuilderError::MetadataFileMissing)?;
703            }
704            MetadataPrintout::None => (),
705        }
706        let metadata = self.parse_metadata_file(&metadata_file)?;
707
708        Ok(metadata)
709    }
710
711    pub(crate) fn parse_metadata_file(
712        &self,
713        at: &Path,
714    ) -> Result<CompileResult, SpirvBuilderError> {
715        let metadata_contents = File::open(at).map_err(SpirvBuilderError::MetadataFileMissing)?;
716        // FIXME(eddyb) move this functionality into `rustc_codegen_spirv_types`.
717        let metadata: CompileResult =
718            rustc_codegen_spirv_types::serde_json::from_reader(BufReader::new(metadata_contents))
719                .map_err(SpirvBuilderError::MetadataFileMalformed)?;
720        match &metadata.module {
721            ModuleResult::SingleModule(spirv_module) => {
722                assert!(!self.multimodule);
723                let env_var = format!(
724                    "{}.spv",
725                    at.file_name()
726                        .unwrap()
727                        .to_str()
728                        .unwrap()
729                        .strip_suffix(ARTIFACT_SUFFIX)
730                        .unwrap()
731                );
732                if self.print_metadata == MetadataPrintout::Full {
733                    println!("cargo:rustc-env={}={}", env_var, spirv_module.display());
734                }
735            }
736            ModuleResult::MultiModule(_) => {
737                assert!(self.multimodule);
738            }
739        }
740        Ok(metadata)
741    }
742}
743
744// https://github.com/rust-lang/cargo/blob/1857880b5124580c4aeb4e8bc5f1198f491d61b1/src/cargo/util/paths.rs#L29-L52
745fn dylib_path_envvar() -> &'static str {
746    if cfg!(windows) {
747        "PATH"
748    } else if cfg!(target_os = "macos") {
749        "DYLD_FALLBACK_LIBRARY_PATH"
750    } else {
751        "LD_LIBRARY_PATH"
752    }
753}
754fn dylib_path() -> Vec<PathBuf> {
755    match env::var_os(dylib_path_envvar()) {
756        Some(var) => env::split_paths(&var).collect(),
757        None => Vec::new(),
758    }
759}
760
761fn find_rustc_codegen_spirv() -> Result<PathBuf, SpirvBuilderError> {
762    if cfg!(feature = "rustc_codegen_spirv") {
763        let filename = format!(
764            "{}rustc_codegen_spirv{}",
765            env::consts::DLL_PREFIX,
766            env::consts::DLL_SUFFIX
767        );
768        for mut path in dylib_path() {
769            path.push(&filename);
770            if path.is_file() {
771                return Ok(path);
772            }
773        }
774        panic!("Could not find {filename} in library path");
775    } else {
776        Err(SpirvBuilderError::MissingRustcCodegenSpirvDylib)
777    }
778}
779
780/// Joins strings together while ensuring none of the strings contain the separator.
781// NOTE(eddyb) this intentionally consumes the `Vec` to limit accidental misuse.
782fn join_checking_for_separators(strings: Vec<impl Borrow<str>>, sep: &str) -> String {
783    for s in &strings {
784        let s = s.borrow();
785        assert!(!s.contains(sep), "{s:?} may not contain separator {sep:?}");
786    }
787    strings.join(sep)
788}
789
790// Returns path to the metadata json.
791fn invoke_rustc(builder: &SpirvBuilder) -> Result<PathBuf, SpirvBuilderError> {
792    let target = builder
793        .target
794        .as_ref()
795        .ok_or(SpirvBuilderError::MissingTarget)?;
796    let path_to_crate = builder
797        .path_to_crate
798        .as_ref()
799        .ok_or(SpirvBuilderError::MissingCratePath)?;
800    {
801        let target_env = target.strip_prefix(SPIRV_TARGET_PREFIX).ok_or_else(|| {
802            SpirvBuilderError::NonSpirvTarget {
803                target: target.clone(),
804            }
805        })?;
806        // HACK(eddyb) used only to split the full list into groups.
807        #[allow(clippy::match_same_arms)]
808        match target_env {
809            // HACK(eddyb) hardcoded list to avoid checking if the JSON file
810            // for a particular target exists (and sanitizing strings for paths).
811            //
812            // FIXME(eddyb) consider moving this list, or even `target-specs`,
813            // into `rustc_codegen_spirv_types`'s code/source.
814            "spv1.0" | "spv1.1" | "spv1.2" | "spv1.3" | "spv1.4" | "spv1.5" | "spv1.6" => {}
815            "opengl4.0" | "opengl4.1" | "opengl4.2" | "opengl4.3" | "opengl4.5" => {}
816            "vulkan1.0" | "vulkan1.1" | "vulkan1.1spv1.4" | "vulkan1.2" | "vulkan1.3"
817            | "vulkan1.4" => {}
818
819            _ => {
820                return Err(SpirvBuilderError::UnsupportedSpirvTargetEnv {
821                    target_env: target_env.into(),
822                });
823            }
824        }
825
826        if (builder.print_metadata == MetadataPrintout::Full) && builder.multimodule {
827            return Err(SpirvBuilderError::MultiModuleWithPrintMetadata);
828        }
829        if !path_to_crate.is_dir() {
830            return Err(SpirvBuilderError::CratePathDoesntExist(
831                path_to_crate.clone(),
832            ));
833        }
834    }
835
836    let toolchain_rustc_version =
837        if let Some(toolchain_rustc_version) = &builder.toolchain_rustc_version {
838            toolchain_rustc_version.clone()
839        } else {
840            query_rustc_version(builder.toolchain_overwrite.as_deref())?
841        };
842
843    // Okay, this is a little bonkers: in a normal world, we'd have the user clone
844    // rustc_codegen_spirv and pass in the path to it, and then we'd invoke cargo to build it, grab
845    // the resulting .so, and pass it into -Z codegen-backend. But that's really gross: the user
846    // needs to clone rustc_codegen_spirv and tell us its path! So instead, we *directly reference
847    // rustc_codegen_spirv in spirv-builder's Cargo.toml*, which means that it will get built
848    // alongside build.rs, and cargo will helpfully add it to LD_LIBRARY_PATH for us! However,
849    // rustc expects a full path, instead of a filename looked up via LD_LIBRARY_PATH, so we need
850    // to copy cargo's understanding of library lookup and find the library and its full path.
851    let rustc_codegen_spirv = Ok(builder.rustc_codegen_spirv_location.clone())
852        .transpose()
853        .unwrap_or_else(find_rustc_codegen_spirv)?;
854    if !rustc_codegen_spirv.is_file() {
855        return Err(SpirvBuilderError::RustcCodegenSpirvDylibDoesNotExist(
856            rustc_codegen_spirv,
857        ));
858    }
859
860    let mut rustflags = vec![
861        format!("-Zcodegen-backend={}", rustc_codegen_spirv.display()),
862        // Ensure the codegen backend is emitted in `.d` files to force Cargo
863        // to rebuild crates compiled with it when it changes (this used to be
864        // the default until https://github.com/rust-lang/rust/pull/93969).
865        "-Zbinary-dep-depinfo".to_string(),
866        "-Csymbol-mangling-version=v0".to_string(),
867        "-Zcrate-attr=feature(register_tool)".to_string(),
868        "-Zcrate-attr=register_tool(rust_gpu)".to_string(),
869        // HACK(eddyb) this is the same configuration that we test with, and
870        // ensures no unwanted surprises from e.g. `core` debug assertions.
871        "-Coverflow-checks=off".to_string(),
872        "-Cdebug-assertions=off".to_string(),
873        // HACK(eddyb) we need this for `core::fmt::rt::Argument::new_*` calls
874        // to *never* be inlined, so we can pattern-match the calls themselves.
875        "-Zinline-mir=off".to_string(),
876        // HACK(eddyb) similar to turning MIR inlining off, we also can't allow
877        // optimizations that drastically impact (the quality of) codegen, and
878        // GVN currently can lead to the memcpy-out-of-const-alloc-global-var
879        // pattern, even for `ScalarPair` (e.g. `return None::<u32>;`).
880        "-Zmir-enable-passes=-GVN".to_string(),
881        // HACK(eddyb) avoid ever reusing instantiations from `compiler_builtins`
882        // which is special-cased to turn calls to functions that never return,
883        // into aborts, and this applies to the panics of UB-checking helpers
884        // (https://github.com/rust-lang/rust/pull/122580#issuecomment-3033026194)
885        // but while upstream that only loses the panic message, for us it's even
886        // worse, as we lose the chance to remove otherwise-dead `fmt::Arguments`.
887        "-Zshare-generics=off".to_string(),
888    ];
889
890    // Wrapper for `env::var` that appropriately informs Cargo of the dependency.
891    let tracked_env_var_get = |name| {
892        if let MetadataPrintout::Full | MetadataPrintout::DependencyOnly = builder.print_metadata {
893            println!("cargo:rerun-if-env-changed={name}");
894        }
895        env::var(name)
896    };
897
898    let mut llvm_args = vec![];
899    if builder.multimodule {
900        llvm_args.push("--module-output=multiple".to_string());
901    }
902    match builder.spirv_metadata {
903        SpirvMetadata::None => (),
904        SpirvMetadata::NameVariables => {
905            llvm_args.push("--spirv-metadata=name-variables".to_string());
906        }
907        SpirvMetadata::Full => llvm_args.push("--spirv-metadata=full".to_string()),
908    }
909    if builder.validator.relax_struct_store {
910        llvm_args.push("--relax-struct-store".to_string());
911    }
912    if builder.validator.relax_logical_pointer {
913        llvm_args.push("--relax-logical-pointer".to_string());
914    }
915    if builder.validator.relax_block_layout.unwrap_or(false) {
916        llvm_args.push("--relax-block-layout".to_string());
917    }
918    if builder.validator.uniform_buffer_standard_layout {
919        llvm_args.push("--uniform-buffer-standard-layout".to_string());
920    }
921    if builder.validator.scalar_block_layout {
922        llvm_args.push("--scalar-block-layout".to_string());
923    }
924    if builder.validator.skip_block_layout {
925        llvm_args.push("--skip-block-layout".to_string());
926    }
927    if builder.optimizer.preserve_bindings {
928        llvm_args.push("--preserve-bindings".to_string());
929    }
930    let mut target_features = vec![];
931    let abort_strategy = match builder.shader_panic_strategy {
932        ShaderPanicStrategy::SilentExit => None,
933        ShaderPanicStrategy::DebugPrintfThenExit {
934            print_inputs,
935            print_backtrace,
936        } => {
937            target_features.push("+ext:SPV_KHR_non_semantic_info".into());
938            Some(format!(
939                "debug-printf{}{}",
940                if print_inputs { "+inputs" } else { "" },
941                if print_backtrace { "+backtrace" } else { "" }
942            ))
943        }
944        ShaderPanicStrategy::UNSOUND_DO_NOT_USE_UndefinedBehaviorViaUnreachable => {
945            Some("unreachable".into())
946        }
947    };
948    llvm_args.extend(abort_strategy.map(|strategy| format!("--abort-strategy={strategy}")));
949
950    if let Ok(extra_codegen_args) = tracked_env_var_get("RUSTGPU_CODEGEN_ARGS") {
951        llvm_args.extend(extra_codegen_args.split_whitespace().map(|s| s.to_string()));
952    } else {
953        llvm_args.extend(builder.extra_args.iter().cloned());
954    }
955
956    let llvm_args = join_checking_for_separators(llvm_args, " ");
957    if !llvm_args.is_empty() {
958        rustflags.push(["-Cllvm-args=", &llvm_args].concat());
959    }
960
961    target_features.extend(builder.capabilities.iter().map(|cap| format!("+{cap:?}")));
962    target_features.extend(builder.extensions.iter().map(|ext| format!("+ext:{ext}")));
963    let target_features = join_checking_for_separators(target_features, ",");
964    if !target_features.is_empty() {
965        rustflags.push(["-Ctarget-feature=", &target_features].concat());
966    }
967
968    if builder.deny_warnings {
969        rustflags.push("-Dwarnings".to_string());
970    }
971
972    if let Ok(extra_rustflags) = tracked_env_var_get("RUSTGPU_RUSTFLAGS") {
973        rustflags.extend(extra_rustflags.split_whitespace().map(|s| s.to_string()));
974    }
975
976    let target_dir_path = builder
977        .target_dir_path
978        .clone()
979        .unwrap_or_else(|| PathBuf::from("spirv-builder"));
980    let target_dir = if target_dir_path.is_absolute() {
981        target_dir_path
982    } else {
983        let metadata = cargo_metadata::MetadataCommand::new()
984            .current_dir(path_to_crate)
985            .exec()?;
986        metadata
987            .target_directory
988            .into_std_path_buf()
989            .join(target_dir_path)
990    };
991
992    let profile = if builder.release { "release" } else { "dev" };
993
994    let mut cargo = cargo_cmd::CargoCmd::new();
995    if let Some(toolchain) = &builder.toolchain_overwrite {
996        cargo.arg(format!("+{toolchain}"));
997    }
998    cargo.args([
999        "build",
1000        "--lib",
1001        "--message-format=json-render-diagnostics",
1002        "-Zbuild-std=core",
1003        "-Zbuild-std-features=compiler-builtins-mem",
1004        "--profile",
1005        profile,
1006    ]);
1007
1008    if let Ok(extra_cargoflags) = tracked_env_var_get("RUSTGPU_CARGOFLAGS") {
1009        cargo.args(extra_cargoflags.split_whitespace());
1010    }
1011
1012    // FIXME(eddyb) consider moving `target-specs` into `rustc_codegen_spirv_types`.
1013    // FIXME(eddyb) consider the `RUST_TARGET_PATH` env var alternative.
1014
1015    // NOTE(firestar99) rustc 1.76 has been tested to correctly parse modern
1016    // target_spec jsons, some later version requires them, some earlier
1017    // version fails with them (notably our 0.9.0 release)
1018    if toolchain_rustc_version >= Version::new(1, 76, 0) {
1019        let path_opt = builder.path_to_target_spec.clone();
1020        let path;
1021        #[cfg(feature = "include-target-specs")]
1022        {
1023            path = path_opt
1024                .unwrap_or_else(|| PathBuf::from(format!("{TARGET_SPEC_DIR_PATH}/{target}.json")));
1025        }
1026        #[cfg(not(feature = "include-target-specs"))]
1027        {
1028            path = path_opt.ok_or(SpirvBuilderError::MissingTargetSpec)?;
1029        }
1030        cargo.arg("--target").arg(path);
1031    } else {
1032        cargo.arg("--target").arg(target);
1033    }
1034
1035    if !builder.shader_crate_features.default_features {
1036        cargo.arg("--no-default-features");
1037    }
1038
1039    if !builder.shader_crate_features.features.is_empty() {
1040        cargo
1041            .arg("--features")
1042            .arg(builder.shader_crate_features.features.join(","));
1043    }
1044
1045    cargo.arg("--target-dir").arg(target_dir);
1046
1047    // NOTE(eddyb) this used to be just `RUSTFLAGS` but at some point Cargo
1048    // added a separate environment variable using `\x1f` instead of spaces,
1049    // which allows us to have spaces within individual `rustc` flags.
1050    cargo.env(
1051        "CARGO_ENCODED_RUSTFLAGS",
1052        join_checking_for_separators(rustflags, "\x1f"),
1053    );
1054
1055    // NOTE(eddyb) there's no parallelism to take advantage of multiple CGUs,
1056    // and inter-CGU duplication can be wasteful, so this forces 1 CGU for now.
1057    let profile_in_env_var = profile.replace('-', "_").to_ascii_uppercase();
1058    let num_cgus = 1;
1059    cargo.env(
1060        format!("CARGO_PROFILE_{profile_in_env_var}_CODEGEN_UNITS"),
1061        num_cgus.to_string(),
1062    );
1063
1064    cargo.stderr(Stdio::inherit()).current_dir(path_to_crate);
1065    log::debug!("building shaders with `{cargo:?}`");
1066    let build = cargo.output().expect("failed to execute cargo build");
1067
1068    // `get_last_artifact` has the side-effect of printing invalid lines, so
1069    // we do that even in case of an error, to let through any useful messages
1070    // that ended up on stdout instead of stderr.
1071    let stdout = String::from_utf8(build.stdout).unwrap();
1072    if build.status.success() {
1073        get_sole_artifact(&stdout).ok_or_else(|| {
1074            eprintln!("--- build output ---\n{stdout}");
1075            panic!(
1076                "`{ARTIFACT_SUFFIX}` artifact not found in (supposedly successful) build output (see above). Verify that `crate-type` is set correctly"
1077            );
1078        })
1079    } else {
1080        Err(SpirvBuilderError::BuildFailed)
1081    }
1082}
1083
1084#[derive(Deserialize)]
1085struct RustcOutput {
1086    reason: String,
1087    filenames: Option<Vec<String>>,
1088}
1089
1090const ARTIFACT_SUFFIX: &str = ".spv.json";
1091
1092fn get_sole_artifact(out: &str) -> Option<PathBuf> {
1093    let mut last_compiler_artifact = None;
1094    for line in out.lines() {
1095        let Ok(msg) = serde_json::from_str::<RustcOutput>(line) else {
1096            // Pass through invalid lines
1097            println!("{line}");
1098            continue;
1099        };
1100        if msg.reason == "compiler-artifact" {
1101            last_compiler_artifact = Some(msg);
1102        }
1103    }
1104    let last_compiler_artifact =
1105        last_compiler_artifact.expect("Did not find output file in rustc output");
1106
1107    let mut filenames = last_compiler_artifact
1108        .filenames
1109        .unwrap()
1110        .into_iter()
1111        .filter(|v| v.ends_with(ARTIFACT_SUFFIX));
1112    let filename = filenames.next()?;
1113    assert_eq!(
1114        filenames.next(),
1115        None,
1116        "build had multiple `{ARTIFACT_SUFFIX}` artifacts"
1117    );
1118    Some(filename.into())
1119}
1120
1121/// Internally iterate through the leaf dependencies of the artifact at `artifact`
1122fn leaf_deps(artifact: &Path, mut handle: impl FnMut(&RawStr)) -> std::io::Result<()> {
1123    let deps_file = artifact.with_extension("d");
1124    let mut deps_map = HashMap::new();
1125    depfile::read_deps_file(&deps_file, |item, deps| {
1126        deps_map.insert(item, deps);
1127        Ok(())
1128    })?;
1129    fn recurse(
1130        map: &HashMap<RawString, Vec<RawString>>,
1131        artifact: &RawStr,
1132        handle: &mut impl FnMut(&RawStr),
1133    ) {
1134        match map.get(artifact) {
1135            Some(entries) => {
1136                for entry in entries {
1137                    recurse(map, entry, handle);
1138                }
1139            }
1140            None => handle(artifact),
1141        }
1142    }
1143    recurse(&deps_map, artifact.to_str().unwrap().into(), &mut handle);
1144    Ok(())
1145}
1146
1147pub fn query_rustc_version(toolchain: Option<&str>) -> std::io::Result<Version> {
1148    let mut cmd = Command::new("rustc");
1149    if let Some(toolchain) = toolchain {
1150        cmd.arg(format!("+{toolchain}"));
1151    }
1152    cmd.arg("--version");
1153    let output = cmd.output()?;
1154
1155    let stdout = String::from_utf8(output.stdout).expect("stdout must be utf-8");
1156    let parse = |output: &str| {
1157        let output = output.strip_prefix("rustc ")?;
1158        let version = &output[..output.find(|c| !"0123456789.".contains(c))?];
1159        Version::parse(version).ok()
1160    };
1161    Ok(parse(&stdout)
1162        .unwrap_or_else(|| panic!("failed parsing `rustc --version` output `{stdout}`")))
1163}