1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
// BEGIN - Embark standard lints v0.4
// do not change or add/remove here, but one can add exceptions after this section
// for more info see: <https://github.com/EmbarkStudios/rust-ecosystem/issues/59>
#![deny(unsafe_code)]
#![warn(
    clippy::all,
    clippy::await_holding_lock,
    clippy::char_lit_as_u8,
    clippy::checked_conversions,
    clippy::dbg_macro,
    clippy::debug_assert_with_mut_call,
    clippy::doc_markdown,
    clippy::empty_enum,
    clippy::enum_glob_use,
    clippy::exit,
    clippy::expl_impl_clone_on_copy,
    clippy::explicit_deref_methods,
    clippy::explicit_into_iter_loop,
    clippy::fallible_impl_from,
    clippy::filter_map_next,
    clippy::float_cmp_const,
    clippy::fn_params_excessive_bools,
    clippy::if_let_mutex,
    clippy::implicit_clone,
    clippy::imprecise_flops,
    clippy::inefficient_to_string,
    clippy::invalid_upcast_comparisons,
    clippy::large_types_passed_by_value,
    clippy::let_unit_value,
    clippy::linkedlist,
    clippy::lossy_float_literal,
    clippy::macro_use_imports,
    clippy::manual_ok_or,
    clippy::map_err_ignore,
    clippy::map_flatten,
    clippy::map_unwrap_or,
    clippy::match_on_vec_items,
    clippy::match_same_arms,
    clippy::match_wildcard_for_single_variants,
    clippy::mem_forget,
    clippy::mismatched_target_os,
    clippy::mut_mut,
    clippy::mutex_integer,
    clippy::needless_borrow,
    clippy::needless_continue,
    clippy::option_option,
    clippy::path_buf_push_overwrite,
    clippy::ptr_as_ptr,
    clippy::ref_option_ref,
    clippy::rest_pat_in_fully_bound_structs,
    clippy::same_functions_in_if_condition,
    clippy::semicolon_if_nothing_returned,
    clippy::string_add_assign,
    clippy::string_add,
    clippy::string_lit_as_bytes,
    clippy::string_to_string,
    clippy::todo,
    clippy::trait_duplication_in_bounds,
    clippy::unimplemented,
    clippy::unnested_or_patterns,
    clippy::unused_self,
    clippy::useless_transmute,
    clippy::verbose_file_reads,
    clippy::zero_sized_map_values,
    future_incompatible,
    nonstandard_style,
    rust_2018_idioms
)]
// END - Embark standard lints v0.4
// crate-specific exceptions:
// #![allow()]
#![doc = include_str!("../README.md")]

// HACK(eddyb) try to catch misuse of Cargo package features very early on
// (see `spirv-builder/Cargo.toml` for why we go through all of this).
#[cfg(all(
    not(any(feature = "use-compiled-tools", feature = "use-installed-tools")),
    not(doc)
))]
compile_error!(
    "at least one of `use-compiled-tools` or `use-installed-tools` features must be enabled
(outside of documentation builds, which require disabling both to build on stable)"
);

#[cfg(doc)]
fn _ensure_cfg_doc_means_rustdoc() {
    // HACK(eddyb) this relies on specific `rustdoc` behavior (i.e. it skips
    // type-checking function bodies, so we trigger a compile-time `panic! from
    // a type) to check that we're in fact under `rustdoc`, not just `--cfg doc`.
    #[rustfmt::skip]
    let _: [(); panic!("

            `--cfg doc` was set outside of `rustdoc`
            (if you are running `rustdoc` or `cargo doc`, please file an issue)

")];
}

mod depfile;
#[cfg(feature = "watch")]
mod watch;

use raw_string::{RawStr, RawString};
use serde::Deserialize;
use std::borrow::Borrow;
use std::collections::HashMap;
use std::env;
use std::error::Error;
use std::fmt;
use std::fs::File;
use std::io::BufReader;
use std::path::{Path, PathBuf};
use std::process::{Command, Stdio};

pub use rustc_codegen_spirv_types::Capability;
pub use rustc_codegen_spirv_types::{CompileResult, ModuleResult};

#[derive(Debug)]
#[non_exhaustive]
pub enum SpirvBuilderError {
    NonSpirvTarget { target: String },
    UnsupportedSpirvTargetEnv { target_env: String },
    CratePathDoesntExist(PathBuf),
    BuildFailed,
    MultiModuleWithPrintMetadata,
    WatchWithPrintMetadata,
    MetadataFileMissing(std::io::Error),
    MetadataFileMalformed(serde_json::Error),
}

const SPIRV_TARGET_PREFIX: &str = "spirv-unknown-";

impl fmt::Display for SpirvBuilderError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::NonSpirvTarget { target } => {
                write!(
                    f,
                    "expected `{SPIRV_TARGET_PREFIX}...` target, found `{target}`"
                )
            }
            Self::UnsupportedSpirvTargetEnv { target_env } if target_env.starts_with("opencl") => {
                write!(
                    f,
                    "OpenCL targets like `{SPIRV_TARGET_PREFIX}-{target_env}` are not supported"
                )
            }
            Self::UnsupportedSpirvTargetEnv { target_env } if target_env.starts_with("webgpu") => {
                write!(
                    f,
                    "WebGPU targets like `{SPIRV_TARGET_PREFIX}-{target_env}` are not supported, \
                     consider using `{SPIRV_TARGET_PREFIX}-vulkan1.0` instead"
                )
            }
            Self::UnsupportedSpirvTargetEnv { target_env } => {
                write!(
                    f,
                    "SPIR-V target `{SPIRV_TARGET_PREFIX}-{target_env}` is not supported"
                )
            }
            Self::CratePathDoesntExist(path) => {
                write!(f, "crate path {} does not exist", path.display())
            }
            Self::BuildFailed => f.write_str("build failed"),
            Self::MultiModuleWithPrintMetadata => f.write_str(
                "multi-module build cannot be used with print_metadata = MetadataPrintout::Full",
            ),
            Self::WatchWithPrintMetadata => {
                f.write_str("watching within build scripts will prevent build completion")
            }
            Self::MetadataFileMissing(_) => f.write_str("multi-module metadata file missing"),
            Self::MetadataFileMalformed(_) => {
                f.write_str("unable to parse multi-module metadata file")
            }
        }
    }
}

