Home | History | Annotate | Download | only in spirv-headers 
      1 # SPIR-V Headers
      2 
      3 This repository contains machine-readable files for the
      4 [SPIR-V Registry](https://www.khronos.org/registry/spir-v/).
      5 This 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 
     13 Headers are provided in the [include](include) directory, with up-to-date
     14 headers in the `unified1` subdirectory. Older headers are provided according to
     15 their version.
     16 
     17 In contrast, the XML registry file has a linear history, so it is
     18 not tied to SPIR-V specification versions.
     19 
     20 ## How is this repository updated?
     21 
     22 When a new version or revision of the SPIR-V specification is published,
     23 the SPIR-V Working Group will push new commits onto master, updating
     24 the files under [include](include).
     25 
     26 The SPIR-V XML registry file is updated by Khronos whenever a new enum range is allocated.
     27 
     28 Pull 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 ```
     35 mkdir build
     36 cd build
     37 cmake ..
     38 cmake --build . --target install
     39 ```
     40 
     41 Then, for example, you will have `/usr/local/include/spirv/unified1/spirv.h`
     42 
     43 If 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 
     48 A CMake-based project can use the headers without installing, as follows:
     49 
     50 1. Add an `add_subdirectory` directive to include this source tree.
     51 2. Use `${SPIRV-Headers_SOURCE_DIR}/include}` in a `target_include_directories`
     52    directive.
     53 3. 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 
     61 See 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 
     66 This will generally be done by Khronos, for a change to the JSON grammar.
     67 However, the project for the tool to do this is included in this repository,
     68 and can be used to test a PR, or even to include the results in the PR.
     69 This is not required though.
     70 
     71 The header-generation project is under the `tools/buildHeaders` directory.
     72 Use CMake to build the project, in a `build` subdirectory (under `tools/buildHeaders`).
     73 There is then a bash script at `bin/makeHeaders` that shows how to use the built
     74 header-generator binary to generate the headers from the JSON grammar.
     75 (Execute `bin/makeHeaders` from the `tools/buildHeaders` directory.)
     76 
     77 Notes:
     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 ```
     99 Copyright (c) 2015-2018 The Khronos Group Inc.
    100 
    101 Permission is hereby granted, free of charge, to any person obtaining a
    102 copy of this software and/or associated documentation files (the
    103 "Materials"), to deal in the Materials without restriction, including
    104 without limitation the rights to use, copy, modify, merge, publish,
    105 distribute, sublicense, and/or sell copies of the Materials, and to
    106 permit persons to whom the Materials are furnished to do so, subject to
    107 the following conditions:
    108 
    109 The above copyright notice and this permission notice shall be included
    110 in all copies or substantial portions of the Materials.
    111 
    112 MODIFICATIONS TO THIS FILE MAY MEAN IT NO LONGER ACCURATELY REFLECTS
    113 KHRONOS STANDARDS. THE UNMODIFIED, NORMATIVE VERSIONS OF KHRONOS
    114 SPECIFICATIONS AND HEADER INFORMATION ARE LOCATED AT
    115    https://www.khronos.org/registry/
    116 
    117 THE MATERIALS ARE PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
    118 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
    119 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
    120 IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
    121 CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
    122 TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
    123 MATERIALS OR THE USE OR OTHER DEALINGS IN THE MATERIALS.
    124 ```
    125