shaderc

shaderc is the Rust binding for Google’s shaderc C++ library, giving Rust programs a safe, ergonomic API for turning GLSL or HLSL shader source into SPIR-V binary modules or human-readable assembly. It wraps the same shader-compilation toolchain that ships inside the Android NDK and the Vulkan SDK, so graphics and game engine code can compile shaders at build time or at runtime without shelling out to an external tool.

The crate is split across a high-level shaderc crate and a low-level shaderc-sys FFI crate that locates or builds the native shaderc library. shaderc-sys’s build script will discover an existing shaderc install via SHADERC_LIB_DIR, VULKAN_SDK, pkg-config, or system library paths, and falls back to checking out and compiling shaderc from source when nothing is found — trading a slower first build for zero manual setup on the consuming side.

What You Get

• A Compiler type that compiles GLSL/HLSL source into SPIR-V binary modules, SPIR-V assembly, or preprocessed source, and can assemble raw SPIR-V assembly into a binary module
• A CompileOptions builder covering target environment/version, SPIR-V version, source language, optimization level, macro definitions, HLSL register/binding mapping, and a custom #include resolution callback
• Typed enums (ShaderKind, TargetEnv, SpirvVersion, GlslProfile, Limit, ResourceKind) that model the shaderc C API without leaking raw FFI types into calling code
• A shaderc-sys crate with a build script that finds or builds the native shaderc library automatically, so consumers don’t hand-manage the C++ dependency
• build-from-source and prefer-static-linking Cargo features to control exactly how the native library is obtained and linked

Common Use Cases

• Compiling GLSL/HLSL shaders to SPIR-V ahead-of-time in a game engine’s asset build pipeline
• Runtime shader compilation for a Vulkan renderer that loads user- or content-authored shaders
• Cross-compiling HLSL shaders written for DirectX-style tooling into SPIR-V for Vulkan backends
• Validating and optimizing shader source as part of a graphics test suite or CI pipeline

Under The Hood

Architecture The project is a two-crate Cargo workspace: shaderc-rs (shaderc-rs/src/lib.rs) provides the safe, idiomatic Rust API, while shaderc-sys provides raw FFI bindings plus a build.rs/cmd_finder module that locates or compiles the native C++ shaderc library. Compiler and CompileOptions hold opaque native handles obtained through shaderc-sys and translate C status codes into a typed Error enum surfaced via a crate-wide Result<T> alias, so callers never see raw FFI failure codes. The custom #include resolution path bridges a user-supplied Rust closure into the C callback interface and wraps the call in panic::catch_unwind to stop a panicking closure from unwinding across the FFI boundary — a deliberate, correctness-focused design choice given the C ABI can’t tolerate Rust unwinding.

Tech Stack shaderc-rs depends only on libc at the API layer; shaderc-sys adds link-cplusplus at runtime and cmake, pkg-config, and roxmltree as build-dependencies to drive native compilation and Vulkan SDK version parsing. The build script searches SHADERC_LIB_DIR, VULKAN_SDK, pkg-config, and platform system paths for a prebuilt shaderc before falling back to checking out and building the C++ shaderc project from source with CMake (and Ninja on Windows). build-from-source and prefer-static-linking Cargo features let consumers override this search order explicitly.

Code Quality Tests are embedded directly in shaderc-rs/src/lib.rs as 35 #[test] functions exercising compilation, preprocessing, assembling, and each CompileOptions setter, using the assert_matches crate for pattern-based assertions on Result/Error variants rather than a separate tests/ integration suite. Two GitHub Actions workflows (check.yml, build-test.yml) run the build and test matrix across platforms, which matters here given the native build script’s OS-specific code paths. Error handling is explicit and typed throughout (Result<T, Error>), with no evidence of swallowed errors in the reviewed source.

API Design The public API is a small, deliberately C++-shaped surface: a Compiler you construct once, a builder-style CompileOptions you configure with chained setters, and typed enums (ShaderKind, TargetEnv, SpirvVersion, GlslProfile, Limit) standing in for the C API’s integer constants. This keeps the mental model close to the underlying shaderc C++ library — useful for developers already familiar with it — at some cost to idiomatic Rust ergonomics (no fluent builder chaining, unwrap()-heavy examples in the README). The value here isn’t novel shader-compilation technology; it’s a safe, cross-platform-buildable wrapper around Google’s own shaderc, with the native-library discovery/build-from-source fallback doing the real engineering work of making the crate usable without manual C++ toolchain setup.