impl Error for SpirvBuilderError {}

#[derive(Debug, PartialEq, Eq, Clone, Copy)]
pub enum MetadataPrintout {
    /// Print no cargo metadata.
    None,
    /// Print only dependency information (eg for multiple modules).
    DependencyOnly,
    /// Print all cargo metadata.
    ///
    /// Includes dependency information and spirv environment variable.
    Full,
}

#[derive(Debug, PartialEq, Eq, Clone, Copy)]
pub enum SpirvMetadata {
    /// Strip all names and other debug information from SPIR-V output.
    None,
    /// Only include `OpName`s for public interface variables (uniforms and the like), to allow
    /// shader reflection.
    NameVariables,
    /// Include all `OpName`s for everything, and `OpLine`s. Significantly increases binary size.
    Full,
}

/// Strategy used to handle Rust `panic!`s in shaders compiled to SPIR-V.
#[derive(Debug, PartialEq, Eq, Clone, Copy)]
pub enum ShaderPanicStrategy {
    /// Return from shader entry-point with no side-effects **(default)**.
    ///
    /// While similar to the standard SPIR-V `OpTerminateInvocation`, this is
    /// *not* limited to fragment shaders, and instead supports all shaders
    /// (as it's handled via control-flow rewriting, instead of SPIR-V features).
    SilentExit,

