README.md

   1 # SPIR-V Tools
   2
   3 [![Build Status](https://travis-ci.org/KhronosGroup/SPIRV-Tools.svg?branch=master)](https://travis-ci.org/KhronosGroup/SPIRV-Tools)
   4 [![Build status](https://ci.appveyor.com/api/projects/status/gpue87cesrx3pi0d/branch/master?svg=true)](https://ci.appveyor.com/project/Khronoswebmaster/spirv-tools/branch/master)
   5
   6 ## Overview
   7
   8 The SPIR-V Tools project provides an API and commands for processing SPIR-V
   9 modules.
  10
  11 The project includes an assembler, binary module parser, disassembler, and
  12 validator for SPIR-V, all based on a common static library. The library contains
  13 all of the implementation details, and is used in the standalone tools whilst
  14 also enabling integration into other code bases directly.
  15
  16 The interfaces are still under development, and are expected to change.
  17
  18 SPIR-V is defined by the Khronos Group Inc.
  19 See the [SPIR-V Registry][spirv-registry] for the SPIR-V specification,
  20 headers, and XML registry.
  21
  22 ## Verisoning SPIRV-Tools
  23
  24 See [`CHANGES`](CHANGES) for a high level summary of recent changes, by version.
  25
  26 SPIRV-Tools project version numbers are of the form `v`*year*`.`*index* and with
  27 an optional `-dev` suffix to indicate work in progress.  For exampe, the
  28 following versions are ordered from oldest to newest:
  29
  30 * `v2016.0`
  31 * `v2016.1-dev`
  32 * `v2016.1`
  33 * `v2016.2-dev`
  34 * `v2016.2`
  35
  36 Use the `--version` option on each command line tool to see the software
  37 version.  An API call reports the software version as a C-style string.
  38
  39 ## Supported features
  40
  41 ### Assembler, binary parser, and disassembler
  42
  43 * Based on SPIR-V version 1.1 Rev 3
  44 * Support for extended instruction sets:
  45   * GLSL std450 version 1.0 Rev 3
  46   * OpenCL version 1.0 Rev 2
  47 * Support for SPIR-V 1.0 (with or without additional restrictions from Vulkan 1.0)
  48 * Assembler only does basic syntax checking.  No cross validation of
  49   IDs or types is performed, except to check literal arguments to
  50   `OpConstant`, `OpSpecConstant`, and `OpSwitch`.
  51
  52 See [`syntax.md`](syntax.md) for the assembly language syntax.
  53
  54 ### Validator
  55
  56 *Warning:* The validator is incomplete.
  57
  58 ## Source code
  59
  60 The SPIR-V Tools are maintained by members of the The Khronos Group Inc.,
  61 at https://github.com/KhronosGroup/SPIRV-Tools.
  62
  63 Contributions via merge request are welcome. Changes should:
  64 * Be provided under the [Apache 2.0](#license).
  65   You'll be prompted with a one-time "click-through" Contributor's License
  66   Agreement (CLA) dialog as part of submitting your pull request or
  67   other contribution to GitHub.
  68 * Include tests to cover updated functionality.
  69 * C++ code should follow the [Google C++ Style Guide][cpp-style-guide].
  70 * Code should be formatted with `clang-format`.  Settings are defined by
  71   the included [.clang-format](.clang-format) file.
  72
  73 We intend to maintain a linear history on the GitHub `master` branch.
  74
  75 ### Source code organization
  76
  77 * `external/googletest`: Intended location for the
  78   [googletest][googletest] sources, not provided
  79 * `include/`: API clients should add this directory to the include search path
  80 * `external/spirv-headers`: Intended location for
  81   [SPIR-V headers][spirv-headers], not provided
  82 * `include/spirv-tools/libspirv.h`: C API public interface
  83 * `source/`: API implementation
  84 * `test/`: Tests, using the [googletest][googletest] framework
  85 * `tools/`: Command line executables
  86
  87 ### Tests
  88
  89 The project contains a number of tests, used to drive development
  90 and ensure correctness.  The tests are written using the
  91 [googletest][googletest] framework.  The `googletest`
  92 source is not provided with this project.  There are two ways to enable
  93 tests:
  94 * If SPIR-V Tools is configured as part of an enclosing project, then the
  95   enclosing project should configure `googletest` before configuring SPIR-V Tools.
  96 * If SPIR-V Tools is configured as a standalone project, then download the
  97   `googletest` source into the `<spirv-dir>/external/googletest` directory before
  98   configuring and building the project.
  99
 100 *Note*: You must use a version of googletest that includes
 101 [a fix][googletest-pull-612] for [googletest issue 610][googletest-issue-610].
 102 The fix is included on the googletest master branch any time after 2015-11-10.
 103 In particular, googletest must be newer than version 1.7.0.
 104
 105 ## Build
 106
 107 The project uses [CMake][cmake] to generate platform-specific build
 108 configurations. Assume that `<spirv-dir>` is the root directory of the checked
 109 out code:
 110
 111 ```
 112 cd <spirv-dir>
 113 git clone https://github.com/KhronosGroup/SPIRV-Headers.git external/spirv-headers
 114 git clone https://github.com/google/googletest.git external/googletest # optional
 115
 116 mkdir build && cd build
 117 cmake [-G <platform-generator>] <spirv-dir>
 118 ```
 119
 120 Once the build files have been generated, build using your preferred
 121 development environment.
 122
 123 ### CMake options
 124
 125 The following CMake options are supported:
 126
 127 * `SPIRV_COLOR_TERMINAL={ON|OFF}`, default `ON` - Enables color console output.
 128 * `SPIRV_SKIP_EXECUTABLES={ON|OFF}`, default `OFF`- Build only the library, not
 129   the command line tools.  This will also prevent the tests from being built.
 130 * `SPIRV_USE_SANITIZER=<sanitizer>`, default is no sanitizing - On UNIX
 131   platforms with an appropriate version of `clang` this option enables the use
 132   of the sanitizers documented [here][clang-sanitizers].
 133   This should only be used with a debug build.
 134 * `SPIRV_WARN_EVERYTHING={ON|OFF}`, default `OFF` - On UNIX platforms enable
 135   more strict warnings.  The code might not compile with this option enabled.
 136   For Clang, enables `-Weverything`.  For GCC, enables `-Wpedantic`.
 137   See [`CMakeLists.txt`](CMakeLists.txt) for details.
 138 * `SPIRV_WERROR={ON|OFF}`, default `ON` - Forces a compilation error on any
 139   warnings encountered by enabling the compiler-specific compiler front-end
 140   option.
 141
 142 ## Library
 143
 144 ### Usage
 145
 146 The library provides a C API, but the internals use C++11.
 147
 148 In order to use the library from an application, the include path should point
 149 to `<spirv-dir>/include`, which will enable the application to include the
 150 header `<spirv-dir>/include/spirv-tools/libspirv.h` then linking against the
 151 static library in `<spirv-build-dir>/source/libSPIRV-Tools.a` or
 152 `<spirv-build-dir>/source/SPIRV-Tools.lib`.
 153
 154 * `SPIRV-Tools` CMake target: Creates the static library:
 155   * `<spirv-build-dir>/source/libSPIRV-Tools.a` on Linux and OS X.
 156   * `<spirv-build-dir>/source/libSPIRV-Tools.lib` on Windows.
 157
 158 #### Entry points
 159
 160 The interfaces are still under development, and are expected to change.
 161
 162 There are three main entry points into the library.
 163
 164 * `spvTextToBinary`: An assembler, translating text to a binary SPIR-V module.
 165 * `spvBinaryToText`: A disassembler, translating a binary SPIR-V module to
 166   text.
 167 * `spvBinaryParse`: The entry point to a binary parser API.  It issues callbacks
 168   for the header and each parsed instruction.  The disassembler is implemented
 169   as a client of `spvBinaryParse`.
 170 * `spvValidate` implements the validator functionality. *Incomplete*
 171
 172 ## Command line tools
 173
 174 Command line tools, which wrap the above library functions, are provided to
 175 assemble or disassemble shader files.  It's a convention to name SPIR-V
 176 assembly and binary files with suffix `.spvasm` and `.spv`, respectively.
 177
 178 ### Assembler tool
 179
 180 The assembler reads the assembly language text, and emits the binary form.
 181
 182 The standalone assembler is the exectuable called `spirv-as`, and is located in
 183 `<spirv-build-dir>/tools/spirv-as`.  The functionality of the assembler is implemented
 184 by the `spvTextToBinary` library function.
 185
 186 * `spirv-as` - the standalone assembler
 187   * `<spirv-dir>/tools/as`
 188
 189 Use option `-h` to print help.
 190
 191 ### Disassembler tool
 192
 193 The disassembler reads the binary form, and emits assembly language text.
 194
 195 The standalone disassembler is the executable called `spirv-dis`, and is located in
 196 `<spirv-build-dir>/tools/spirv-dis`. The functionality of the disassembler is implemented
 197 by the `spvBinaryToText` library function.
 198
 199 * `spirv-dis` - the standalone disassembler
 200   * `<spirv-dir>/tools/dis`
 201
 202 Use option `-h` to print help.
 203
 204 The output includes syntax colouring when printing to the standard output stream,
 205 on Linux, Windows, and OS X.
 206
 207 ### Optimizer tool
 208
 209 The optimizer processes a SPIR-V binary module, applying transformations
 210 in the specified order.
 211
 212 This is a work in progress, with initially only few available transformations.
 213
 214 * `spirv-opt` - the standalone optimizer
 215   * `<spirv-dir>/tools/opt`
 216
 217 ### Validator tool
 218
 219 *Warning:* This functionality is under development, and is incomplete.
 220
 221 The standalone validator is the executable called `spirv-val`, and is located in
 222 `<spirv-build-dir>/tools/spirv-val`. The functionality of the validator is implemented
 223 by the `spvValidate` library function.
 224
 225 The validator operates on the binary form.
 226
 227 * `spirv-val` - the standalone validator
 228   * `<spirv-dir>/tools/val`
 229
 230 ### Control flow dumper tool
 231
 232 The control flow dumper prints the control flow graph for a SPIR-V module as a
 233 [GraphViz](http://www.graphviz.org/) graph.
 234
 235 This is experimental.
 236
 237 * `spirv-cfg` - the control flow graph dumper
 238   * `<spirv-dir>/tools/cfg`
 239
 240 ### Utility filters
 241
 242 * `spirv-lesspipe.sh` - Automatically disassembles `.spv` binary files for the
 243   `less` program, on compatible systems.  For example, set the `LESSOPEN`
 244   environment variable as follows, assuming both `spirv-lesspipe.sh` and
 245   `spirv-dis` are on your executable search path:
 246   ```
 247    export LESSOPEN='| spirv-lesspipe.sh "%s"'
 248   ```
 249   Then you page through a disassembled module as follows:
 250   ```
 251   less foo.spv
 252   ```
 253   * The `spirv-lesspipe.sh` script will pass through any extra arguments to
 254     `spirv-dis`.  So, for example, you can turn off colours and friendly ID
 255     naming as follows:
 256     ```
 257     export LESSOPEN='| spirv-lesspipe.sh "%s" --no-color --raw-id'
 258     ```
 259
 260 ### Tests
 261
 262 Tests are only built when googletest is found.
 263
 264 The `<spirv-build-dir>/test/UnitSPIRV` executable runs the project tests.
 265 It supports the standard `googletest` command line options.
 266
 267 The project also adds a CMake test `spirv-tools-testsuite`, which executes
 268 `UnitSPIRV`.  That way it's possible to run the tests using `ctest`.
 269
 270 ## Future Work
 271 <a name="future"></a>
 272
 273 ### Assembler and disassembler
 274
 275 * The disassembler could emit helpful annotations in comments.  For example:
 276   * Use variable name information from debug instructions to annotate
 277     key operations on variables.
 278   * Show control flow information by annotating `OpLabel` instructions with
 279     that basic block's predecessors.
 280 * Error messages could be improved.
 281
 282 ### Validator
 283
 284 This is a work in progress.
 285
 286 ## Licence
 287 <a name="license"></a>
 288 Full license terms are in [LICENSE](LICENSE)
 289 ```
 290 Copyright (c) 2015-2016 The Khronos Group Inc.
 291
 292 Licensed under the Apache License, Version 2.0 (the "License");
 293 you may not use this file except in compliance with the License.
 294 You may obtain a copy of the License at
 295
 296     http://www.apache.org/licenses/LICENSE-2.0
 297
 298 Unless required by applicable law or agreed to in writing, software
 299 distributed under the License is distributed on an "AS IS" BASIS,
 300 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 301 See the License for the specific language governing permissions and
 302 limitations under the License.
 303 ```
 304
 305 [spirv-registry]: https://www.khronos.org/registry/spir-v/
 306 [spirv-headers]: https://github.com/KhronosGroup/SPIRV-Headers
 307 [googletest]: https://github.com/google/googletest
 308 [googletest-pull-612]: https://github.com/google/googletest/pull/612
 309 [googletest-issue-610]: https://github.com/google/googletest/issues/610
 310 [CMake]: https://cmake.org/
 311 [cpp-style-guide]: https://google.github.io/styleguide/cppguide.html
 312 [clang-sanitizers]: http://clang.llvm.org/docs/UsersManual.html#controlling-code-generation