Lines Matching +full:libspirv +full:- +full:tools +full:- +full:opt
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 …/storage.googleapis.com/spirv-tools/badges/build_status_linux_clang_release.svg)](https://storage.…
25 …/storage.googleapis.com/spirv-tools/badges/build_status_macos_clang_release.svg)](https://storage.…
26 …://storage.googleapis.com/spirv-tools/badges/build_status_windows_release.svg)](https://storage.go…
30 ## Versioning SPIRV-Tools
34 SPIRV-Tools project version numbers are of the form `v`*year*`.`*index* and with
35 an optional `-dev` suffix to indicate work in progress. For example, the
39 * `v2016.1-dev`
41 * `v2016.2-dev`
44 Use the `--version` option on each command line tool to see the software
45 version. An API call reports the software version as a C-style string.
49 Some versions of SPIRV-Tools are tagged as stable releases (see
50 [tags](https://github.com/KhronosGroup/SPIRV-Tools/tags) on github).
53 [SPIRV-Headers][spirv-headers].
54 Releases of SPIRV-Tools are tested against the version of SPIRV-Headers listed
56 The release generally uses the most recent compatible version of SPIRV-Headers
58 No version of SPIRV-Headers other than the one listed in the DEPS file is
59 guaranteed to work with the SPIRV-Tools release.
65 * Support for SPIR-V 1.0, through 1.5
66 * Based on SPIR-V syntax described by JSON grammar files in the
67 [SPIRV-Headers](https://github.com/KhronosGroup/SPIRV-Headers) repository.
68 * Usually, support for a new version of SPIR-V is ready within days after
81 The validator checks validation rules described by the SPIR-V specification.
83 Khronos recommends that tools that create or transform SPIR-V modules use the
84 validator to ensure their outputs are valid, and that tools that consume SPIR-V
88 The validator has one-sided error: it will only return an error when it has
94 sub-project](https://github.com/KhronosGroup/SPIRV-Tools/projects/1) for planned
95 and in-progress work.
97 *Note*: The validator checks some Universal Limits, from section 2.17 of the SPIR-V spec.
99 It is [future work](https://github.com/KhronosGroup/SPIRV-Tools/projects/1#card-1052403)
101 limits accepted by a more than minimally capable SPIR-V consumer.
143 * Convert AMD-specific instructions to KHR instructions
146 * If-conversion
149 * Loop-invariant code motion
156 higher-level recipes. These include:
158 * Optimization for size (`spirv-opt -Os`)
159 * Optimization for performance (`spirv-opt -O`)
162 [`include/spirv-tools/optimizer.hpp`](include/spirv-tools/optimizer.hpp).
164 …er to this [white paper](https://www.lunarg.com/shader-compiler-technologies/white-paper-spirv-opt…
172 * Combine multiple SPIR-V binary modules together.
177 sub-project](https://github.com/KhronosGroup/SPIRV-Tools/projects/2) for
178 planned and in-progress work.
185 The reducer simplifies and shrinks a SPIR-V module with respect to a
186 user-supplied *interestingness function*. For example, given a large
187 SPIR-V module that cause some SPIR-V compiler to fail with a given
193 issue](https://github.com/KhronosGroup/SPIRV-Tools/issues]) with
201 The fuzzer applies semantics-preserving transformations to a SPIR-V binary
204 their results should differ only due to floating-point round-off, if at all.
205 Significant differences in results can pinpoint bugs in tools that process
206 SPIR-V binaries, such as miscompilations. This *metamorphic testing* approach
211 issue](https://github.com/KhronosGroup/SPIRV-Tools/issues]) with
217 * [Utility filters](#utility-filters)
218 * Build target `spirv-tools-vimsyntax` generates file `spvasm.vim`.
219 Copy that file into your `$HOME/.vim/syntax` directory to get SPIR-V assembly syntax
224 The SPIR-V Tools project is maintained by members of the The Khronos Group Inc.,
225 and is hosted at https://github.com/KhronosGroup/SPIRV-Tools.
228 [https://www.khronos.org/spir/spirv-tools-mailing-list/](https://www.khronos.org/spir/spirv-tools-m…
229 The mailing list is used to discuss development plans for the SPIRV-Tools as an open source project.
232 [projects][spirv-tools-projects].
234 (To provide feedback on the SPIR-V _specification_, file an issue on the
235 [SPIRV-Headers][spirv-headers] GitHub repository.)
239 feature](https://help.github.com/articles/tracking-the-progress-of-your-work-with-projects/)
240 to organize planned and in-progress work.
244 * You'll be prompted with a one-time "click-through"
245 [Khronos Open Source Contributor License Agreement][spirv-tools-cla]
249 * C++ code should follow the [Google C++ Style Guide][cpp-style-guide].
250 * Code should be formatted with `clang-format`.
251 [kokoro/check-format/build.sh](kokoro/check-format/build.sh)
253 `clang-format version 5.0.0` for SPIRV-Tools. Settings are defined by
254 the included [.clang-format](.clang-format) file.
260 Example of getting sources, assuming SPIRV-Tools is configured as a standalone project:
262 git clone https://github.com/KhronosGroup/SPIRV-Tools.git spirv-tools
263 cd spirv-tools
267 python3 utils/git-sync-deps
269 For some kinds of development, you may need the latest sources from the third-party projects:
271 git clone https://github.com/KhronosGroup/SPIRV-Headers.git spirv-tools/external/spirv-headers
272 git clone https://github.com/google/googletest.git spirv-tools/external/googletest
273 git clone https://github.com/google/effcee.git spirv-tools/external/effcee
274 git clone https://github.com/google/re2.git spirv-tools/external/re2
281 * If SPIRV-Tools is configured as part of a larger project that already uses
282 Effcee, then that project should include Effcee before SPIRV-Tools.
283 * Otherwise, SPIRV-Tools expects Effcee sources to appear in `external/effcee`
288 * `example`: demo code of using SPIRV-Tools APIs
297 * `external/spirv-headers`: Intended location for
298 [SPIR-V headers][spirv-headers], not provided
299 * `include/spirv-tools/libspirv.h`: C API public interface
302 * `tools/`: Command line executables
311 * If SPIR-V Tools is configured as part of an enclosing project, then the
312 enclosing project should configure `googletest` before configuring SPIR-V Tools.
313 * If SPIR-V Tools is configured as a standalone project, then download the
314 `googletest` source into the `<spirv-dir>/external/googletest` directory before
321 First [get the sources](#getting-the-source).
322 Then build using CMake, Bazel, Android ndk-build, or the Emscripten SDK.
328 cd <spirv-dir>
330 cmake [-G <platform-generator>] <spirv-dir>
339 cmake --build . [--config Debug] # runs `make` or `ninja` or `msbuild` etc.
344 The SPIR-V fuzzer, `spirv-fuzz`, can only be built via CMake, and is disabled by
349 # In <spirv-dir> (the SPIRV-Tools repo root):
350 git clone --depth=1 --branch v3.13.0.1 https://github.com/protocolbuffers/protobuf external/protobuf
353 cmake [-G <platform-generator>] <spirv-dir> -DSPIRV_BUILD_FUZZER=ON
354 cmake --build . --config Debug
357 You can also add `-DSPIRV_ENABLE_LONG_FUZZER_TESTS=ON` to build additional
364 cd <spirv-dir>
369 The SPIRV-Tools core library can be built to a WebAssembly [node.js](https://nodejs.org)
371 assemble and disassemble SPIR-V modules.
377 cd <spirv-dir>
382 written to `<spirv-dir>/out/web`.
392 ### Tools you'll need
394 For building and testing SPIRV-Tools, the following tools should be
397 - [CMake](http://www.cmake.org/): if using CMake for generating compilation
399 - [Python 3](http://www.python.org/): for utility scripts and running the test
401 - [Bazel](https://bazel.build/) (optional): if building the source with Bazel,
404 - [Emscripten SDK](https://emscripten.org) (optional): if building the
407 SPIRV-Tools is regularly tested with the following compilers:
410 - GCC version 9.3
411 - Clang version 10.0
414 - AppleClang 11.0
417 - Visual Studio 2015
418 - Visual Studio 2017
426 * `SPIRV_BUILD_FUZZER={ON|OFF}`, default `OFF` - Build the spirv-fuzz tool.
427 * `SPIRV_COLOR_TERMINAL={ON|OFF}`, default `ON` - Enables color console output.
428 * `SPIRV_SKIP_TESTS={ON|OFF}`, default `OFF`- Build only the library and
429 the command line tools. This will prevent the tests from being built.
430 * `SPIRV_SKIP_EXECUTABLES={ON|OFF}`, default `OFF`- Build only the library, not
431 the command line tools and tests.
432 * `SPIRV_USE_SANITIZER=<sanitizer>`, default is no sanitizing - On UNIX
434 of the sanitizers documented [here][clang-sanitizers].
436 * `SPIRV_WARN_EVERYTHING={ON|OFF}`, default `OFF` - On UNIX platforms enable
438 For Clang, enables `-Weverything`. For GCC, enables `-Wpedantic`.
440 * `SPIRV_WERROR={ON|OFF}`, default `ON` - Forces a compilation error on any
441 warnings encountered by enabling the compiler-specific compiler front-end
442 option. No compiler front-end options are enabled when this option is OFF.
444 Additionally, you can pass additional C preprocessor definitions to SPIRV-Tools
449 ### Android ndk-build
451 SPIR-V Tools supports building static libraries `libSPIRV-Tools.a` and
452 `libSPIRV-Tools-opt.a` for Android:
455 cd <spirv-dir>
463 $ANDROID_NDK/ndk-build -C ../android_test \
475 [`depot_tools`](https://chromium.googlesource.com/chromium/tools/depot_tools).
485 to `<spirv-dir>/include`, which will enable the application to include the
486 header `<spirv-dir>/include/spirv-tools/libspirv.h{|pp}` then linking against
487 the static library in `<spirv-build-dir>/source/libSPIRV-Tools.a` or
488 `<spirv-build-dir>/source/SPIRV-Tools.lib`.
490 `<spirv-dir>/include/spirv-tools/optimizer.hpp`, and the static library is
491 `<spirv-build-dir>/source/libSPIRV-Tools-opt.a` or
492 `<spirv-build-dir>/source/SPIRV-Tools-opt.lib`.
494 * `SPIRV-Tools` CMake target: Creates the static library:
495 * `<spirv-build-dir>/source/libSPIRV-Tools.a` on Linux and OS X.
496 * `<spirv-build-dir>/source/libSPIRV-Tools.lib` on Windows.
497 * `SPIRV-Tools-opt` CMake target: Creates the static library:
498 * `<spirv-build-dir>/source/libSPIRV-Tools-opt.a` on Linux and OS X.
499 * `<spirv-build-dir>/source/libSPIRV-Tools-opt.lib` on Windows.
507 * `spvTextToBinary`: An assembler, translating text to a binary SPIR-V module.
508 * `spvBinaryToText`: A disassembler, translating a binary SPIR-V module to
522 ## Command line tools
524 Command line tools, which wrap the above library functions, are provided to
525 assemble or disassemble shader files. It's a convention to name SPIR-V
532 The standalone assembler is the executable called `spirv-as`, and is located in
533 `<spirv-build-dir>/tools/spirv-as`. The functionality of the assembler is implemented
536 * `spirv-as` - the standalone assembler
537 * `<spirv-dir>/tools/as`
539 Use option `-h` to print help.
545 The standalone disassembler is the executable called `spirv-dis`, and is located in
546 `<spirv-build-dir>/tools/spirv-dis`. The functionality of the disassembler is implemented
549 * `spirv-dis` - the standalone disassembler
550 * `<spirv-dir>/tools/dis`
552 Use option `-h` to print help.
559 The linker combines multiple SPIR-V binary modules together, resulting in a single
566 * `spirv-link` - the standalone linker
567 * `<spirv-dir>/tools/link`
571 The optimizer processes a SPIR-V binary module, applying transformations
576 * `spirv-opt` - the standalone optimizer
577 * `<spirv-dir>/tools/opt`
583 The standalone validator is the executable called `spirv-val`, and is located in
584 `<spirv-build-dir>/tools/spirv-val`. The functionality of the validator is implemented
589 * `spirv-val` - the standalone validator
590 * `<spirv-dir>/tools/val`
594 The reducer shrinks a SPIR-V binary module, guided by a user-supplied
599 * `spirv-reduce` - the standalone reducer
600 * `<spirv-dir>/tools/reduce`
602 Run `spirv-reduce --help` to see how to specify interestingness.
606 The fuzzer transforms a SPIR-V binary module into a semantically-equivalent
607 SPIR-V binary module by applying transformations in a randomized fashion.
609 This is a work in progress, with initially only a few semantics-preserving
612 * `spirv-fuzz` - the standalone fuzzer
613 * `<spirv-dir>/tools/fuzz`
615 Run `spirv-fuzz --help` for a detailed list of options.
619 The control flow dumper prints the control flow graph for a SPIR-V module as a
624 * `spirv-cfg` - the control flow graph dumper
625 * `<spirv-dir>/tools/cfg`
629 * `spirv-lesspipe.sh` - Automatically disassembles `.spv` binary files for the
631 environment variable as follows, assuming both `spirv-lesspipe.sh` and
632 `spirv-dis` are on your executable search path:
634 export LESSOPEN='| spirv-lesspipe.sh "%s"'
640 * The `spirv-lesspipe.sh` script will pass through any extra arguments to
641 `spirv-dis`. So, for example, you can turn off colours and friendly ID
644 export LESSOPEN='| spirv-lesspipe.sh "%s" --no-color --raw-id'
647 * [vim-spirv](https://github.com/kbenzie/vim-spirv) - A vim plugin which
654 * `50spirv-tools.el` - Automatically disassembles '.spv' binary files when
655 loaded into the emacs text editor, and re-assembles them when saved,
660 cmake -DSPIRV_TOOLS_INSTALL_EMACS_HELPERS=true ...
663 In addition, this helper is only installed if the directory /etc/emacs/site-start.d
667 This may change if the ability is added to spirv-as.
676 Use `ctest -j <num threads>` to run all the tests. To run tests using all threads:
678 ctest -j$(nproc)
681 To run a single test target, use `ctest [-j <N>] -R <test regex>`. For example,
682 you can run all `opt` tests with:
684 ctest -R 'spirv-tools-test_opt'
702 _See the [projects pages](https://github.com/KhronosGroup/SPIRV-Tools/projects)
721 math flags passed at linking-time in OpenCL.
730 Copyright (c) 2015-2016 The Khronos Group Inc.
736 http://www.apache.org/licenses/LICENSE-2.0
745 [spirv-tools-cla]: https://cla-assistant.io/KhronosGroup/SPIRV-Tools
746 [spirv-tools-projects]: https://github.com/KhronosGroup/SPIRV-Tools/projects
747 [spirv-tools-mailing-list]: https://www.khronos.org/spir/spirv-tools-mailing-list
748 [spirv-registry]: https://www.khronos.org/registry/spir-v/
749 [spirv-headers]: https://github.com/KhronosGroup/SPIRV-Headers
751 [googletest-pull-612]: https://github.com/google/googletest/pull/612
752 [googletest-issue-610]: https://github.com/google/googletest/issues/610
756 [cpp-style-guide]: https://google.github.io/styleguide/cppguide.html
757 [clang-sanitizers]: http://clang.llvm.org/docs/UsersManual.html#controlling-code-generation