    /// Like `SilentExit`, but also using `debugPrintf` to report the panic in
    /// a way that can reach the user, before returning from the entry-point.
    ///
    /// Will automatically require the `SPV_KHR_non_semantic_info` extension,
    /// as `debugPrintf` uses a "non-semantic extended instruction set".
    ///
    /// If you have multiple entry-points, you *may* need to also enable the
    /// `multimodule` node (see <https://github.com/KhronosGroup/SPIRV-Tools/issues/4892>).
    ///
    /// **Note**: actually obtaining the `debugPrintf` output requires:
    /// * Vulkan Validation Layers (from e.g. the Vulkan SDK)
    ///   * (they contain the `debugPrintf` implementation, a SPIR-V -> SPIR-V translation)
    ///   * **set the `VK_LOADER_LAYERS_ENABLE=VK_LAYER_KHRONOS_validation`
    ///     environment variable** to easily enable them without any code changes
    ///   * alternatively, `"VK_LAYER_KHRONOS_validation"` can be passed during
    ///     instance creation, to enable them programmatically
    /// * Validation Layers' `debugPrintf` support:
    ///   * **set the `VK_LAYER_ENABLES=VK_VALIDATION_FEATURE_ENABLE_DEBUG_PRINTF_EXT`
    ///     environment variable** to easily enable the `debugPrintf` support
    ///   * alternatively, `VkValidationFeaturesEXT` during instance creation,
    ///     or the `khronos_validation.enables` field in `vk_layer_settings.txt`,
    ///     can be used to enable `VK_VALIDATION_FEATURE_ENABLE_DEBUG_PRINTF_EXT`
    ///     (see also <https://github.com/KhronosGroup/Vulkan-ValidationLayers/blob/main/docs/debug_printf.md>)
    /// * for outputting the `debugPrintf` messages sent back from the GPU:
    ///   * **set the `DEBUG_PRINTF_TO_STDOUT=1` environment variable** if you don't
    ///     plan on customizing the reporting (see below for alternatives)
    /// * for `wgpu`:
    ///   * **required**: `wgpu::Features::SPIRV_SHADER_PASSTHROUGH` (Naga lacks `debugPrintf`)
    ///   * *optional*: building in debug mode (and/or with debug-assertions enabled),
    ///     to enable `wgpu` logging/debug support
    ///     * (the debug assertions requirement may be lifted in future `wgpu` versions)
    ///     * this uses `VK_EXT_debug_utils` internally, and is a better-integrated
    ///       alternative to just setting `DEBUG_PRINTF_TO_STDOUT=1`
    ///     * `RUST_LOG=wgpu_hal::vulkan=info` (or equivalent) will enable said
    ///       output (as `debugPrintf` messages have the "info" level)
    ///     * `RUST_LOG` controls `env_logger`, which isn't itself required,
    ///       but *some* `log`/`tracing` subscriber is needed to get any output
    /// * for Vulkan (e.g. via `ash`):
    ///   * **required**: enabling the `VK_KHR_shader_non_semantic_info` Vulkan *Device* extension
    ///   * *optional*: as described above, enabling the Validation Layers and
    ///     their `debugPrintf` support can be done during instance creation
    ///   * *optional*: integrating [`VK_EXT_debug_utils`](https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VK_EXT_debug_utils.html)
    ///     allows more reporting flexibility than `DEBUG_PRINTF_TO_STDOUT=1`)
    DebugPrintfThenExit {
        /// Whether to also print the entry-point inputs (excluding buffers/resources),
        /// which should uniquely identify the panicking shader invocation.
        print_inputs: bool,

        /// Whether to also print a "backtrace" (i.e. the chain of function calls
        /// that led to the `panic!`).
        ///
        /// As there is no way to dynamically compute this information, the string
        /// containing the full backtrace of each `panic!` is statically generated,
        /// meaning this option could significantly increase binary size.
        print_backtrace: bool,
    },

    /// **Warning**: this is _**unsound**_ (i.e. adds Undefined Behavior to *safe* Rust code)
    ///
    /// This option only exists for testing (hence the unfriendly name it has),
    /// and more specifically testing whether conditional panics are responsible
    /// for performance differences when upgrading from older Rust-GPU versions
    /// (which used infinite loops for panics, that `spirv-opt`/drivers could've
    /// sometimes treated as UB, and optimized as if they were impossible to reach).
    ///
    /// Unlike those infinite loops, however, this uses `OpUnreachable`, so it
    /// forces the old worst-case (all `panic!`s become UB and are optimized out).
    #[allow(non_camel_case_types)]
    UNSOUND_DO_NOT_USE_UndefinedBehaviorViaUnreachable,
}

/// Cargo features specification for building the shader crate.
#[derive(Default)]
struct ShaderCrateFeatures {
    default_features: Option<bool>,
    features: Vec<String>,
}

pub struct SpirvBuilder {
    path_to_crate: PathBuf,
    print_metadata: MetadataPrintout,
    release: bool,
    target: String,
    shader_crate_features: ShaderCrateFeatures,
    deny_warnings: bool,
    multimodule: bool,
    spirv_metadata: SpirvMetadata,
    capabilities: Vec<Capability>,
    extensions: Vec<String>,
    extra_args: Vec<String>,
    // Optional location of a known `rustc_codegen_spirv` dylib
    rustc_codegen_spirv_location: Option<std::path::PathBuf>,
    // Optional location of a known "target-spec" file
    path_to_target_spec: Option<PathBuf>,

    // `rustc_codegen_spirv::linker` codegen args
    pub shader_panic_strategy: ShaderPanicStrategy,

    // spirv-val flags
    pub relax_struct_store: bool,
    pub relax_logical_pointer: bool,
    pub relax_block_layout: bool,
    pub uniform_buffer_standard_layout: bool,
    pub scalar_block_layout: bool,
    pub skip_block_layout: bool,

    // spirv-opt flags
    pub preserve_bindings: bool,
}

impl SpirvBuilder {
    pub fn new(path_to_crate: impl AsRef<Path>, target: impl Into<String>) -> Self {
        Self {
            path_to_crate: path_to_crate.as_ref().to_owned(),
            print_metadata: MetadataPrintout::Full,
            release: true,
            target: target.into(),
            deny_warnings: false,
            multimodule: false,
            spirv_metadata: SpirvMetadata::None,
            capabilities: Vec::new(),
            extensions: Vec::new(),
            extra_args: Vec::new(),
            rustc_codegen_spirv_location: None,
            path_to_target_spec: None,

            shader_panic_strategy: ShaderPanicStrategy::SilentExit,

            relax_struct_store: false,
            relax_logical_pointer: false,
            relax_block_layout: false,
            uniform_buffer_standard_layout: false,
            scalar_block_layout: false,
            skip_block_layout: false,

            preserve_bindings: false,
            shader_crate_features: ShaderCrateFeatures::default(),
        }
    }

