Lines Matching +full:spirv +full:- +full:tools
1 # SPIR-V Tools
5 The SPIR-V Tools project provides an API and commands for processing SPIR-V
9 validator, and optimizer for SPIR-V. Except for the optimizer, all are based
11 details, and is used in the standalone tools whilst also enabling integration
18 SPIR-V is defined by the Khronos Group Inc.
19 See the [SPIR-V Registry][spirv-registry] for the SPIR-V specification,
24 …ranch/master?svg=true)](https://ci.appveyor.com/project/Khronoswebmaster/spirv-tools/branch/master)
25 …://storage.googleapis.com/spirv-tools/badges/build_status_linux_clang_release.svg)](https://storag…
26 …://storage.googleapis.com/spirv-tools/badges/build_status_macos_clang_release.svg)](https://storag…
27 …ps://storage.googleapis.com/spirv-tools/badges/build_status_windows_release.svg)](https://storage.…
31 ## Versioning SPIRV-Tools
35 SPIRV-Tools project version numbers are of the form `v`*year*`.`*index* and with
36 an optional `-dev` suffix to indicate work in progress. For example, the
40 * `v2016.1-dev`
42 * `v2016.2-dev`
45 Use the `--version` option on each command line tool to see the software
46 version. An API call reports the software version as a C-style string.
52 * Support for SPIR-V 1.0, through 1.5
53 * Based on SPIR-V syntax described by JSON grammar files in the
54 [SPIRV-Headers](https://github.com/KhronosGroup/SPIRV-Headers) repository.
55 * Usually, support for a new version of SPIR-V is ready within days after
68 The validator checks validation rules described by the SPIR-V specification.
70 Khronos recommends that tools that create or transform SPIR-V modules use the
71 validator to ensure their outputs are valid, and that tools that consume SPIR-V
75 The validator has one-sided error: it will only return an error when it has
81 sub-project](https://github.com/KhronosGroup/SPIRV-Tools/projects/1) for planned
82 and in-progress work.
84 *Note*: The validator checks some Universal Limits, from section 2.17 of the SPIR-V spec.
86 It is [future work](https://github.com/KhronosGroup/SPIRV-Tools/projects/1#card-1052403)
88 limits accepted by a more than minimally capable SPIR-V consumer.
130 * Convert AMD-specific instructions to KHR instructions
133 * If-conversion
136 * Loop-invariant code motion
143 higher-level recipes. These include:
145 * Optimization for size (`spirv-opt -Os`)
146 * Optimization for performance (`spirv-opt -O`)
149 [`include/spirv-tools/optimizer.hpp`](include/spirv-tools/optimizer.hpp).
151 …efer to this [white paper](https://www.lunarg.com/shader-compiler-technologies/white-paper-spirv-o…
159 * Combine multiple SPIR-V binary modules together.
164 sub-project](https://github.com/KhronosGroup/SPIRV-Tools/projects/2) for
165 planned and in-progress work.
172 The reducer simplifies and shrinks a SPIR-V module with respect to a
173 user-supplied *interestingness function*. For example, given a large
174 SPIR-V module that cause some SPIR-V compiler to fail with a given
180 issue](https://github.com/KhronosGroup/SPIRV-Tools/issues]) with
188 The fuzzer applies semantics-preserving transformations to a SPIR-V binary
191 their results should differ only due to floating-point round-off, if at all.
192 Significant differences in results can pinpoint bugs in tools that process
193 SPIR-V binaries, such as miscompilations. This *metamorphic testing* approach
198 issue](https://github.com/KhronosGroup/SPIRV-Tools/issues]) with
204 * [Utility filters](#utility-filters)
205 * Build target `spirv-tools-vimsyntax` generates file `spvasm.vim`.
206 Copy that file into your `$HOME/.vim/syntax` directory to get SPIR-V assembly syntax
211 The SPIR-V Tools project is maintained by members of the The Khronos Group Inc.,
212 and is hosted at https://github.com/KhronosGroup/SPIRV-Tools.
215 [https://www.khronos.org/spir/spirv-tools-mailing-list/](https://www.khronos.org/spir/spirv-tools-m…
216 The mailing list is used to discuss development plans for the SPIRV-Tools as an open source project.
219 [projects][spirv-tools-projects].
221 (To provide feedback on the SPIR-V _specification_, file an issue on the
222 [SPIRV-Headers][spirv-headers] GitHub repository.)
226 feature](https://help.github.com/articles/tracking-the-progress-of-your-work-with-projects/)
227 to organize planned and in-progress work.
231 * You'll be prompted with a one-time "click-through"
232 [Khronos Open Source Contributor License Agreement][spirv-tools-cla]
236 * C++ code should follow the [Google C++ Style Guide][cpp-style-guide].
237 * Code should be formatted with `clang-format`.
238 [kokoro/check-format/build.sh](kokoro/check-format/build.sh)
240 `clang-format version 5.0.0` for SPIRV-Tools. Settings are defined by
241 the included [.clang-format](.clang-format) file.
247 * `example`: demo code of using SPIRV-Tools APIs
256 * `external/spirv-headers`: Intended location for
257 [SPIR-V headers][spirv-headers], not provided
258 * `include/spirv-tools/libspirv.h`: C API public interface
261 * `tools/`: Command line executables
263 Example of getting sources, assuming SPIRV-Tools is configured as a standalone project:
265 git clone https://github.com/KhronosGroup/SPIRV-Tools.git spirv-tools
266 git clone https://github.com/KhronosGroup/SPIRV-Headers.git spirv-tools/external/spirv-headers
267 git clone https://github.com/google/googletest.git spirv-tools/external/googletest
268 git clone https://github.com/google/effcee.git spirv-tools/external/effcee
269 git clone https://github.com/google/re2.git spirv-tools/external/re2
278 * If SPIR-V Tools is configured as part of an enclosing project, then the
279 enclosing project should configure `googletest` before configuring SPIR-V Tools.
280 * If SPIR-V Tools is configured as a standalone project, then download the
281 `googletest` source into the `<spirv-dir>/external/googletest` directory before
285 [a fix][googletest-pull-612] for [googletest issue 610][googletest-issue-610].
286 The fix is included on the googletest master branch any time after 2015-11-10.
294 * If SPIRV-Tools is configured as part of a larger project that already uses
295 Effcee, then that project should include Effcee before SPIRV-Tools.
296 * Otherwise, SPIRV-Tools expects Effcee sources to appear in `external/effcee`
303 platform directly from the [master-tot release][master-tot-release] on GitHub.
309 that it depends on. Assume that `<spirv-dir>` is the root directory of the
313 cd <spirv-dir>
314 git clone https://github.com/KhronosGroup/SPIRV-Headers.git external/spirv-headers
322 The script `utils/git-sync-deps` can be used to checkout and/or update the
329 cd <spirv-dir>
331 cmake [-G <platform-generator>] <spirv-dir>
340 cmake --build . [--config Debug] # runs `make` or `ninja` or `msbuild` etc.
345 The SPIR-V fuzzer, `spirv-fuzz`, can only be built via CMake, and is disabled by
350 # In <spirv-dir> (the SPIRV-Tools repo root):
351 git clone --depth=1 --branch v3.13.0 https://github.com/protocolbuffers/protobuf external/protobuf
354 cmake [-G <platform-generator>] <spirv-dir> -DSPIRV_BUILD_FUZZER=ON
355 cmake --build . --config Debug
358 You can also add `-DSPIRV_ENABLE_LONG_FUZZER_TESTS=ON` to build additional
365 cd <spirv-dir>
369 ### Tools you'll need
371 For building and testing SPIRV-Tools, the following tools should be
374 - [CMake](http://www.cmake.org/): if using CMake for generating compilation
376 - [Python 3](http://www.python.org/): for utility scripts and running the test
378 - [Bazel](https://bazel.build/) (optional): if building the source with Bazel,
382 SPIRV-Tools is regularly tested with the following compilers:
385 - GCC version 4.8.5
386 - Clang version 3.8
389 - AppleClang 10.0
392 - Visual Studio 2015
393 - Visual Studio 2017
401 * `SPIRV_BUILD_FUZZER={ON|OFF}`, default `OFF` - Build the spirv-fuzz tool.
402 * `SPIRV_COLOR_TERMINAL={ON|OFF}`, default `ON` - Enables color console output.
403 * `SPIRV_SKIP_TESTS={ON|OFF}`, default `OFF`- Build only the library and
404 the command line tools. This will prevent the tests from being built.
405 * `SPIRV_SKIP_EXECUTABLES={ON|OFF}`, default `OFF`- Build only the library, not
406 the command line tools and tests.
407 * `SPIRV_USE_SANITIZER=<sanitizer>`, default is no sanitizing - On UNIX
409 of the sanitizers documented [here][clang-sanitizers].
411 * `SPIRV_WARN_EVERYTHING={ON|OFF}`, default `OFF` - On UNIX platforms enable
413 For Clang, enables `-Weverything`. For GCC, enables `-Wpedantic`.
415 * `SPIRV_WERROR={ON|OFF}`, default `ON` - Forces a compilation error on any
416 warnings encountered by enabling the compiler-specific compiler front-end
417 option. No compiler front-end options are enabled when this option is OFF.
419 Additionally, you can pass additional C preprocessor definitions to SPIRV-Tools
426 SPIR-V Tools supports building static libraries `libSPIRV-Tools.a` and
427 `libSPIRV-Tools-opt.a` for Android:
430 cd <spirv-dir>
438 $ANDROID_NDK/ndk-build -C ../android_test \
459 to `<spirv-dir>/include`, which will enable the application to include the
460 header `<spirv-dir>/include/spirv-tools/libspirv.h{|pp}` then linking against
461 the static library in `<spirv-build-dir>/source/libSPIRV-Tools.a` or
462 `<spirv-build-dir>/source/SPIRV-Tools.lib`.
464 `<spirv-dir>/include/spirv-tools/optimizer.hpp`, and the static library is
465 `<spirv-build-dir>/source/libSPIRV-Tools-opt.a` or
466 `<spirv-build-dir>/source/SPIRV-Tools-opt.lib`.
468 * `SPIRV-Tools` CMake target: Creates the static library:
469 * `<spirv-build-dir>/source/libSPIRV-Tools.a` on Linux and OS X.
470 * `<spirv-build-dir>/source/libSPIRV-Tools.lib` on Windows.
471 * `SPIRV-Tools-opt` CMake target: Creates the static library:
472 * `<spirv-build-dir>/source/libSPIRV-Tools-opt.a` on Linux and OS X.
473 * `<spirv-build-dir>/source/libSPIRV-Tools-opt.lib` on Windows.
481 * `spvTextToBinary`: An assembler, translating text to a binary SPIR-V module.
482 * `spvBinaryToText`: A disassembler, translating a binary SPIR-V module to
496 ## Command line tools
498 Command line tools, which wrap the above library functions, are provided to
499 assemble or disassemble shader files. It's a convention to name SPIR-V
506 The standalone assembler is the executable called `spirv-as`, and is located in
507 `<spirv-build-dir>/tools/spirv-as`. The functionality of the assembler is implemented
510 * `spirv-as` - the standalone assembler
511 * `<spirv-dir>/tools/as`
513 Use option `-h` to print help.
519 The standalone disassembler is the executable called `spirv-dis`, and is located in
520 `<spirv-build-dir>/tools/spirv-dis`. The functionality of the disassembler is implemented
523 * `spirv-dis` - the standalone disassembler
524 * `<spirv-dir>/tools/dis`
526 Use option `-h` to print help.
533 The linker combines multiple SPIR-V binary modules together, resulting in a single
540 * `spirv-link` - the standalone linker
541 * `<spirv-dir>/tools/link`
545 The optimizer processes a SPIR-V binary module, applying transformations
550 * `spirv-opt` - the standalone optimizer
551 * `<spirv-dir>/tools/opt`
557 The standalone validator is the executable called `spirv-val`, and is located in
558 `<spirv-build-dir>/tools/spirv-val`. The functionality of the validator is implemented
563 * `spirv-val` - the standalone validator
564 * `<spirv-dir>/tools/val`
568 The reducer shrinks a SPIR-V binary module, guided by a user-supplied
573 * `spirv-reduce` - the standalone reducer
574 * `<spirv-dir>/tools/reduce`
576 Run `spirv-reduce --help` to see how to specify interestingness.
580 The fuzzer transforms a SPIR-V binary module into a semantically-equivalent
581 SPIR-V binary module by applying transformations in a randomized fashion.
583 This is a work in progress, with initially only a few semantics-preserving
586 * `spirv-fuzz` - the standalone fuzzer
587 * `<spirv-dir>/tools/fuzz`
589 Run `spirv-fuzz --help` for a detailed list of options.
593 The control flow dumper prints the control flow graph for a SPIR-V module as a
598 * `spirv-cfg` - the control flow graph dumper
599 * `<spirv-dir>/tools/cfg`
603 * `spirv-lesspipe.sh` - Automatically disassembles `.spv` binary files for the
605 environment variable as follows, assuming both `spirv-lesspipe.sh` and
606 `spirv-dis` are on your executable search path:
608 export LESSOPEN='| spirv-lesspipe.sh "%s"'
614 * The `spirv-lesspipe.sh` script will pass through any extra arguments to
615 `spirv-dis`. So, for example, you can turn off colours and friendly ID
618 export LESSOPEN='| spirv-lesspipe.sh "%s" --no-color --raw-id'
621 * [vim-spirv](https://github.com/kbenzie/vim-spirv) - A vim plugin which
628 * `50spirv-tools.el` - Automatically disassembles '.spv' binary files when
629 loaded into the emacs text editor, and re-assembles them when saved,
634 cmake -DSPIRV_TOOLS_INSTALL_EMACS_HELPERS=true ...
637 In addition, this helper is only installed if the directory /etc/emacs/site-start.d
641 This may change if the ability is added to spirv-as.
652 _See the [projects pages](https://github.com/KhronosGroup/SPIRV-Tools/projects)
671 math flags passed at linking-time in OpenCL.
680 Copyright (c) 2015-2016 The Khronos Group Inc.
686 http://www.apache.org/licenses/LICENSE-2.0
695 [spirv-tools-cla]: https://cla-assistant.io/KhronosGroup/SPIRV-Tools
696 [spirv-tools-projects]: https://github.com/KhronosGroup/SPIRV-Tools/projects
697 [spirv-tools-mailing-list]: https://www.khronos.org/spir/spirv-tools-mailing-list
698 [spirv-registry]: https://www.khronos.org/registry/spir-v/
699 [spirv-headers]: https://github.com/KhronosGroup/SPIRV-Headers
701 [googletest-pull-612]: https://github.com/google/googletest/pull/612
702 [googletest-issue-610]: https://github.com/google/googletest/issues/610
706 [cpp-style-guide]: https://google.github.io/styleguide/cppguide.html
707 [clang-sanitizers]: http://clang.llvm.org/docs/UsersManual.html#controlling-code-generation
708 [master-tot-release]: https://github.com/KhronosGroup/SPIRV-Tools/releases/tag/master-tot