Merge remote-tracking branch 'aosp/upstream-master' into HEAD

Includes:
419517b spvc is optional, off by default, in Android.mk (#563)
6099206 Remove commas for googltest test suite macro (#561)
9e1151a Add NV_EXTENSIONS shader types on util compiler conversion. (#559)
f5abb5c Move public headers to libshaderc. (#558)
e7a1910 WIP Fix install. (#556)
6ff17fe Fix cmake build for libshaderc_spvc. (#554)
8e5a205 Remove use of deprecated googletest macro (#541)
634dd35 Flesh out for Dawn fuzzers. (#552)
ce7d921 Use the full spirv-cross dependency. (#550)
cabee68 BUILD.gn: fix build error on is_component_build=true (#549)
2dc76ac BUILD.gn: Make libraries Chromium-style "components" (#548)
fdecc63 Disable spvc build by default.  (#542) (#547)
026d4e3 Fix build with exceptions off. (#546)
d93ef8b Fix MinGW: Format %lu must be unsigned long. (#544)
5c97fca Fix leaks in tests (#545)
003c82f Fix ASAN build. (#543)
a0a4695 Add libshaderc_spvc interface to SPIRV-Cross. (#524)
fcb2d4e Fix NDK build. (#540)
14ae0de Android.mk: better fallback for SPIRV-Tools dir (#538)
6733f17 Roll RE2 Dep (#537)
1079643 Fixup source matching test (#534)
b9e151b Fix Windows test script return value. (#533)
355fe6a Switch GLSLang to upstream (#515)
d6c89a6 Generate source text debug info if requested (#455) (#532)
3faf34a [kokoro] Stop running tests on VS 2013 builds. (#531)
a516b67 Update Android NDK. (#530)
4727ede Test shader uniforms need descriptor set and binding (#523)
32b6d90 Add git clone of re2 and effcee to the Dockerfile (#527)
53c776f Update to use Android.mk from glslang (#520)
2898ad7 Add unit tests for mesh and task shaders
44f7dd2 Add support for NV_EXTENSIONS in #pragma shader_stage()
7544155 Build file updates. (#514)
eb743ec Fixup shadowed variables (#513)
823901b Unpin googletest. It has been fixed upstream
a8bbd80 Add effcee and re2 when building spirv-tools tests (#510)
92efe45 Only include third_party directories if needed. (#507)
909f0d3 BUILD.gn: remove the static_library target.
818a37b [kokoro] Report error if ctest fails
a4116bc [kokoro] Compile for x86_64 and print CMake version on Windows
72512db VS builds: Pin an older googletest to avoid around a CMake problem
b806cd2 Disable layout and relax logical pointer for optimizer validation
196d38f BUILD.gn: Make source_set not depend on static_libraries
c9da865 BUILD.gn: only use complete_static_lib on mac
a1f4027 Start Shaderc v2018.1-dev development
7d8582b Finalize Shaderc v2018.0
ed3c8e3 Update CHANGES
69413e3 Fix -Wfallthrough warnings
6503446 Return *this in move-assign operator
0e81b8b Add default ctor and move assignment to CompilationResult
7193d2e Adjust to glslang's removal of NV_EXTENSIONS from headers
41d15ff BUILD.gn: make the static_lib complete to fix the build on OSX
fc4ff0e Pass environment version into SPIRV-Tools properly
5804d8c Add SONAME version to the library

Test: checkbuild.py on Linux; unit tests on Windows
Change-Id: Ib255e3b16d7e96ce4bcc5ccaff9c178c472d8bb7
tree: fe1d41824093eff1c970fa3e1fad0c7fb9876982
  1. .gitignore
  2. AUTHORS
  3. Android.mk
  4. BUILD.gn
  5. CHANGES
  6. CMakeLists.txt
  7. CONTRIBUTING.md
  8. CONTRIBUTORS
  9. DEPS
  10. DEVELOPMENT.howto.md
  11. Dockerfile
  12. LICENSE
  13. README.md
  14. android_test/
  15. build_overrides/
  16. cmake/
  17. examples/
  18. glslc/
  19. kokoro/
  20. libshaderc/
  21. libshaderc_spvc/
  22. libshaderc_util/
  23. shader.vert.spvasm
  24. third_party/
  25. utils/
README.md

Shaderc

Linux Build Status MacOS Build Status Windows Build Status

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.) We currently require r18b.

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.

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

Experimental: On Windows, instead of building from source, you can get the artifacts built by Appveyor for the top of the tree of the master branch under the “Artifacts” tab of a certain job.

  1. Check out the source code:
git clone https://github.com/google/shaderc $SOURCE_DIR
cd $SOURCE_DIR
./utils/git-sync-deps
cd $SOURCE_DIR/

Note: The known-good branch of the repository contains a known_good.json file describing a set of repo URLs and specific commits that have been tested together. This information is updated periodically, and typically matches the latest update of these sources in the development branch of the Android NDK. The known-good branch also contains a update_shaderc.py script that will read the JSON file and checkout those specific commits for you.

  1. Ensure you have the requisite tools -- see the tools subsection below.

  2. 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:

Building and running Shaderc 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 internally, 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.

Bindings

Bindings are maintained by third parties, may contain content offered under a different license, and may reference or contain older versions of Shaderc and its dependencies.