    /// Sets the path of the "target specification" file.
    ///
    /// For more info on "target specification" see
    /// [this RFC](https://rust-lang.github.io/rfcs/0131-target-specification.html).
    #[must_use]
    pub fn target_spec(mut self, p: impl AsRef<Path>) -> Self {
        self.path_to_target_spec = Some(p.as_ref().to_path_buf());
        self
    }

    /// Whether to print build.rs cargo metadata (e.g. cargo:rustc-env=var=val). Defaults to [`MetadataPrintout::Full`].
    #[must_use]
    pub fn print_metadata(mut self, v: MetadataPrintout) -> Self {
        self.print_metadata = v;
        self
    }

    #[must_use]
    pub fn deny_warnings(mut self, v: bool) -> Self {
        self.deny_warnings = v;
        self
    }

    /// Build in release. Defaults to true.
    #[must_use]
    pub fn release(mut self, v: bool) -> Self {
        self.release = v;
        self
    }

    /// Splits the resulting SPIR-V file into one module per entry point. This is useful in cases
    /// where ecosystem tooling has bugs around multiple entry points per module - having all entry
    /// points bundled into a single file is the preferred system.
    #[must_use]
    pub fn multimodule(mut self, v: bool) -> Self {
        self.multimodule = v;
        self
    }

    /// Sets the level of metadata (primarily `OpName` and `OpLine`) included in the SPIR-V binary.
    /// Including metadata significantly increases binary size.
    #[must_use]
    pub fn spirv_metadata(mut self, v: SpirvMetadata) -> Self {
        self.spirv_metadata = v;
        self
    }

    /// Adds a capability to the SPIR-V module. Checking if a capability is enabled in code can be
    /// done via `#[cfg(target_feature = "TheCapability")]`.
    #[must_use]
    pub fn capability(mut self, capability: Capability) -> Self {
        self.capabilities.push(capability);
        self
    }

    /// Adds an extension to the SPIR-V module. Checking if an extension is enabled in code can be
    /// done via `#[cfg(target_feature = "ext:the_extension")]`.
    #[must_use]
    pub fn extension(mut self, extension: impl Into<String>) -> Self {
        self.extensions.push(extension.into());
        self
    }

    /// Change the shader `panic!` handling strategy (see [`ShaderPanicStrategy`]).
    #[must_use]
    pub fn shader_panic_strategy(mut self, shader_panic_strategy: ShaderPanicStrategy) -> Self {
        self.shader_panic_strategy = shader_panic_strategy;
        self
    }

    /// Allow store from one struct type to a different type with compatible layout and members.
    #[must_use]
    pub fn relax_struct_store(mut self, v: bool) -> Self {
        self.relax_struct_store = v;
        self
    }

    /// Allow allocating an object of a pointer type and returning a pointer value from a function
    /// in logical addressing mode
    #[must_use]
    pub fn relax_logical_pointer(mut self, v: bool) -> Self {
        self.relax_logical_pointer = v;
        self
    }

    /// Enable `VK_KHR_relaxed_block_layout` when checking standard uniform, storage buffer, and
    /// push constant layouts. This is the default when targeting Vulkan 1.1 or later.
    #[must_use]
    pub fn relax_block_layout(mut self, v: bool) -> Self {
        self.relax_block_layout = v;
        self
    }

    /// Enable `VK_KHR_uniform_buffer_standard_layout` when checking standard uniform buffer
    /// layouts.
    #[must_use]
    pub fn uniform_buffer_standard_layout(mut self, v: bool) -> Self {
        self.uniform_buffer_standard_layout = v;
        self
    }

    /// Enable `VK_EXT_scalar_block_layout` when checking standard uniform, storage buffer, and
    /// push constant layouts. Scalar layout rules are more permissive than relaxed block layout so
    /// in effect this will override the --relax-block-layout option.
    #[must_use]
    pub fn scalar_block_layout(mut self, v: bool) -> Self {
        self.scalar_block_layout = v;
        self
    }

    /// Skip checking standard uniform/storage buffer layout. Overrides any --relax-block-layout or
    /// --scalar-block-layout option.
    #[must_use]
    pub fn skip_block_layout(mut self, v: bool) -> Self {
        self.skip_block_layout = v;
        self
    }

