README.md
1# SPIR-V Tools
2
3## Overview
4
5The SPIR-V Tools project provides an API and commands for processing SPIR-V
6modules.
7
8The project includes an assembler, binary module parser, disassembler,
9validator, and optimizer for SPIR-V. Except for the optimizer, all are based
10on a common static library. The library contains all of the implementation
11details, and is used in the standalone tools whilst also enabling integration
12into other code bases directly. The optimizer implementation resides in its
13own library, which depends on the core library.
14
15The interfaces have stabilized:
16We don't anticipate making a breaking change for existing features.
17
18SPIR-V is defined by the Khronos Group Inc.
19See the [SPIR-V Registry][spirv-registry] for the SPIR-V specification,
20headers, and XML registry.
21
22## Downloads
23
24[](https://ci.appveyor.com/project/Khronoswebmaster/spirv-tools/branch/master)
25<img alt="Linux" src="kokoro/img/linux.png" width="20px" height="20px" hspace="2px"/>[](https://storage.googleapis.com/spirv-tools/badges/build_link_linux_clang_release.html)
26<img alt="MacOS" src="kokoro/img/macos.png" width="20px" height="20px" hspace="2px"/>[](https://storage.googleapis.com/spirv-tools/badges/build_link_macos_clang_release.html)
27<img alt="Windows" src="kokoro/img/windows.png" width="20px" height="20px" hspace="2px"/>[](https://storage.googleapis.com/spirv-tools/badges/build_link_windows_vs2017_release.html)
28
29[More downloads](docs/downloads.md)
30
31## Versioning SPIRV-Tools
32
33See [`CHANGES`](CHANGES) for a high level summary of recent changes, by version.
34
35SPIRV-Tools project version numbers are of the form `v`*year*`.`*index* and with
36an optional `-dev` suffix to indicate work in progress. For example, the
37following versions are ordered from oldest to newest:
38
39* `v2016.0`
40* `v2016.1-dev`
41* `v2016.1`
42* `v2016.2-dev`
43* `v2016.2`
44
45Use the `--version` option on each command line tool to see the software
46version. An API call reports the software version as a C-style string.
47
48## Supported features
49
50### Assembler, binary parser, and disassembler
51
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
56 publication.
57* Support for extended instruction sets:
58 * GLSL std450 version 1.0 Rev 3
59 * OpenCL version 1.0 Rev 2
60* Assembler only does basic syntax checking. No cross validation of
61 IDs or types is performed, except to check literal arguments to
62 `OpConstant`, `OpSpecConstant`, and `OpSwitch`.
63
64See [`docs/syntax.md`](docs/syntax.md) for the assembly language syntax.
65
66### Validator
67
68The validator checks validation rules described by the SPIR-V specification.
69
70Khronos recommends that tools that create or transform SPIR-V modules use the
71validator to ensure their outputs are valid, and that tools that consume SPIR-V
72modules optionally use the validator to protect themselves from bad inputs.
73This is especially encouraged for debug and development scenarios.
74
75The validator has one-sided error: it will only return an error when it has
76implemented a rule check and the module violates that rule.
77
78The validator is incomplete.
79See the [CHANGES](CHANGES) file for reports on completed work, and
80the [Validator
81sub-project](https://github.com/KhronosGroup/SPIRV-Tools/projects/1) for planned
82and in-progress work.
83
84*Note*: The validator checks some Universal Limits, from section 2.17 of the SPIR-V spec.
85The validator will fail on a module that exceeds those minimum upper bound limits.
86It is [future work](https://github.com/KhronosGroup/SPIRV-Tools/projects/1#card-1052403)
87to parameterize the validator to allow larger
88limits accepted by a more than minimally capable SPIR-V consumer.
89
90
91### Optimizer
92
93The optimizer is a collection of code transforms, or "passes".
94Transforms are written for a diverse set of reasons:
95
96* To restructure, simplify, or normalize the code for further processing.
97* To eliminate undesirable code.
98* To improve code quality in some metric such as size or performance.
99 **Note**: These transforms are not guaranteed to actually improve any
100 given metric. Users should always measure results for their own situation.
101
102As of this writing, there are 67 transforms including examples such as:
103* Simplification
104 * Strip debug info
105 * Strip reflection info
106* Specialization Constants
107 * Set spec constant default value
108 * Freeze spec constant to default value
109 * Fold `OpSpecConstantOp` and `OpSpecConstantComposite`
110 * Unify constants
111 * Eliminate dead constant
112* Code Reduction
113 * Inline all function calls exhaustively
114 * Convert local access chains to inserts/extracts
115 * Eliminate local load/store in single block
116 * Eliminate local load/store with single store
117 * Eliminate local load/store with multiple stores
118 * Eliminate local extract from insert
119 * Eliminate dead instructions (aggressive)
120 * Eliminate dead branches
121 * Merge single successor / single predecessor block pairs
122 * Eliminate common uniform loads
123 * Remove duplicates: Capabilities, extended instruction imports, types, and
124 decorations.
125* Normalization
126 * Compact IDs
127 * CFG cleanup
128 * Flatten decorations
129 * Merge returns
130 * Convert AMD-specific instructions to KHR instructions
131* Code improvement
132 * Conditional constant propagation
133 * If-conversion
134 * Loop fission
135 * Loop fusion
136 * Loop-invariant code motion
137 * Loop unroll
138* Other
139 * Graphics robust access
140 * Upgrade memory model to VulkanKHR
141
142Additionally, certain sets of transformations have been packaged into
143higher-level recipes. These include:
144
145* Optimization for size (`spirv-opt -Os`)
146* Optimization for performance (`spirv-opt -O`)
147
148For the latest list with detailed documentation, please refer to
149[`include/spirv-tools/optimizer.hpp`](include/spirv-tools/optimizer.hpp).
150
151For suggestions on using the code reduction options, please refer to this [white paper](https://www.lunarg.com/shader-compiler-technologies/white-paper-spirv-opt/).
152
153
154### Linker
155
156*Note:* The linker is still under development.
157
158Current features:
159* Combine multiple SPIR-V binary modules together.
160* Combine into a library (exports are retained) or an executable (no symbols
161 are exported).
162
163See the [CHANGES](CHANGES) file for reports on completed work, and the [General
164sub-project](https://github.com/KhronosGroup/SPIRV-Tools/projects/2) for
165planned and in-progress work.
166
167
168### Reducer
169
170*Note:* The reducer is still under development.
171
172The reducer simplifies and shrinks a SPIR-V module with respect to a
173user-supplied *interestingness function*. For example, given a large
174SPIR-V module that cause some SPIR-V compiler to fail with a given
175fatal error message, the reducer could be used to look for a smaller
176version of the module that causes the compiler to fail with the same
177fatal error message.
178
179To suggest an additional capability for the reducer, [file an
180issue](https://github.com/KhronosGroup/SPIRV-Tools/issues]) with
181"Reducer:" as the start of its title.
182
183
184### Fuzzer
185
186*Note:* The fuzzer is still under development.
187
188The fuzzer applies semantics-preserving transformations to a SPIR-V binary
189module, to produce an equivalent module. The original and transformed modules
190should produce essentially identical results when executed on identical inputs:
191their results should differ only due to floating-point round-off, if at all.
192Significant differences in results can pinpoint bugs in tools that process
193SPIR-V binaries, such as miscompilations. This *metamorphic testing* approach
194is similar to the method used by the [GraphicsFuzz
195project](https://github.com/google/graphicsfuzz) for fuzzing of GLSL shaders.
196
197To suggest an additional capability for the fuzzer, [file an
198issue](https://github.com/KhronosGroup/SPIRV-Tools/issues]) with
199"Fuzzer:" as the start of its title.
200
201
202### Extras
203
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
207 highlighting in Vim. This build target is not built by default.
208
209## Contributing
210
211The SPIR-V Tools project is maintained by members of the The Khronos Group Inc.,
212and is hosted at https://github.com/KhronosGroup/SPIRV-Tools.
213
214Consider joining the `public_spirv_tools_dev@khronos.org` mailing list, via
215[https://www.khronos.org/spir/spirv-tools-mailing-list/](https://www.khronos.org/spir/spirv-tools-mailing-list/).
216The mailing list is used to discuss development plans for the SPIRV-Tools as an open source project.
217Once discussion is resolved,
218specific work is tracked via issues and sometimes in one of the
219[projects][spirv-tools-projects].
220
221(To provide feedback on the SPIR-V _specification_, file an issue on the
222[SPIRV-Headers][spirv-headers] GitHub repository.)
223
224See [`docs/projects.md`](docs/projects.md) to see how we use the
225[GitHub Project
226feature](https://help.github.com/articles/tracking-the-progress-of-your-work-with-projects/)
227to organize planned and in-progress work.
228
229Contributions via merge request are welcome. Changes should:
230* Be provided under the [Apache 2.0](#license).
231* You'll be prompted with a one-time "click-through"
232 [Khronos Open Source Contributor License Agreement][spirv-tools-cla]
233 (CLA) dialog as part of submitting your pull request or
234 other contribution to GitHub.
235* Include tests to cover updated functionality.
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)
239 shows how to download it. Note that we currently use
240 `clang-format version 5.0.0` for SPIRV-Tools. Settings are defined by
241 the included [.clang-format](.clang-format) file.
242
243We intend to maintain a linear history on the GitHub `master` branch.
244
245### Source code organization
246
247* `example`: demo code of using SPIRV-Tools APIs
248* `external/googletest`: Intended location for the
249 [googletest][googletest] sources, not provided
250* `external/effcee`: Location of [Effcee][effcee] sources, if the `effcee` library
251 is not already configured by an enclosing project.
252* `external/re2`: Location of [RE2][re2] sources, if the `re2` library is not already
253 configured by an enclosing project.
254 (The Effcee project already requires RE2.)
255* `include/`: API clients should add this directory to the include search path
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
259* `source/`: API implementation
260* `test/`: Tests, using the [googletest][googletest] framework
261* `tools/`: Command line executables
262
263Example of getting sources, assuming SPIRV-Tools is configured as a standalone project:
264
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
270
271### Tests
272
273The project contains a number of tests, used to drive development
274and ensure correctness. The tests are written using the
275[googletest][googletest] framework. The `googletest`
276source is not provided with this project. There are two ways to enable
277tests:
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
282 configuring and building the project.
283
284*Note*: You must use a version of googletest that includes
285[a fix][googletest-pull-612] for [googletest issue 610][googletest-issue-610].
286The fix is included on the googletest master branch any time after 2015-11-10.
287In particular, googletest must be newer than version 1.7.0.
288
289### Dependency on Effcee
290
291Some tests depend on the [Effcee][effcee] library for stateful matching.
292Effcee itself depends on [RE2][re2].
293
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`
297 and RE2 sources to appear in `external/re2`.
298
299
300## Build
301
302Instead of building manually, you can also download the binaries for your
303platform directly from the [master-tot release][master-tot-release] on GitHub.
304Those binaries are automatically uploaded by the buildbots after successful
305testing and they always reflect the current top of the tree of the master
306branch.
307
308In order to build the code, you first need to sync the external repositories
309that it depends on. Assume that `<spirv-dir>` is the root directory of the
310checked out code:
311
312```sh
313cd <spirv-dir>
314git clone https://github.com/KhronosGroup/SPIRV-Headers.git external/spirv-headers
315git clone https://github.com/google/effcee.git external/effcee
316git clone https://github.com/google/re2.git external/re2
317git clone https://github.com/google/googletest.git external/googletest # optional
318
319```
320
321*Note*:
322The script `utils/git-sync-deps` can be used to checkout and/or update the
323contents of the repos under `external/` instead of manually maintaining them.
324
325### Build using CMake
326You can build the project using [CMake][cmake]:
327
328```sh
329cd <spirv-dir>
330mkdir build && cd build
331cmake [-G <platform-generator>] <spirv-dir>
332```
333
334Once the build files have been generated, build using the appropriate build
335command (e.g. `ninja`, `make`, `msbuild`, etc.; this depends on the platform
336generator used above), or use your IDE, or use CMake to run the appropriate build
337command for you:
338
339```sh
340cmake --build . [--config Debug] # runs `make` or `ninja` or `msbuild` etc.
341```
342
343#### Note about the fuzzer
344
345The SPIR-V fuzzer, `spirv-fuzz`, can only be built via CMake, and is disabled by
346default. To build it, clone protobuf and use the `SPIRV_BUILD_FUZZER` CMake
347option, like so:
348
349```sh
350# In <spirv-dir> (the SPIRV-Tools repo root):
351git clone --depth=1 --branch v3.13.0 https://github.com/protocolbuffers/protobuf external/protobuf
352
353# In your build directory:
354cmake [-G <platform-generator>] <spirv-dir> -DSPIRV_BUILD_FUZZER=ON
355cmake --build . --config Debug
356```
357
358You can also add `-DSPIRV_ENABLE_LONG_FUZZER_TESTS=ON` to build additional
359fuzzer tests.
360
361
362### Build using Bazel
363You can also use [Bazel](https://bazel.build/) to build the project.
364```sh
365cd <spirv-dir>
366bazel build :all
367```
368
369### Tools you'll need
370
371For building and testing SPIRV-Tools, the following tools should be
372installed regardless of your OS:
373
374- [CMake](http://www.cmake.org/): if using CMake for generating compilation
375targets, you need to install CMake Version 2.8.12 or later.
376- [Python 3](http://www.python.org/): for utility scripts and running the test
377suite.
378- [Bazel](https://bazel.build/) (optional): if building the source with Bazel,
379you need to install Bazel Version 0.29.1 on your machine. Other versions may
380also work, but are not verified.
381
382SPIRV-Tools is regularly tested with the following compilers:
383
384On Linux
385- GCC version 4.8.5
386- Clang version 3.8
387
388On MacOS
389- AppleClang 10.0
390
391On Windows
392- Visual Studio 2015
393- Visual Studio 2017
394
395Other compilers or later versions may work, but they are not tested.
396
397### CMake options
398
399The following CMake options are supported:
400
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
408 platforms with an appropriate version of `clang` this option enables the use
409 of the sanitizers documented [here][clang-sanitizers].
410 This should only be used with a debug build.
411* `SPIRV_WARN_EVERYTHING={ON|OFF}`, default `OFF` - On UNIX platforms enable
412 more strict warnings. The code might not compile with this option enabled.
413 For Clang, enables `-Weverything`. For GCC, enables `-Wpedantic`.
414 See [`CMakeLists.txt`](CMakeLists.txt) for details.
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.
418
419Additionally, you can pass additional C preprocessor definitions to SPIRV-Tools
420via setting `SPIRV_TOOLS_EXTRA_DEFINITIONS`. For example, by setting it to
421`/D_ITERATOR_DEBUG_LEVEL=0` on Windows, you can disable checked iterators and
422iterator debugging.
423
424### Android
425
426SPIR-V Tools supports building static libraries `libSPIRV-Tools.a` and
427`libSPIRV-Tools-opt.a` for Android:
428
429```
430cd <spirv-dir>
431
432export ANDROID_NDK=/path/to/your/ndk
433
434mkdir build && cd build
435mkdir libs
436mkdir app
437
438$ANDROID_NDK/ndk-build -C ../android_test \
439 NDK_PROJECT_PATH=. \
440 NDK_LIBS_OUT=`pwd`/libs \
441 NDK_APP_OUT=`pwd`/app
442```
443
444### Updating DEPS
445Occasionally the entries in DEPS will need to be updated. This is done on demand
446when there is a request to do this, often due to downstream breakages. There is
447a script `utils/roll_deps.sh` provided, which will generate a patch with the
448updated DEPS values. This will still need to be tested in your checkout to
449confirm that there are no integration issues that need to be resolved.
450
451## Library
452
453### Usage
454
455The internals of the library use C++11 features, and are exposed via both a C
456and C++ API.
457
458In order to use the library from an application, the include path should point
459to `<spirv-dir>/include`, which will enable the application to include the
460header `<spirv-dir>/include/spirv-tools/libspirv.h{|pp}` then linking against
461the static library in `<spirv-build-dir>/source/libSPIRV-Tools.a` or
462`<spirv-build-dir>/source/SPIRV-Tools.lib`.
463For optimization, the header file is
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`.
467
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.
474
475#### Entry points
476
477The interfaces are still under development, and are expected to change.
478
479There are five main entry points into the library in the C interface:
480
481* `spvTextToBinary`: An assembler, translating text to a binary SPIR-V module.
482* `spvBinaryToText`: A disassembler, translating a binary SPIR-V module to
483 text.
484* `spvBinaryParse`: The entry point to a binary parser API. It issues callbacks
485 for the header and each parsed instruction. The disassembler is implemented
486 as a client of `spvBinaryParse`.
487* `spvValidate` implements the validator functionality. *Incomplete*
488* `spvValidateBinary` implements the validator functionality. *Incomplete*
489
490The C++ interface is comprised of three classes, `SpirvTools`, `Optimizer` and
491`Linker`, all in the `spvtools` namespace.
492* `SpirvTools` provides `Assemble`, `Disassemble`, and `Validate` methods.
493* `Optimizer` provides methods for registering and running optimization passes.
494* `Linker` provides methods for combining together multiple binaries.
495
496## Command line tools
497
498Command line tools, which wrap the above library functions, are provided to
499assemble or disassemble shader files. It's a convention to name SPIR-V
500assembly and binary files with suffix `.spvasm` and `.spv`, respectively.
501
502### Assembler tool
503
504The assembler reads the assembly language text, and emits the binary form.
505
506The 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
508by the `spvTextToBinary` library function.
509
510* `spirv-as` - the standalone assembler
511 * `<spirv-dir>/tools/as`
512
513Use option `-h` to print help.
514
515### Disassembler tool
516
517The disassembler reads the binary form, and emits assembly language text.
518
519The 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
521by the `spvBinaryToText` library function.
522
523* `spirv-dis` - the standalone disassembler
524 * `<spirv-dir>/tools/dis`
525
526Use option `-h` to print help.
527
528The output includes syntax colouring when printing to the standard output stream,
529on Linux, Windows, and OS X.
530
531### Linker tool
532
533The linker combines multiple SPIR-V binary modules together, resulting in a single
534binary module as output.
535
536This is a work in progress.
537The linker does not support OpenCL program linking options related to math
538flags. (See section 5.6.5.2 in OpenCL 1.2)
539
540* `spirv-link` - the standalone linker
541 * `<spirv-dir>/tools/link`
542
543### Optimizer tool
544
545The optimizer processes a SPIR-V binary module, applying transformations
546in the specified order.
547
548This is a work in progress, with initially only few available transformations.
549
550* `spirv-opt` - the standalone optimizer
551 * `<spirv-dir>/tools/opt`
552
553### Validator tool
554
555*Warning:* This functionality is under development, and is incomplete.
556
557The 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
559by the `spvValidate` library function.
560
561The validator operates on the binary form.
562
563* `spirv-val` - the standalone validator
564 * `<spirv-dir>/tools/val`
565
566### Reducer tool
567
568The reducer shrinks a SPIR-V binary module, guided by a user-supplied
569*interestingness test*.
570
571This is a work in progress, with initially only shrinks a module in a few ways.
572
573* `spirv-reduce` - the standalone reducer
574 * `<spirv-dir>/tools/reduce`
575
576Run `spirv-reduce --help` to see how to specify interestingness.
577
578### Fuzzer tool
579
580The fuzzer transforms a SPIR-V binary module into a semantically-equivalent
581SPIR-V binary module by applying transformations in a randomized fashion.
582
583This is a work in progress, with initially only a few semantics-preserving
584transformations.
585
586* `spirv-fuzz` - the standalone fuzzer
587 * `<spirv-dir>/tools/fuzz`
588
589Run `spirv-fuzz --help` for a detailed list of options.
590
591### Control flow dumper tool
592
593The control flow dumper prints the control flow graph for a SPIR-V module as a
594[GraphViz](http://www.graphviz.org/) graph.
595
596This is experimental.
597
598* `spirv-cfg` - the control flow graph dumper
599 * `<spirv-dir>/tools/cfg`
600
601### Utility filters
602
603* `spirv-lesspipe.sh` - Automatically disassembles `.spv` binary files for the
604 `less` program, on compatible systems. For example, set the `LESSOPEN`
605 environment variable as follows, assuming both `spirv-lesspipe.sh` and
606 `spirv-dis` are on your executable search path:
607 ```
608 export LESSOPEN='| spirv-lesspipe.sh "%s"'
609 ```
610 Then you page through a disassembled module as follows:
611 ```
612 less foo.spv
613 ```
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
616 naming as follows:
617 ```
618 export LESSOPEN='| spirv-lesspipe.sh "%s" --no-color --raw-id'
619 ```
620
621* [vim-spirv](https://github.com/kbenzie/vim-spirv) - A vim plugin which
622 supports automatic disassembly of `.spv` files using the `:edit` command and
623 assembly using the `:write` command. The plugin also provides additional
624 features which include; syntax highlighting; highlighting of all ID's matching
625 the ID under the cursor; and highlighting errors where the `Instruction`
626 operand of `OpExtInst` is used without an appropriate `OpExtInstImport`.
627
628* `50spirv-tools.el` - Automatically disassembles '.spv' binary files when
629 loaded into the emacs text editor, and re-assembles them when saved,
630 provided any modifications to the file are valid. This functionality
631 must be explicitly requested by defining the symbol
632 SPIRV_TOOLS_INSTALL_EMACS_HELPERS as follows:
633 ```
634 cmake -DSPIRV_TOOLS_INSTALL_EMACS_HELPERS=true ...
635 ```
636
637 In addition, this helper is only installed if the directory /etc/emacs/site-start.d
638 exists, which is typically true if emacs is installed on the system.
639
640 Note that symbol IDs are not currently preserved through a load/edit/save operation.
641 This may change if the ability is added to spirv-as.
642
643
644### Tests
645
646Tests are only built when googletest is found. Use `ctest` to run all the
647tests.
648
649## Future Work
650<a name="future"></a>
651
652_See the [projects pages](https://github.com/KhronosGroup/SPIRV-Tools/projects)
653for more information._
654
655### Assembler and disassembler
656
657* The disassembler could emit helpful annotations in comments. For example:
658 * Use variable name information from debug instructions to annotate
659 key operations on variables.
660 * Show control flow information by annotating `OpLabel` instructions with
661 that basic block's predecessors.
662* Error messages could be improved.
663
664### Validator
665
666This is a work in progress.
667
668### Linker
669
670* The linker could accept math transformations such as allowing MADs, or other
671 math flags passed at linking-time in OpenCL.
672* Linkage attributes can not be applied through a group.
673* Check decorations of linked functions attributes.
674* Remove dead instructions, such as OpName targeting imported symbols.
675
676## Licence
677<a name="license"></a>
678Full license terms are in [LICENSE](LICENSE)
679```
680Copyright (c) 2015-2016 The Khronos Group Inc.
681
682Licensed under the Apache License, Version 2.0 (the "License");
683you may not use this file except in compliance with the License.
684You may obtain a copy of the License at
685
686 http://www.apache.org/licenses/LICENSE-2.0
687
688Unless required by applicable law or agreed to in writing, software
689distributed under the License is distributed on an "AS IS" BASIS,
690WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
691See the License for the specific language governing permissions and
692limitations under the License.
693```
694
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
700[googletest]: https://github.com/google/googletest
701[googletest-pull-612]: https://github.com/google/googletest/pull/612
702[googletest-issue-610]: https://github.com/google/googletest/issues/610
703[effcee]: https://github.com/google/effcee
704[re2]: https://github.com/google/re2
705[CMake]: https://cmake.org/
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
709
){kind=link}
){kind=link}
){kind=link}