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
219 The diff tool takes two SPIR-V files, either in binary or text format and
220 produces a diff-style comparison between the two.  The instructions between the
222 (in src id-space) that shows which instructions are removed in src, added in dst
225 Matching instructions between two SPIR-V modules is not trivial, and thus a
228 this tool is primarily useful to produce the diff of two SPIR-V modules derived
230 before and after a transformation, or SPIR-V produced from different tools.
235 * [Utility filters](#utility-filters)
236 * Build target `spirv-tools-vimsyntax` generates file `spvasm.vim`.
237   Copy that file into your `$HOME/.vim/syntax` directory to get SPIR-V assembly syntax
242 The SPIR-V Tools project is maintained by members of the The Khronos Group Inc.,
243 and is hosted at https://github.com/KhronosGroup/SPIRV-Tools.
246 [https://www.khronos.org/spir/spirv-tools-mailing-list/](https://www.khronos.org/spir/spirv-tools-m…
247 The mailing list is used to discuss development plans for the SPIRV-Tools as an open source project.
250 [projects][spirv-tools-projects].
252 (To provide feedback on the SPIR-V _specification_, file an issue on the
253 [SPIRV-Headers][spirv-headers] GitHub repository.)
257 feature](https://help.github.com/articles/tracking-the-progress-of-your-work-with-projects/)
258 to organize planned and in-progress work.
262 * You'll be prompted with a one-time "click-through"
263   [Khronos Open Source Contributor License Agreement][spirv-tools-cla]
267 * C++ code should follow the [Google C++ Style Guide][cpp-style-guide].
268 * Code should be formatted with `clang-format`.
269   [kokoro/check-format/build.sh](kokoro/check-format/build.sh)
271   `clang-format version 5.0.0` for SPIRV-Tools. Settings are defined by
272   the included [.clang-format](.clang-format) file.
278 Example of getting sources, assuming SPIRV-Tools is configured as a standalone project:
280     git clone https://github.com/KhronosGroup/SPIRV-Tools.git   spirv-tools
281     cd spirv-tools
285     python3 utils/git-sync-deps
287 For some kinds of development, you may need the latest sources from the third-party projects:
289     git clone https://github.com/KhronosGroup/SPIRV-Headers.git spirv-tools/external/spirv-headers
290     git clone https://github.com/google/googletest.git          spirv-tools/external/googletest
291     git clone https://github.com/google/effcee.git              spirv-tools/external/effcee
292     git clone https://github.com/google/re2.git                 spirv-tools/external/re2
299 * If SPIRV-Tools is configured as part of a larger project that already uses
300   Effcee, then that project should include Effcee before SPIRV-Tools.
301 * Otherwise, SPIRV-Tools expects Effcee sources to appear in `external/effcee`
306 * `example`: demo code of using SPIRV-Tools APIs
315 * `external/spirv-headers`: Intended location for
316   [SPIR-V headers][spirv-headers], not provided
317 * `include/spirv-tools/libspirv.h`: C API public interface
320 * `tools/`: Command line executables
329 * If SPIR-V Tools is configured as part of an enclosing project, then the
330   enclosing project should configure `googletest` before configuring SPIR-V Tools.
331 * If SPIR-V Tools is configured as a standalone project, then download the
332   `googletest` source into the `<spirv-dir>/external/googletest` directory before
339 First [get the sources](#getting-the-source).
340 Then build using CMake, Bazel, Android ndk-build, or the Emscripten SDK.
346 cd <spirv-dir>
348 cmake [-G <platform-generator>] <spirv-dir>
357 cmake --build . [--config Debug]  # runs `make` or `ninja` or `msbuild` etc.
362 The SPIR-V fuzzer, `spirv-fuzz`, can only be built via CMake, and is disabled by
367 # In <spirv-dir> (the SPIRV-Tools repo root):
368 git clone --depth=1 --branch v3.13.0.1 https://github.com/protocolbuffers/protobuf external/protobuf
371 cmake [-G <platform-generator>] <spirv-dir> -DSPIRV_BUILD_FUZZER=ON
372 cmake --build . --config Debug
375 You can also add `-DSPIRV_ENABLE_LONG_FUZZER_TESTS=ON` to build additional
382 cd <spirv-dir>
387 The SPIRV-Tools core library can be built to a WebAssembly [node.js](https://nodejs.org)
389 assemble and disassemble SPIR-V modules.
395 cd <spirv-dir>
400 written to `<spirv-dir>/out/web`.
410 ### Tools you'll need
412 For building and testing SPIRV-Tools, the following tools should be
415 - [CMake](http://www.cmake.org/): if using CMake for generating compilation
417 - [Python 3](http://www.python.org/): for utility scripts and running the test
419 - [Bazel](https://bazel.build/) (optional): if building the source with Bazel,
422 - [Emscripten SDK](https://emscripten.org) (optional): if building the
425 SPIRV-Tools is regularly tested with the following compilers:
428 - GCC version 9.3
429 - Clang version 10.0
432 - AppleClang 11.0
435 - Visual Studio 2015
436 - Visual Studio 2017
444 * `SPIRV_BUILD_FUZZER={ON|OFF}`, default `OFF` - Build the spirv-fuzz tool.
445 * `SPIRV_COLOR_TERMINAL={ON|OFF}`, default `ON` - Enables color console output.
446 * `SPIRV_SKIP_TESTS={ON|OFF}`, default `OFF`- Build only the library and
447   the command line tools.  This will prevent the tests from being built.
448 * `SPIRV_SKIP_EXECUTABLES={ON|OFF}`, default `OFF`- Build only the library, not
449   the command line tools and tests.
450 * `SPIRV_USE_SANITIZER=<sanitizer>`, default is no sanitizing - On UNIX
452   of the sanitizers documented [here][clang-sanitizers].
454 * `SPIRV_WARN_EVERYTHING={ON|OFF}`, default `OFF` - On UNIX platforms enable
456   For Clang, enables `-Weverything`.  For GCC, enables `-Wpedantic`.
458 * `SPIRV_WERROR={ON|OFF}`, default `ON` - Forces a compilation error on any
459   warnings encountered by enabling the compiler-specific compiler front-end
460   option.  No compiler front-end options are enabled when this option is OFF.
462 Additionally, you can pass additional C preprocessor definitions to SPIRV-Tools
467 ### Android ndk-build
469 SPIR-V Tools supports building static libraries `libSPIRV-Tools.a` and
470 `libSPIRV-Tools-opt.a` for Android:
473 cd <spirv-dir>
481 $ANDROID_NDK/ndk-build -C ../android_test     \
493 [`depot_tools`](https://chromium.googlesource.com/chromium/tools/depot_tools).
503 to `<spirv-dir>/include`, which will enable the application to include the
504 header `<spirv-dir>/include/spirv-tools/libspirv.h{|pp}` then linking against
505 the static library in `<spirv-build-dir>/source/libSPIRV-Tools.a` or
506 `<spirv-build-dir>/source/SPIRV-Tools.lib`.
508 `<spirv-dir>/include/spirv-tools/optimizer.hpp`, and the static library is
509 `<spirv-build-dir>/source/libSPIRV-Tools-opt.a` or
510 `<spirv-build-dir>/source/SPIRV-Tools-opt.lib`.
512 * `SPIRV-Tools` CMake target: Creates the static library:
513   * `<spirv-build-dir>/source/libSPIRV-Tools.a` on Linux and OS X.
514   * `<spirv-build-dir>/source/libSPIRV-Tools.lib` on Windows.
515 * `SPIRV-Tools-opt` CMake target: Creates the static library:
516   * `<spirv-build-dir>/source/libSPIRV-Tools-opt.a` on Linux and OS X.
517   * `<spirv-build-dir>/source/libSPIRV-Tools-opt.lib` on Windows.
525 * `spvTextToBinary`: An assembler, translating text to a binary SPIR-V module.
526 * `spvBinaryToText`: A disassembler, translating a binary SPIR-V module to
540 ## Command line tools
542 Command line tools, which wrap the above library functions, are provided to
543 assemble or disassemble shader files.  It's a convention to name SPIR-V
550 The standalone assembler is the executable called `spirv-as`, and is located in
551 `<spirv-build-dir>/tools/spirv-as`.  The functionality of the assembler is implemented
554 * `spirv-as` - the standalone assembler
555   * `<spirv-dir>/tools/as`
557 Use option `-h` to print help.
563 The standalone disassembler is the executable called `spirv-dis`, and is located in
564 `<spirv-build-dir>/tools/spirv-dis`. The functionality of the disassembler is implemented
567 * `spirv-dis` - the standalone disassembler
568   * `<spirv-dir>/tools/dis`
570 Use option `-h` to print help.
577 The linker combines multiple SPIR-V binary modules together, resulting in a single
584 * `spirv-link` - the standalone linker
585   * `<spirv-dir>/tools/link`
589 The optimizer processes a SPIR-V binary module, applying transformations
594 * `spirv-opt` - the standalone optimizer
595   * `<spirv-dir>/tools/opt`
601 The standalone validator is the executable called `spirv-val`, and is located in
602 `<spirv-build-dir>/tools/spirv-val`. The functionality of the validator is implemented
607 * `spirv-val` - the standalone validator
608   * `<spirv-dir>/tools/val`
612 The reducer shrinks a SPIR-V binary module, guided by a user-supplied
617 * `spirv-reduce` - the standalone reducer
618   * `<spirv-dir>/tools/reduce`
620 Run `spirv-reduce --help` to see how to specify interestingness.
624 The fuzzer transforms a SPIR-V binary module into a semantically-equivalent
625 SPIR-V binary module by applying transformations in a randomized fashion.
627 This is a work in progress, with initially only a few semantics-preserving
630 * `spirv-fuzz` - the standalone fuzzer
631   * `<spirv-dir>/tools/fuzz`
633 Run `spirv-fuzz --help` for a detailed list of options.
637 The control flow dumper prints the control flow graph for a SPIR-V module as a
642 * `spirv-cfg` - the control flow graph dumper
643   * `<spirv-dir>/tools/cfg`
649 The diff tool produces a diff-style comparison between two SPIR-V modules.
651 * `spirv-diff` - the standalone diff tool
652   * `<spirv-dir>`/tools/diff`
656 * `spirv-lesspipe.sh` - Automatically disassembles `.spv` binary files for the
658   environment variable as follows, assuming both `spirv-lesspipe.sh` and
659   `spirv-dis` are on your executable search path:
661    export LESSOPEN='| spirv-lesspipe.sh "%s"'
667   * The `spirv-lesspipe.sh` script will pass through any extra arguments to
668     `spirv-dis`.  So, for example, you can turn off colours and friendly ID
671     export LESSOPEN='| spirv-lesspipe.sh "%s" --no-color --raw-id'
674 * [vim-spirv](https://github.com/kbenzie/vim-spirv) - A vim plugin which
681 * `50spirv-tools.el` - Automatically disassembles '.spv' binary files when
682   loaded into the emacs text editor, and re-assembles them when saved,
687   cmake -DSPIRV_TOOLS_INSTALL_EMACS_HELPERS=true ...
690   In addition, this helper is only installed if the directory /etc/emacs/site-start.d
694   This may change if the ability is added to spirv-as.
703 Use `ctest -j <num threads>` to run all the tests. To run tests using all threads:
705 ctest -j$(nproc)
708 To run a single test target, use `ctest [-j <N>] -R <test regex>`. For example,
709 you can run all `opt` tests with:
711 ctest -R 'spirv-tools-test_opt'
729 _See the [projects pages](https://github.com/KhronosGroup/SPIRV-Tools/projects)
748   math flags passed at linking-time in OpenCL.
757 Copyright (c) 2015-2016 The Khronos Group Inc.
763     http://www.apache.org/licenses/LICENSE-2.0
772 [spirv-tools-cla]: https://cla-assistant.io/KhronosGroup/SPIRV-Tools
773 [spirv-tools-projects]: https://github.com/KhronosGroup/SPIRV-Tools/projects
774 [spirv-tools-mailing-list]: https://www.khronos.org/spir/spirv-tools-mailing-list
775 [spirv-registry]: https://www.khronos.org/registry/spir-v/
776 [spirv-headers]: https://github.com/KhronosGroup/SPIRV-Headers
778 [googletest-pull-612]: https://github.com/google/googletest/pull/612
779 [googletest-issue-610]: https://github.com/google/googletest/issues/610
783 [cpp-style-guide]: https://google.github.io/styleguide/cppguide.html
784 [clang-sanitizers]: http://clang.llvm.org/docs/UsersManual.html#controlling-code-generation