From d0298a36c3a00fab2b67adba4f3b6b00958de66a Mon Sep 17 00:00:00 2001
From: Ryan Harrison <zoddicus@users.noreply.github.com>
Date: Fri, 7 Jun 2019 08:29:13 -0700
Subject: [PATCH]  Add details of spvc to README.md (#661)

Fixes #562
---
 README.md | 37 +++++++++++++++++++++++++++++++++----
 1 file changed, 33 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index 646e00eb0..43a60466d 100644
--- a/README.md
+++ b/README.md
@@ -4,10 +4,19 @@ A collection of tools, libraries and tests for shader compilation.
 At the moment it includes:
 
 - [`glslc`](glslc), a command line compiler for GLSL/HLSL to SPIR-V, and
-- [`libshaderc`](libshaderc), a library API for doing the same.
-
-Shaderc wraps around core functionality in [glslang][khr-glslang]
-and [SPIRV-Tools][spirv-tools].  Shaderc aims to
+- [`libshaderc`](libshaderc), a library API for accessing `glslc` functionality.
+- [`spvc`](spvc), a command line wrapper around the SPIR-V to GLSL/HLSL/MSL
+  compiler [SPIRV-Cross][spirv-cross], and
+- [`libshaderc_spvc`](libshaderc_spvc), a library API for accessing `spvc`
+  functionality.
+
+**Note:** The fact that that `libshaderc` is not named `libshaderc_glslc` is a
+quirk of history, and a known inconsistancy. Changing it would require a
+significant amount of renaming and breaking of downstream projects, so it is
+being left as is.
+
+`glslc` wraps around core functionality in [glslang][khr-glslang]
+and [SPIRV-Tools][spirv-tools]. `glslc` and its library aims to
 to provide:
 * a command line compiler with GCC- and Clang-like usage, for better
   integration with build systems
@@ -16,6 +25,16 @@ to provide:
   operating systems
 * increased functionality such as file `#include` support
 
+`spvc` wraps around core functionality in [spirv-cross][spirv-cross]
+and [SPIRV-Tools][spirv-tools]. `spirv` and its library aims to
+provide:
+
+* validation and transformation of inputs before cross-compiling
+* an API designed around integration with specific projects like [Dawn][dawn]
+
+**Note:** `spvc` and its library are WIP and optional artifacts that are by
+default disabled in the build. How to enabled is detailed below.
+
 ## Downloads
 
 <img alt="Linux" src="kokoro/img/linux.png" width="20px" height="20px" hspace="2px"/>[![Linux Build Status](https://storage.googleapis.com/shaderc/badges/build_status_linux_clang_release.svg)](https://storage.googleapis.com/shaderc/badges/build_link_linux_clang_release.html)
@@ -204,6 +223,14 @@ test.vert
 /code $ glslc -c -o - test.vert | spirv-dis
 ```
 
+### Building spvc
+
+The value `SHADERC_ENABLE_SPVC` in `CMakeLists.txt` must be set to `ON` to
+enable building `spvc`.
+
+This can be achieved by either editing the file in your checkout, or passing
+`-DSHADERC_ENABLE_SPVC=ON` to `cmake` to set the value.
+
 ## Bug tracking
 
 We track bugs using GitHub -- click on the "Issues" button on
@@ -234,6 +261,8 @@ older versions of Shaderc and its dependencies.
 
 [khr-glslang]: https://github.com/KhronosGroup/glslang
 [spirv-tools]: https://github.com/KhronosGroup/SPIRV-Tools
+[spirv-cross]: https://github.com/KhronosGroup/SPIRV-Cross
 [pyshaderc]: https://github.com/realitix/pyshaderc
 [shaderc-rs]: https://github.com/google/shaderc-rs
 [appveyor]: https://ci.appveyor.com/project/dneto0/shaderc
+[dawn]: https://dawn.googlesource.com/dawn