Crate spirv_builder

spirv-builder

This crate gives you SpirvBuilder, a tool to build shaders using rust-gpu.

It takes care of pulling in the SPIR-V backend for Rust, rustc_codegen_spirv, and invoking a nested build using appropriate compiler options, some of which may be set using the SpirvBuilder API.

Example

use spirv_builder::{MetadataPrintout, SpirvBuilder};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    SpirvBuilder::new("my_shaders", "spirv-unknown-vulkan1.1")
        .print_metadata(MetadataPrintout::Full)
        .build()?;
    Ok(())
}

This example will build a shader crate called my_shaders. You typically insert this code in your crate’s build.rs that requires the shader binary. The path to the shader module’s binary will be set in the my_shaders.spv environment variable, which you can include in your project using something along the lines of:

const SHADER: &[u8] = include_bytes!(env!("my_shaders.spv"));

Building with spirv-builder

As spirv-builder relies on rustc_codegen_spirv being built for it (by Cargo, as a direct dependency), and due to the special nature of the latter (as a rustc codegen backend “plugin”), both end up sharing the requirement for a very specific nightly toolchain version of Rust.

The current Rust toolchain version is: nightly-2024-04-24.

Rust toolchain version history across rust-gpu releases (since 0.4):

spirv-builder version	Rust toolchain version
0.10	nightly-2024-04-24
0.9	nightly-2023-05-27
0.8	nightly-2023-04-15
0.7	nightly-2023-03-04
0.6	nightly-2023-01-21
0.5	nightly-2022-12-18
0.4	nightly-2022-10-29

^{As patch versions must be semver-compatible, they will always require the
same toolchain (for example, 0.6.0 and 0.6.1 both use nightly-2023-01-21).}

Only that exact Rust nightly toolchain version is supported. Since 0.4, the commit hash of your current Rust toolchain is checked and you’ll get a build error when building rustc_codegen_spirv with the wrong toolchain.
Notably, the error will also show what the rust-toolchain.toml file should contain (to get the expected toolchain), which you can rely on when updating to a new release.

If you want to experiment with different, unsupported, Rust toolchain versions, this check can be omitted by defining the environment variable RUSTGPU_SKIP_TOOLCHAIN_CHECK. Keep in mind that, as rustc_codegen_spirv is heavily dependent on rustc’s internal APIs, diverging too much from the supported toolchain version will quickly result in compile errors (or worse, e.g. spurious errors and/or incorrect behavior, when compiling shaders with it).

Modules

cargo_cmd

serde

Serde

serde_json

Serde JSON

Structs

CompileResult

OptimizerOptions

Options for specifying the behavior of the optimizer Copied from spirv-tools/src/opt.rs struct Options, with some fields disabled.

ShaderCrateFeatures

Cargo features specification for building the shader crate.

SpirvBuilder

SpirvTarget

A well-formed rust-gpu target.

ValidatorOptions

Options for specifying the behavior of the validator Copied from spirv-tools/src/val.rs struct ValidatorOptions, with some fields disabled.

Enums

Capability

SPIR-V operand kind: Capability

MetadataPrintout

ModuleResult

ShaderPanicStrategy

Strategy used to handle Rust panic!s in shaders compiled to SPIR-V.

SpirvBuilderError

SpirvMetadata

TargetError

TargetSpecVersion

Enum for different versions of target specs, to allow changing the target spec for different rust versions. The version listed in the enum is always the minimum version to require said target spec, with the newest version always at the top.

Constants

SPIRV_TARGET_PREFIX

a

Functions

query_rustc_version