    /// Preserve unused descriptor bindings. Useful for reflection.
    #[must_use]
    pub fn preserve_bindings(mut self, v: bool) -> Self {
        self.preserve_bindings = v;
        self
    }

    /// Set additional "codegen arg". Note: the `RUSTGPU_CODEGEN_ARGS` environment variable
    /// takes precedence over any set arguments using this function.
    #[must_use]
    pub fn extra_arg(mut self, arg: impl Into<String>) -> Self {
        self.extra_args.push(arg.into());
        self
    }

    /// Set --default-features for the target shader crate.
    #[must_use]
    pub fn shader_crate_default_features(mut self, default_features: bool) -> Self {
        self.shader_crate_features.default_features = Some(default_features);
        self
    }

    /// Set --features for the target shader crate.
    #[must_use]
    pub fn shader_crate_features(mut self, features: impl IntoIterator<Item = String>) -> Self {
        self.shader_crate_features.features = features.into_iter().collect();
        self
    }

    #[must_use]
    pub fn rustc_codegen_spirv_location(
        mut self,
        path_to_dylib: impl AsRef<std::path::Path>,
    ) -> Self {
        let path_to_dylib = path_to_dylib.as_ref().to_path_buf();
        assert!(
            path_to_dylib.is_file(),
            "Provided path to dylib '{}' is not a file",
            path_to_dylib.display()
        );
        self.rustc_codegen_spirv_location = Some(path_to_dylib);
        self
    }

    /// Builds the module. If `print_metadata` is [`MetadataPrintout::Full`], you usually don't have to inspect the path
    /// in the result, as the environment variable for the path to the module will already be set.
    pub fn build(mut self) -> Result<CompileResult, SpirvBuilderError> {
        self.validate_running_conditions()?;
        let metadata_file = invoke_rustc(&self)?;
        match self.print_metadata {
            MetadataPrintout::Full | MetadataPrintout::DependencyOnly => {
                leaf_deps(&metadata_file, |artifact| {
                    println!("cargo:rerun-if-changed={artifact}");
                })
                // Close enough
                .map_err(SpirvBuilderError::MetadataFileMissing)?;
            }
            MetadataPrintout::None => (),
        }
        let metadata = self.parse_metadata_file(&metadata_file)?;

        Ok(metadata)
    }

    pub(crate) fn validate_running_conditions(&mut self) -> Result<(), SpirvBuilderError> {
        let target_env = self
            .target
            .strip_prefix(SPIRV_TARGET_PREFIX)
            .ok_or_else(|| SpirvBuilderError::NonSpirvTarget {
                target: self.target.clone(),
            })?;
        // HACK(eddyb) used only to split the full list into groups.
        #[allow(clippy::match_same_arms)]
        match target_env {
            // HACK(eddyb) hardcoded list to avoid checking if the JSON file
            // for a particular target exists (and sanitizing strings for paths).
            //
            // FIXME(eddyb) consider moving this list, or even `target-specs`,
            // into `rustc_codegen_spirv_types`'s code/source.
            "spv1.0" | "spv1.1" | "spv1.2" | "spv1.3" | "spv1.4" | "spv1.5" => {}
            "opengl4.0" | "opengl4.1" | "opengl4.2" | "opengl4.3" | "opengl4.5" => {}
            "vulkan1.0" | "vulkan1.1" | "vulkan1.1spv1.4" | "vulkan1.2" => {}

            _ => {
                return Err(SpirvBuilderError::UnsupportedSpirvTargetEnv {
                    target_env: target_env.into(),
                });
            }
        }

        if (self.print_metadata == MetadataPrintout::Full) && self.multimodule {
            return Err(SpirvBuilderError::MultiModuleWithPrintMetadata);
        }
        if !self.path_to_crate.is_dir() {
            return Err(SpirvBuilderError::CratePathDoesntExist(std::mem::take(
                &mut self.path_to_crate,
            )));
        }
        Ok(())
    }

    pub(crate) fn parse_metadata_file(
        &self,
        at: &Path,
    ) -> Result<CompileResult, SpirvBuilderError> {
        let metadata_contents = File::open(at).map_err(SpirvBuilderError::MetadataFileMissing)?;
        // FIXME(eddyb) move this functionality into `rustc_codegen_spirv_types`.
        let metadata: CompileResult =
            rustc_codegen_spirv_types::serde_json::from_reader(BufReader::new(metadata_contents))
                .map_err(SpirvBuilderError::MetadataFileMalformed)?;
        match &metadata.module {
            ModuleResult::SingleModule(spirv_module) => {
                assert!(!self.multimodule);
                let env_var = format!(
                    "{}.spv",
                    at.file_name()
                        .unwrap()
                        .to_str()
                        .unwrap()
                        .strip_suffix(".spv.json")
                        .unwrap()
                );
                if self.print_metadata == MetadataPrintout::Full {
                    println!("cargo:rustc-env={}={}", env_var, spirv_module.display());
                }
            }
            ModuleResult::MultiModule(_) => {
                assert!(self.multimodule);
            }
        }
        Ok(metadata)
    }
}

