`enum SpirvTargetEnv` containing all available targets #311

Firestar99 · 2025-07-01T09:36:51Z

List all available targets in enum SpirvTargetEnv and centralize parsing, to_string and target spec references there. Changes SpirvBuilder.target from String to the new enum and makes SpirvBuilder::new accept both String and the new enum to reduce breakage as much as possible.

…Env`

Firestar99 · 2025-07-01T17:34:10Z

crates/spirv-builder/src/lib.rs

@@ -490,10 +490,10 @@ impl Default for SpirvBuilder {
 }

 impl SpirvBuilder {
-    pub fn new(path_to_crate: impl AsRef<Path>, target: impl Into<String>) -> Self {
+    pub fn new(path_to_crate: impl AsRef<Path>, target: SpirvTargetEnv) -> Self {


This PR introduces a significant breaking change right here that will affect everyone. I would like to change SpirvBuilder.target to the new enum, so new users don't have to deal with strings. But this moves parsing of the target string from build() to here, where we can't just return an error easily. The options:

breaking change: return a Result for failed parsing, may be annoying to handle for the user

~~My choice:~~ breaking change: require everyone to use the new enum directly (SpirvTargetEnv::Vulkan_1_2) or explicitly call the parse function that may fail (SpirvTargetEnv::parse_triple("spirv-unknown-vulkan1.2")?)

a surprise panic if parsing fails

Why not impl Into<SpirvTargetEnv> and support &'static str, breaking everyone who didn't specify a string?

I forget if you can mark an impl or its methods as deprecated (or rather, if that ever results in a warning).

But honestly, enumerating the target-env explicitly is a bit silly. It would be much cooler if you can come up with a foolproof way for spirv-builder itself to create and cache a target JSON (e.g. in the target dir, which currently we only detect based off of $OUT_DIR, but maybe we could cheaply get "what would be the target dir used for the shader crate" out of Cargo?).

And then we presumably wouldn't even need this part of the system to care about the values at all and it can remain a string (unless that interferes with other plans ofc).

I may have an even better idea how not to break anything: Just have SpirvBuilder.target be Result<SpirvTargetEnv, *ParseError> so we can forward the error to the build() call. Then make new(..., target: impl IntoSpirvTargetEnv) so it can accept a &str, String or SpirvTargetEnv. We would only break anyone doing builder.target = Some("spirv-unknown-vulkan1.2") which is a small minority since that only works since about 2 months or so.

impl IntoSpirvTargetEnv ... so it can accept a &str, String or ...

I suppose one way to be 100% back-compat would be to implement IntoSpirvTargetEnv for all types that implement Into<String>, but that might feel wasteful, idk. Then again, some of this depends on whether we care about parsing SpirvTargetEnv at all.

I like that IDEs can auto-complete enum names, since they're symbols, not magic strings

eddyb · 2025-07-01T18:43:56Z

crates/rustc_codegen_spirv-target-specs/src/include_str.rs

+        match self {
+            SpirvTargetEnv::OpenGL_4_0 => {
+                include_str!("../target-specs/spirv-unknown-opengl4.0.json")
+            }
+            SpirvTargetEnv::OpenGL_4_1 => {
+                include_str!("../target-specs/spirv-unknown-opengl4.1.json")
+            }
+            SpirvTargetEnv::OpenGL_4_2 => {
+                include_str!("../target-specs/spirv-unknown-opengl4.2.json")
+            }
+            SpirvTargetEnv::OpenGL_4_3 => {
+                include_str!("../target-specs/spirv-unknown-opengl4.3.json")
+            }
+            SpirvTargetEnv::OpenGL_4_5 => {
+                include_str!("../target-specs/spirv-unknown-opengl4.5.json")
+            }
+            SpirvTargetEnv::Spv_1_0 => {
+                include_str!("../target-specs/spirv-unknown-spv1.0.json")
+            }
+            SpirvTargetEnv::Spv_1_1 => {
+                include_str!("../target-specs/spirv-unknown-spv1.1.json")
+            }
+            SpirvTargetEnv::Spv_1_2 => {
+                include_str!("../target-specs/spirv-unknown-spv1.2.json")
+            }
+            SpirvTargetEnv::Spv_1_3 => {
+                include_str!("../target-specs/spirv-unknown-spv1.3.json")
+            }
+            SpirvTargetEnv::Spv_1_4 => {
+                include_str!("../target-specs/spirv-unknown-spv1.4.json")
+            }
+            SpirvTargetEnv::Spv_1_5 => {
+                include_str!("../target-specs/spirv-unknown-spv1.5.json")
+            }
+            SpirvTargetEnv::Spv_1_6 => {
+                include_str!("../target-specs/spirv-unknown-spv1.6.json")
+            }
+            SpirvTargetEnv::Vulkan_1_0 => {
+                include_str!("../target-specs/spirv-unknown-vulkan1.0.json")
+            }
+            SpirvTargetEnv::Vulkan_1_1 => {
+                include_str!("../target-specs/spirv-unknown-vulkan1.1.json")
+            }
+            SpirvTargetEnv::Vulkan_1_1_Spv_1_4 => {
+                include_str!("../target-specs/spirv-unknown-vulkan1.1spv1.4.json")
+            }
+            SpirvTargetEnv::Vulkan_1_2 => {
+                include_str!("../target-specs/spirv-unknown-vulkan1.2.json")
+            }
+            SpirvTargetEnv::Vulkan_1_3 => {
+                include_str!("../target-specs/spirv-unknown-vulkan1.3.json")
+            }
+            SpirvTargetEnv::Vulkan_1_4 => {
+                include_str!("../target-specs/spirv-unknown-vulkan1.4.json")
+            }
+        }


Quick question since we keep changing these things, since I went with JSON files to minimal deviation from previous behavior, and because they wouldn't cause spurious rebuilds (relative to the spirv-builder version being used, since I would expect shaders to be rebuilt most of the times spirv-builder itself is rebuilt):

Could cargo-gpu generate the JSON file on-demand (and maybe cache it)? Especially since there's include_str! going on here, I feel like that's already what's happening?

Because the only difference between these files is, for spirv-unknown-X:

env is set to X

llvm-target is set to spirv-unknown-X

$ echo crates/rustc_codegen_spirv-target-specs/target-specs/*.json | xargs -n1 diff -U0 crates/rustc_codegen_spirv-targe t-specs/target-specs/spirv-unknown-spv1.0.json | rg '^[\-+] ' -r '' | sed 's/: .*/: .../' | sort -u "env": ... "llvm-target": ...

(run this without sed 's/: .*/: .../' to see the actual values)

They could even be generated by string interpolation, if not serde_json, since the target env name doesn't even need escaping!

cargo-gpu only needs them for the "legacy path" aka rustc_codegen_spirv versions which did not depend on *target-specs. And that "legacy" dependency is fixed to version 0.9 on crates, so technically these changes don't actually do anything. It just feels wrong not to adjust them as well.

Sorry, I'm not 100% sure what's going on, are you saying that most of the time, the .json files in the source tree get used?

I would actually be happier if cargo-gpu/spirv-builder created these from one template - I don't mind rustc_codegen_spirv-target-specs existing (and we can release older versions of that crate, if we want, I guess?) - but its main job could be "take this target_env string and return a JSON blob", without having the result of that templating be baked in the way it is today.

Wow, I actually wrote some nice docs for what's going on: https://github.com/Rust-GPU/cargo-gpu/blob/main/crates/cargo-gpu/src/target_specs.rs

And I get that they actually don't change much, just something I didn't know / want to worry about back when I wrote this.

Firestar99 requested review from eddyb, LegNeato and schell as code owners July 1, 2025 09:36

Firestar99 mentioned this pull request Jul 1, 2025

add spirv-unknown-wgsl target via naga #280

Draft

Firestar99 marked this pull request as draft July 1, 2025 11:32

Firestar99 force-pushed the target_env_enum branch 3 times, most recently from bbbcf8b to 61a51d6 Compare July 1, 2025 14:39

target enum: add enum SpirvTargetEnv containing all targets

be49382

Firestar99 force-pushed the target_env_enum branch from 326f31a to 669460a Compare July 1, 2025 15:51

Firestar99 mentioned this pull request Jul 1, 2025

target enum: fixup cargo gpu Rust-GPU/cargo-gpu#92

Draft

Firestar99 added 3 commits July 1, 2025 19:02

target enum: make SpirvTargetEnv::parse_triple() return a Result

8ca7f4f

spirv-builder: clap testing

be2b142

target enum: serde SpirvTargetEnv like a target string

bb65113

Firestar99 force-pushed the target_env_enum branch from 669460a to 109b8c9 Compare July 1, 2025 17:17

target enum: change SpirvBuilder.target from String to `SpirvTarget…

