13 releases (6 breaking)

0.9.0 Jul 25, 2023
0.7.0 Apr 21, 2023
0.6.1 Mar 20, 2023
0.4.0 Dec 21, 2022
0.1.0 Oct 16, 2020

#67 in Graphics APIs

Download history 194/week @ 2023-11-02 113/week @ 2023-11-09 93/week @ 2023-11-16 129/week @ 2023-11-23 129/week @ 2023-11-30 84/week @ 2023-12-07 124/week @ 2023-12-14 141/week @ 2023-12-21 81/week @ 2023-12-28 183/week @ 2024-01-04 159/week @ 2024-01-11 216/week @ 2024-01-18 271/week @ 2024-01-25 108/week @ 2024-02-01 138/week @ 2024-02-08 236/week @ 2024-02-15

773 downloads per month
Used in krnlc


6.5K 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

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-2023-05-27.

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

Rust toolchain
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).


~238K SLoC