// https://github.com/rust-lang/cargo/blob/1857880b5124580c4aeb4e8bc5f1198f491d61b1/src/cargo/util/paths.rs#L29-L52
fn dylib_path_envvar() -> &'static str {
    if cfg!(windows) {
        "PATH"
    } else if cfg!(target_os = "macos") {
        "DYLD_FALLBACK_LIBRARY_PATH"
    } else {
        "LD_LIBRARY_PATH"
    }
}
fn dylib_path() -> Vec<PathBuf> {
    match env::var_os(dylib_path_envvar()) {
        Some(var) => env::split_paths(&var).collect(),
        None => Vec::new(),
    }
}

fn find_rustc_codegen_spirv() -> PathBuf {
    let filename = format!(
        "{}rustc_codegen_spirv{}",
        env::consts::DLL_PREFIX,
        env::consts::DLL_SUFFIX
    );
    for mut path in dylib_path() {
        path.push(&filename);
        if path.is_file() {
            return path;
        }
    }
    panic!("Could not find {filename} in library path");
}

/// Joins strings together while ensuring none of the strings contain the separator.
// NOTE(eddyb) this intentionally consumes the `Vec` to limit accidental misuse.
fn join_checking_for_separators(strings: Vec<impl Borrow<str>>, sep: &str) -> String {
    for s in &strings {
        let s = s.borrow();
        assert!(!s.contains(sep), "{s:?} may not contain separator {sep:?}");
    }
    strings.join(sep)
}

