Shaderc

A collection of tools, libraries and tests for shader compilation.
At the moment it includes:

glslc, a command line compiler for GLSL/HLSL to SPIR-V, and
libshaderc, a library API for doing the same.

Shaderc wraps around core functionality in glslang
and SPIRV-Tools. Shaderc aims to
to provide:

a command line compiler with GCC- and Clang-like usage, for better
integration with build systems
an API where functionality can be added without breaking existing clients
an API supporting standard concurrency patterns across multiple
operating systems
increased functionality such as file #include support

Status

Shaderc has maintained backward compatibility for quite some time, and we
don't anticipate any breaking changes.
Ongoing enhancements are described in the CHANGES file.

Shaderc has been shipping in the
Android NDK since version r12b.
(The NDK build uses sources from https://android.googlesource.com/platform/external/shaderc/.
Those repos are downstream from GitHub.)

For licensing terms, please see the LICENSE file. If interested in
contributing to this project, please see CONTRIBUTING.md.

This is not an official Google product (experimental or otherwise), it is just
code that happens to be owned by Google. That may change if Shaderc gains
contributions from others. See the CONTRIBUTING.md file
for more information. See also the AUTHORS and
CONTRIBUTORS files.

File organization

android_test/ : a small Android application to verify compilation
cmake/: CMake utility functions and configuration for Shaderc
examples/: Example programs
glslc/: an executable to compile GLSL to SPIR-V
libshaderc/: a library for compiling shader strings into SPIR-V
libshaderc_util/: a utility library used by multiple shaderc components
third_party/: third party open source packages; see below
utils/: utility scripts for Shaderc

Shaderc depends on glslang, the Khronos reference compiler for GLSL.
Sometimes a change updates both Shaderc and glslang. In that case the
glslang change will appear in google/glslang
before it appears upstream in KhronosGroup/glslang
We intend to upstream all changes to glslang. We maintain the separate
copy only to stage those changes for review, and to provide something for
Shaderc to build against in the meantime. Please see
DEVELOPMENT.howto.md for more details.

Shaderc depends on SPIRV-Tools for assembling, disassembling,
and transforming SPIR-V binaries.

Shaderc depends on the Google Test
testing framework.

In the following sections, $SOURCE_DIR is the directory you intend to clone
Shaderc into.

Getting and building Shaderc

Check out the source code:

git clone https://github.com/google/shaderc $SOURCE_DIR
cd $SOURCE_DIR/third_party
git clone https://github.com/google/googletest.git
git clone https://github.com/google/glslang.git
git clone https://github.com/KhronosGroup/SPIRV-Tools.git spirv-tools
git clone https://github.com/KhronosGroup/SPIRV-Headers.git spirv-tools/external/spirv-headers
cd $SOURCE_DIR/

Ensure you have the requisite tools -- see the tools subsection below.
Decide where to place the build output. In the following steps, we'll call it
$BUILD_DIR. Any new directory should work. We recommend building outside
the source tree, but it is also common to build in a (new) subdirectory of
$SOURCE_DIR, such as $SOURCE_DIR/build.

4a) Build (and test) with Ninja on Linux or Windows:

cd $BUILD_DIR
cmake -GNinja -DCMAKE_BUILD_TYPE={Debug|Release|RelWithDebInfo} $SOURCE_DIR
ninja
ctest # optional

4b) Or build (and test) with MSVC on Windows:

cd $BUILD_DIR
cmake $SOURCE_DIR
cmake --build . --config {Release|Debug|MinSizeRel|RelWithDebInfo}
ctest -C {Release|Debug|MinSizeRel|RelWithDebInfo}

4c) Or build with MinGW on Linux for Windows:
(Skip building threaded unit tests due to
Googletest bug 606)

cd $BUILD_DIR
cmake -GNinja -DCMAKE_BUILD_TYPE={Debug|Release|RelWithDebInfo} $SOURCE_DIR \
   -DCMAKE_TOOLCHAIN_FILE=$SOURCE_DIR/cmake/linux-mingw-toolchain.cmake \
   -Dgtest_disable_pthreads=ON
ninja

After a successful build, you should have a glslc executable somewhere under
the $BUILD_DIR/glslc/ directory, as well as a libshaderc library somewhere
under the $BUILD_DIR/libshaderc/ directory.

The default behavior on MSVC is to link with the static CRT. If you would like
to change this behavior -DSHADERC_ENABLE_SHARED_CRT may be passed on the
cmake configure line.

See the libshaderc README for more on using the library
API in your project.

Tools you'll need

For building, testing, and profiling Shaderc, the following tools should be
installed regardless of your OS:

CMake: for generating compilation targets.
Python: for utility scripts and running the test suite.

On Linux, the following tools should be installed:

gcov: for testing code
coverage, provided by the gcc package on Ubuntu.
lcov: a graphical frontend
for gcov, provided by the lcov package on Ubuntu.
genhtml: for creating reports in html
format from lcov output, provided by the lcov package on Ubuntu.

On Linux, if cross compiling to Windows:

mingw: A GCC-based cross compiler targeting Windows
so that generated executables use the Micrsoft C runtime libraries.

On Windows, the following tools should be installed and available on your path:

Visual Studio 2013 Update 4 or later. Previous versions of Visual Studio
will likely work but are untested.
Git - including the associated tools, Bash, diff.

Optionally, the following tools may be installed on any OS:

asciidoctor: for generating documenation.
- pygments.rb required by
  asciidoctor for syntax highlighting.
nosetests: for testing the Python code.

Building and running Shderc using Docker

Please make sure you have the Docker engine
installed on your machine.

To create a Docker image containing Shaderc command line tools, issue the
following command in ${SOURCE_DIR}: docker build -t <IMAGE-NAME> ..
The created image will have all the command line tools installed at
/usr/local interally, and a data volume mounted at /code.

Assume <IMAGE-NAME> is shaderc/shaderc from now on.

To invoke a tool from the above created image in a Docker container:

docker run shaderc/shaderc glslc --version

Alternatively, you can mount a host directory (e.g., example) containing
the shaders you want to manipulate and run different kinds of tools via
an interactive shell in the container:

$ docker run -i -t -v `pwd`/example:/code shaderc/shaderc
/code $ ls
test.vert
/code $ glslc -c -o - test.vert | spirv-dis

Bug tracking

We track bugs using GitHub -- click on the "Issues" button on
the project's GitHub page.

Test coverage

On Linux, you can obtain test coverage as follows:

cd $BUILD_DIR
cmake -GNinja -DCMAKE_BUILD_TYPE=Debug -DENABLE_CODE_COVERAGE=ON $SOURCE_DIR
ninja
ninja report-coverage

Then the coverage report can be found under the $BUILD_DIR/coverage-report
directory.

dgkoch/shaderc