10 unstable releases (3 breaking)

0.6.1 Mar 20, 2023
0.6.0 Mar 15, 2023
0.5.0 Feb 2, 2023
0.4.0 Dec 21, 2022
0.1.0 Oct 16, 2020

#26 in Graphics APIs

Download history 2489/week @ 2022-12-06 3392/week @ 2022-12-13 644/week @ 2022-12-20 609/week @ 2022-12-27 1407/week @ 2023-01-03 1698/week @ 2023-01-10 2267/week @ 2023-01-17 2221/week @ 2023-01-24 2974/week @ 2023-01-31 3607/week @ 2023-02-07 2987/week @ 2023-02-14 3422/week @ 2023-02-21 3306/week @ 2023-02-28 3757/week @ 2023-03-07 4750/week @ 2023-03-14 1972/week @ 2023-03-21

14,598 downloads per month


21K SLoC


Rust version

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.


use spirv_builder::{MetadataPrintout, SpirvBuilder};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    SpirvBuilder::new("my_shaders", "spirv-unknown-vulkan1.1")

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_CHECKsince 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.


~402K SLoC