// Returns path to the metadata json.
fn invoke_rustc(builder: &SpirvBuilder) -> Result<PathBuf, SpirvBuilderError> {
    // Okay, this is a little bonkers: in a normal world, we'd have the user clone
    // rustc_codegen_spirv and pass in the path to it, and then we'd invoke cargo to build it, grab
    // the resulting .so, and pass it into -Z codegen-backend. But that's really gross: the user
    // needs to clone rustc_codegen_spirv and tell us its path! So instead, we *directly reference
    // rustc_codegen_spirv in spirv-builder's Cargo.toml*, which means that it will get built
    // alongside build.rs, and cargo will helpfully add it to LD_LIBRARY_PATH for us! However,
    // rustc expects a full path, instead of a filename looked up via LD_LIBRARY_PATH, so we need
    // to copy cargo's understanding of library lookup and find the library and its full path.
    let rustc_codegen_spirv = builder
        .rustc_codegen_spirv_location
        .clone()
        .unwrap_or_else(find_rustc_codegen_spirv);

    let mut rustflags = vec![
        format!("-Zcodegen-backend={}", rustc_codegen_spirv.display()),
        // Ensure the codegen backend is emitted in `.d` files to force Cargo
        // to rebuild crates compiled with it when it changes (this used to be
        // the default until https://github.com/rust-lang/rust/pull/93969).
        "-Zbinary-dep-depinfo".to_string(),
        "-Csymbol-mangling-version=v0".to_string(),
        "-Zcrate-attr=feature(register_tool)".to_string(),
        "-Zcrate-attr=register_tool(rust_gpu)".to_string(),
        // HACK(eddyb) this is the same configuration that we test with, and
        // ensures no unwanted surprises from e.g. `core` debug assertions.
        "-Coverflow-checks=off".to_string(),
        "-Cdebug-assertions=off".to_string(),
        // HACK(eddyb) we need this for `core::fmt::rt::Argument::new_*` calls
        // to *never* be inlined, so we can pattern-match the calls themselves.
        "-Zinline-mir=off".to_string(),
        // HACK(eddyb) similar to turning MIR inlining off, we also can't allow
        // optimizations that drastically impact (the quality of) codegen, and
        // GVN currently can lead to the memcpy-out-of-const-alloc-global-var
        // pattern, even for `ScalarPair` (e.g. `return None::<u32>;`).
        "-Zmir-enable-passes=-GVN".to_string(),
    ];

    // Wrapper for `env::var` that appropriately informs Cargo of the dependency.
    let tracked_env_var_get = |name| {
        if let MetadataPrintout::Full | MetadataPrintout::DependencyOnly = builder.print_metadata {
            println!("cargo:rerun-if-env-changed={name}");
        }
        env::var(name)
    };

    let mut llvm_args = vec![];
    if builder.multimodule {
        llvm_args.push("--module-output=multiple".to_string());
    }
    match builder.spirv_metadata {
        SpirvMetadata::None => (),
        SpirvMetadata::NameVariables => {
            llvm_args.push("--spirv-metadata=name-variables".to_string());
        }
        SpirvMetadata::Full => llvm_args.push("--spirv-metadata=full".to_string()),
    }
    if builder.relax_struct_store {
        llvm_args.push("--relax-struct-store".to_string());
    }
    if builder.relax_logical_pointer {
        llvm_args.push("--relax-logical-pointer".to_string());
    }
    if builder.relax_block_layout {
        llvm_args.push("--relax-block-layout".to_string());
    }
    if builder.uniform_buffer_standard_layout {
        llvm_args.push("--uniform-buffer-standard-layout".to_string());
    }
    if builder.scalar_block_layout {
        llvm_args.push("--scalar-block-layout".to_string());
    }
    if builder.skip_block_layout {
        llvm_args.push("--skip-block-layout".to_string());
    }
    if builder.preserve_bindings {
        llvm_args.push("--preserve-bindings".to_string());
    }
    let mut target_features = vec![];
    let abort_strategy = match builder.shader_panic_strategy {
        ShaderPanicStrategy::SilentExit => None,
        ShaderPanicStrategy::DebugPrintfThenExit {
            print_inputs,
            print_backtrace,
        } => {
            target_features.push("+ext:SPV_KHR_non_semantic_info".into());
            Some(format!(
                "debug-printf{}{}",
                if print_inputs { "+inputs" } else { "" },
                if print_backtrace { "+backtrace" } else { "" }
            ))
        }
        ShaderPanicStrategy::UNSOUND_DO_NOT_USE_UndefinedBehaviorViaUnreachable => {
            Some("unreachable".into())
        }
    };
    llvm_args.extend(abort_strategy.map(|strategy| format!("--abort-strategy={strategy}")));

    if let Ok(extra_codegen_args) = tracked_env_var_get("RUSTGPU_CODEGEN_ARGS") {
        llvm_args.extend(extra_codegen_args.split_whitespace().map(|s| s.to_string()));
    } else {
        llvm_args.extend(builder.extra_args.iter().cloned());
    }

    let llvm_args = join_checking_for_separators(llvm_args, " ");
    if !llvm_args.is_empty() {
        rustflags.push(["-Cllvm-args=", &llvm_args].concat());
    }

    target_features.extend(builder.capabilities.iter().map(|cap| format!("+{cap:?}")));
    target_features.extend(builder.extensions.iter().map(|ext| format!("+ext:{ext}")));
    let target_features = join_checking_for_separators(target_features, ",");
    if !target_features.is_empty() {
        rustflags.push(["-Ctarget-feature=", &target_features].concat());
    }

    if builder.deny_warnings {
        rustflags.push("-Dwarnings".to_string());
    }

    if let Ok(extra_rustflags) = tracked_env_var_get("RUSTGPU_RUSTFLAGS") {
        rustflags.extend(extra_rustflags.split_whitespace().map(|s| s.to_string()));
    }

    // If we're nested in `cargo` invocation, use a different `--target-dir`,
    // to avoid waiting on the same lock (which effectively dead-locks us).
    let outer_target_dir = match (env::var("PROFILE"), env::var_os("OUT_DIR")) {
        (Ok(outer_profile), Some(dir)) => {
            // Strip `$outer_profile/build/*/out`.
            [&outer_profile, "build", "*", "out"].iter().rev().try_fold(
                PathBuf::from(dir),
                |mut dir, &filter| {
                    if (filter == "*" || dir.ends_with(filter)) && dir.pop() {
                        Some(dir)
                    } else {
                        None
                    }
                },
            )
        }
        _ => None,
    };
    // FIXME(eddyb) use `crate metadata` to always be able to get the "outer"
    // (or "default") `--target-dir`, to append `/spirv-builder` to it.
    let target_dir = outer_target_dir.map(|outer| outer.join("spirv-builder"));

    let profile = if builder.release { "release" } else { "dev" };

    let mut cargo = Command::new("cargo");
    cargo.args([
        "build",
        "--lib",
        "--message-format=json-render-diagnostics",
        "-Zbuild-std=core",
        "-Zbuild-std-features=compiler-builtins-mem",
        "--profile",
        profile,
    ]);

    // FIXME(eddyb) consider moving `target-specs` into `rustc_codegen_spirv_types`.
    // FIXME(eddyb) consider the `RUST_TARGET_PATH` env var alternative.
    cargo
        .arg("--target")
        .arg(builder.path_to_target_spec.clone().unwrap_or_else(|| {
            PathBuf::from(env!("CARGO_MANIFEST_DIR"))
                .join("target-specs")
                .join(format!("{}.json", builder.target))
        }));

    if let Some(default_features) = builder.shader_crate_features.default_features {
        if !default_features {
            cargo.arg("--no-default-features");
        }
    }

    if !builder.shader_crate_features.features.is_empty() {
        cargo
            .arg("--features")
            .arg(builder.shader_crate_features.features.join(","));
    }

    // NOTE(eddyb) see above how this is computed and why it might be missing.
    if let Some(target_dir) = target_dir {
        cargo.arg("--target-dir").arg(target_dir);
    }

    // Clear Cargo environment variables that we don't want to leak into the
    // inner invocation of Cargo (because e.g. build scripts might read them),
    // before we set any of our own below.
    for (key, _) in env::vars_os() {
        let remove = key.to_str().map_or(false, |s| {
            s.starts_with("CARGO_FEATURES_") || s.starts_with("CARGO_CFG_")
        });
        if remove {
            cargo.env_remove(key);
        }
    }

    // NOTE(eddyb) Cargo caches some information it got from `rustc` in
    // `.rustc_info.json`, and assumes it only depends on the `rustc` binary,
    // but in our case, `rustc_codegen_spirv` changes are also relevant,
    // so we turn off that caching with an env var, just to avoid any issues.
    cargo.env("CARGO_CACHE_RUSTC_INFO", "0");

    // NOTE(eddyb) this used to be just `RUSTFLAGS` but at some point Cargo
    // added a separate environment variable using `\x1f` instead of spaces,
    // which allows us to have spaces within individual `rustc` flags.
    cargo.env(
        "CARGO_ENCODED_RUSTFLAGS",
        join_checking_for_separators(rustflags, "\x1f"),
    );

    let profile_in_env_var = profile.replace('-', "_").to_ascii_uppercase();

    // NOTE(eddyb) there's no parallelism to take advantage of multiple CGUs,
    // and inter-CGU duplication can be wasteful, so this forces 1 CGU for now.
    let num_cgus = 1;
    cargo.env(
        format!("CARGO_PROFILE_{profile_in_env_var}_CODEGEN_UNITS"),
        num_cgus.to_string(),
    );

    let build = cargo
        .stderr(Stdio::inherit())
        .current_dir(&builder.path_to_crate)
        .output()
        .expect("failed to execute cargo build");

    // `get_last_artifact` has the side-effect of printing invalid lines, so
    // we do that even in case of an error, to let through any useful messages
    // that ended up on stdout instead of stderr.
    let stdout = String::from_utf8(build.stdout).unwrap();
    if build.status.success() {
        get_sole_artifact(&stdout).ok_or_else(|| {
            eprintln!("--- build output ---\n{stdout}");
            panic!(
                "`{ARTIFACT_SUFFIX}` artifact not found in (supposedly successful) build output (see above)"
            );
        })
    } else {
        Err(SpirvBuilderError::BuildFailed)
    }
}

