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