rust-gpu/crates/spirv-builder/README.md

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

Because of its nature, rustc_codegen_spirv, and therefore spirv-builder by extension, require the use of a very specific nightly toolchain of Rust.

The current toolchain is: nightly-2023-01-21.

Toolchains for previous versions of spirv-builder:

Version	Toolchain
0.6.*	nightly-2023-01-21
0.5.0	nightly-2022-12-18
0.4.0	nightly-2022-10-29
0.4.0-alpha.16 - 0.4.0-alpha.17	nightly-2022-10-01
0.4.0-alpha.15	nightly-2022-08-29
0.4.0-alpha.13 - 0.4.0-alpha.14	nightly-2022-04-11

The nightly toolchain has to match exactly. Starting with 0.4.0-alpha.15, the commit hash of your local toolchain is checked and you'll get a build error when building rustc_codegen_spirv with the wrong toolchain. If you want to experiment with different versions, this check can be omitted by defining the environment variable RUSTGPU_SKIP_TOOLCHAIN_CHECK^{since 0.4.0-alpha.16}. Keep in mind that, as rustc_codegen_spirv is heavily dependent on rustc's internal API, diverging too much from the required toolchain will quickly result in compile errors.