Skip to content
Rust bindings for the shaderc library.
Branch: master
Clone or download
antiagainst Update native projects
This is the last batch of commits supporting Python2. Following
commits for SPIRV-Tools and Shaderc will require Python3.
Latest commit c5bb329 Apr 22, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
shaderc-rs Create shaderc-sys for FFI, building, and linking (#46) Apr 22, 2019
shaderc-sys Update native projects Apr 22, 2019
.appveyor.yml Update docs: Ninja now required to build with MSVC (#48) Apr 22, 2019
.gitignore
.gitmodules Create shaderc-sys for FFI, building, and linking (#46) Apr 22, 2019
.travis.yml Increase Travis CI wait time to 20 minutes Aug 20, 2018
CONTRIBUTING.md
Cargo.toml
LICENSE Add Apache 2.0 LICENSE. Dec 21, 2016
README.md Update docs: Ninja now required to build with MSVC (#48) Apr 22, 2019

README.md

shaderc-rs

Version Documentation Build Status Build status

Rust bindings for the shaderc library.

Disclaimer

This is not an official Google product (experimental or otherwise), it is just code that happens to be owned by Google.

Usage

The included shaderc-sys crate uses build.rs to discover or build a copy of shaderc libraries. See Setup section.

First add to your Cargo.toml:

[dependencies]
shaderc = "0.5"

Then add to your crate root:

extern crate shaderc;

Documentation

shaderc provides the Compiler interface to compile GLSL/HLSL source code into SPIR-V binary modules or assembly code. It can also assemble SPIR-V assembly into binary module. Default compilation behavior can be adjusted using CompileOptions. Successful results are kept in CompilationArtifacts.

Please see Documentation for detailed documentation.

Example

Compile a shader into SPIR-V binary module and assembly text:

use shaderc;

let source = "#version 310 es\n void EP() {}";

let mut compiler = shaderc::Compiler::new().unwrap();
let mut options = shaderc::CompileOptions::new().unwrap();
options.add_macro_definition("EP", Some("main"));
let binary_result = compiler.compile_into_spirv(
    source, shaderc::ShaderKind::Vertex,
    "shader.glsl", "main", Some(&options)).unwrap();

assert_eq!(Some(&0x07230203), binary_result.as_binary().first());

let text_result = compiler.compile_into_spirv_assembly(
    source, shaderc::ShaderKind::Vertex,
    "shader.glsl", "main", Some(&options)).unwrap();

assert!(text_result.as_text().starts_with("; SPIR-V\n"));

Setup

The order of preference in which the build script will attempt to obtain shaderc can be controlled by several options, which are passed through to shaderc-sys when building shaderc-rs:

  1. The option --features build-from-source will prevent automatic library detection and force building from source.
  2. If the SHADERC_LIB_DIR environment variable is set to /path/to/shaderc/libs/, it will take precedence and libshaderc_combined.a (and the glsang and SPIRV libraries on Linux) will be searched in the /path/to/shaderc/libs/ directory.
  3. On Linux, /usr/lib/ will be automatically searched for system libraries if none of the above were given.
  4. If no other option was set or succeeded, shaderc-sys will fall back to checking out and compiling a copy of shaderc. This procedure is quite slow.

NOTE: --no-default-features still works on shaderc-rs, but shaderc-sys implements this behavior in a deprecated manner, and it will be removed in the next release. This method only works with a monolithic libshaderc_combined.a. Refer to pre-0.5 documentation for more information. Prefer SHADERC_LIB_DIR="/path/to/shaderc/libs/".

Building from Source

The shaderc-sys build.rs will automatically check out and compile a copy of native C++ shaderc and link to the generated artifacts, which requires git, cmake, and python existing in the PATH.

To build your own libshaderc for the shaderc-sys crate, the following tools must be installed and available on PATH:

  • CMake
  • Ninja (required on windows-msvc, but optional on all other platforms)
  • Git
  • Python (works with both Python 2.x and 3.x, on windows the executable must be named python.exe)
  • a C++11 compiler

These requirements can be either installed with your favourite package manager or with installers from the projects' websites. Below are some example ways to get setup.

windows-msvc Example Setup

  1. rustup default stable-x86_64-pc-windows-msvc
  2. Install Build Tools for Visual Studio 2017. If you have already been using this toolchain then its probably already installed.
  3. Install Ninja (download ninja-win.zip and extract ninja.exe somewhere suitable).
  4. Install msys2, following ALL of the instructions.
  5. Then in the msys2 terminal run: pacman --noconfirm -Syu mingw-w64-x86_64-cmake mingw-w64-x86_64-python2
  6. Edit the PATH environment variable to include the path where you extracted ninja.exe, and the msys2 mingw64 binary path.

windows-gnu Example Setup

windows-gnu toolchain is not supported but you can instead cross-compile to windows-gnu from windows-msvc.

Steps 1 and 2 are to workaround https://github.com/rust-lang/rust/issues/49078 by using the same mingw that rust uses.

  1. Download and extract https://s3-us-west-1.amazonaws.com/rust-lang-ci2/rust-ci-mirror/x86_64-6.3.0-release-posix-seh-rt_v5-rev2.7z
  2. Add the absolute path to mingw64\bin to your PATH environment variable.
  3. Run the command: rustup default stable-x86_64-pc-windows-msvc
  4. Run the command: rustup target install x86_64-pc-windows-gnu
  5. Install Build Tools for Visual Studio 2017. If you have already been using this toolchain then its probably already installed.
  6. Install Ninja (download ninja-win.zip and extract ninja.exe somewhere suitable).
  7. Install msys2, following ALL of the instructions.
  8. Then in the msys2 terminal run: pacman --noconfirm -Syu mingw-w64-x86_64-cmake mingw-w64-x86_64-make mingw-w64-x86_64-python2
  9. Edit the PATH environment variable to include the path where you extracted ninja.exe, and the msys2 mingw64 binary path.
  10. Any cargo command that builds the project needs to include --target x86_64-pc-windows-gnu e.g. to run: cargo run --target x86_64-pc-windows-gnu

Linux Example Setup

Use your package manager to install the required dev-tools

For example on ubuntu:

sudo apt-get install build-essential git python cmake

On Arch linux, the shaderc package will include glsang and SPIRV libs in a detectable location.

macOS Example Setup

Assuming Homebrew:

brew install cmake

Contributions

This project is licensed under the Apache 2 license. Please see CONTRIBUTING before contributing.

Authors

This project is initialized and mainly developed by Lei Zhang (@antiagainst).

You can’t perform that action at this time.