#[derive(Deserialize)]
struct RustcOutput {
    reason: String,
    filenames: Option<Vec<String>>,
}

const ARTIFACT_SUFFIX: &str = ".spv.json";

fn get_sole_artifact(out: &str) -> Option<PathBuf> {
    let last = out
        .lines()
        .filter_map(|line| {
            if let Ok(line) = serde_json::from_str::<RustcOutput>(line) {
                Some(line)
            } else {
                // Pass through invalid lines
                println!("{line}");
                None
            }
        })
        .filter(|line| line.reason == "compiler-artifact")
        .last()
        .expect("Did not find output file in rustc output");

    let mut filenames = last
        .filenames
        .unwrap()
        .into_iter()
        .filter(|v| v.ends_with(ARTIFACT_SUFFIX));
    let filename = filenames.next()?;
    assert_eq!(
        filenames.next(),
        None,
        "build had multiple `{ARTIFACT_SUFFIX}` artifacts"
    );
    Some(filename.into())
}

/// Internally iterate through the leaf dependencies of the artifact at `artifact`
fn leaf_deps(artifact: &Path, mut handle: impl FnMut(&RawStr)) -> std::io::Result<()> {
    let deps_file = artifact.with_extension("d");
    let mut deps_map = HashMap::new();
    depfile::read_deps_file(&deps_file, |item, deps| {
        deps_map.insert(item, deps);
        Ok(())
    })?;
    fn recurse(
        map: &HashMap<RawString, Vec<RawString>>,
        artifact: &RawStr,
        handle: &mut impl FnMut(&RawStr),
    ) {
        match map.get(artifact) {
            Some(entries) => {
                for entry in entries {
                    recurse(map, entry, handle);
                }
            }
            None => handle(artifact),
        }
    }
    recurse(&deps_map, artifact.to_str().unwrap().into(), &mut handle);
    Ok(())
}