d80832e

…Env`

Firestar99 force-pushed the target_env_enum branch from 109b8c9 to 4be9bba Compare July 1, 2025 17:23

Firestar99 commented Jul 1, 2025

View reviewed changes

Firestar99 marked this pull request as ready for review July 1, 2025 17:50

eddyb reviewed Jul 1, 2025

View reviewed changes

target enum: propagate parsing error to build() to reduce breakage

51d17b9

Firestar99 force-pushed the target_env_enum branch from 6bd4a1b to 51d17b9 Compare July 1, 2025 20:17

Firestar99 marked this pull request as draft July 1, 2025 20:30

target enum: fix serde impl for target not round tripping

59d108b

Firestar99 self-assigned this Jul 1, 2025

Firestar99 marked this pull request as ready for review July 1, 2025 20:48

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

`enum SpirvTargetEnv` containing all available targets #311

`enum SpirvTargetEnv` containing all available targets #311

Uh oh!

Firestar99 commented Jul 1, 2025 •

edited

Loading

Uh oh!

Firestar99 Jul 1, 2025 •

edited

Loading

Uh oh!

eddyb Jul 1, 2025

Uh oh!

Firestar99 Jul 1, 2025

Uh oh!

eddyb Jul 1, 2025

Uh oh!

Firestar99 Jul 1, 2025

Uh oh!

eddyb Jul 1, 2025

Uh oh!

Firestar99 Jul 1, 2025

Uh oh!

eddyb Jul 1, 2025

Uh oh!

Firestar99 Jul 1, 2025 •

edited

Loading

Uh oh!

Uh oh!

enum SpirvTargetEnv containing all available targets #311

Are you sure you want to change the base?

enum SpirvTargetEnv containing all available targets #311

Uh oh!

Conversation

Firestar99 commented Jul 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Firestar99 Jul 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

eddyb Jul 1, 2025

Choose a reason for hiding this comment

Uh oh!

Firestar99 Jul 1, 2025

Choose a reason for hiding this comment

Uh oh!

eddyb Jul 1, 2025

Choose a reason for hiding this comment

Uh oh!

Firestar99 Jul 1, 2025

Choose a reason for hiding this comment

Uh oh!

eddyb Jul 1, 2025

Choose a reason for hiding this comment

Uh oh!

Firestar99 Jul 1, 2025

Choose a reason for hiding this comment

Uh oh!

eddyb Jul 1, 2025

Choose a reason for hiding this comment

Uh oh!

Firestar99 Jul 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

`enum SpirvTargetEnv` containing all available targets #311

`enum SpirvTargetEnv` containing all available targets #311

Firestar99 commented Jul 1, 2025 •

edited

Loading

Firestar99 Jul 1, 2025 •

edited

Loading

Firestar99 Jul 1, 2025 •

edited

Loading