1# SPIR-V Headers 2 3This repository contains machine-readable files for the 4[SPIR-V Registry](https://www.khronos.org/registry/spir-v/). 5This includes: 6 7* Header files for various languages. 8* JSON files describing the grammar for the SPIR-V core instruction set 9 and the extended instruction sets. 10* The XML registry file. 11* A tool to build the headers from the JSON grammar. 12 13Headers are provided in the [include](include) directory, with up-to-date 14headers in the `unified1` subdirectory. Older headers are provided according to 15their version. 16 17In contrast, the XML registry file has a linear history, so it is 18not tied to SPIR-V specification versions. 19 20## How is this repository updated? 21 22When a new version or revision of the SPIR-V specification is published, 23the SPIR-V Working Group will push new commits onto master, updating 24the files under [include](include). 25 26The SPIR-V XML registry file is updated by Khronos whenever a new enum range is allocated. 27 28Pull requests can be made to 29- request allocation of new enum ranges in the XML registry file 30- reserve specific tokens in the JSON grammar 31 32## How to install the headers 33 34``` 35mkdir build 36cd build 37cmake .. 38cmake --build . --target install 39``` 40 41Then, for example, you will have `/usr/local/include/spirv/unified1/spirv.h` 42 43If you want to install them somewhere else, then use 44`-DCMAKE_INSTALL_PREFIX=/other/path` on the first `cmake` command. 45 46## Using the headers without installing 47 48A CMake-based project can use the headers without installing, as follows: 49 501. Add an `add_subdirectory` directive to include this source tree. 512. Use `${SPIRV-Headers_SOURCE_DIR}/include}` in a `target_include_directories` 52 directive. 533. In your C or C++ source code use `#include` directives that explicitly mention 54 the `spirv` path component. 55``` 56#include "spirv/unified1/GLSL.std.450.h" 57#include "spirv/unified1/OpenCL.std.h" 58#include "spirv/unified1/spirv.hpp" 59``` 60 61See also the [example](example/) subdirectory. But since that example is 62*inside* this repostory, it doesn't use and `add_subdirectory` directive. 63 64## Generating the headers from the JSON grammar 65 66This will generally be done by Khronos, for a change to the JSON grammar. 67However, the project for the tool to do this is included in this repository, 68and can be used to test a PR, or even to include the results in the PR. 69This is not required though. 70 71The header-generation project is under the `tools/buildHeaders` directory. 72Use CMake to build the project, in a `build` subdirectory (under `tools/buildHeaders`). 73There is then a bash script at `bin/makeHeaders` that shows how to use the built 74header-generator binary to generate the headers from the JSON grammar. 75(Execute `bin/makeHeaders` from the `tools/buildHeaders` directory.) 76 77Notes: 78- this generator is used in a broader context within Khronos to generate the specification, 79 and that influences the languages used, for legacy reasons 80- the C++ structures built may similarly include more than strictly necessary, for the same reason 81 82## FAQ 83 84* *How are different versions published?* 85 86 The multiple versions of the headers have been simplified into a 87 single `unified1` view. The JSON grammar has a "version" field saying 88 what version things first showed up in. 89 90* *How do you handle the evolution of extended instruction sets?* 91 92 Extended instruction sets evolve asynchronously from the core spec. 93 Right now there is only a single version of both the GLSL and OpenCL 94 headers. So we don't yet have a problematic example to resolve. 95 96## License 97<a name="license"></a> 98``` 99Copyright (c) 2015-2018 The Khronos Group Inc. 100 101Permission is hereby granted, free of charge, to any person obtaining a 102copy of this software and/or associated documentation files (the 103"Materials"), to deal in the Materials without restriction, including 104without limitation the rights to use, copy, modify, merge, publish, 105distribute, sublicense, and/or sell copies of the Materials, and to 106permit persons to whom the Materials are furnished to do so, subject to 107the following conditions: 108 109The above copyright notice and this permission notice shall be included 110in all copies or substantial portions of the Materials. 111 112MODIFICATIONS TO THIS FILE MAY MEAN IT NO LONGER ACCURATELY REFLECTS 113KHRONOS STANDARDS. THE UNMODIFIED, NORMATIVE VERSIONS OF KHRONOS 114SPECIFICATIONS AND HEADER INFORMATION ARE LOCATED AT 115 https://www.khronos.org/registry/ 116 117THE MATERIALS ARE PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 118EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 119MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. 120IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY 121CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, 122TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE 123MATERIALS OR THE USE OR OTHER DEALINGS IN THE MATERIALS. 124``` 125