1// Copyright 2014-2022 The Khronos Group Inc. 2// 3// SPDX-License-Identifier: CC-BY-4.0 4 5= Vulkan^(R)^ API Registry Build Instructions and Notes 6 7Jon Leech 8 9 * <<intro,Introduction>> 10 * <<build,Build Environment>> 11 * <<files,Files>> 12 * <<targets,Makefile Targets>> 13 * <<linux,Linux Software Dependencies>> 14 * <<windows,Windows Software Dependencies>> 15 * <<history,Revision History>> 16 17 18[[intro]] 19== Introduction 20 21This is the Vulkan XML API Registry. It is used to generate the canonical 22Vulkan header files, the API Asciidoc include files used by the Vulkan 23Specification and Reference Pages, and many other types of generated files. 24 25When changes to generated files are needed, follow this workflow. 26Normally changes are needed only when defining a new extension or core 27version of the API. 28 29 * Clone the repository and create a branch to work in locally 30 * Edit `vk.xml` 31 * `make validate install test` 32 ** This validates the XML files against the schema description; generates 33 headers in `../gen/include/vulkan` including `vulkan_core.h` and a set 34 of platform-dependent headers `vulkan_<platform>.h`; and runs a simple 35 compilation test of the headers. 36 * `(cd .. && make generated)` 37 ** This uses `vk.xml` to generate asciidoc includes and other intermediate 38 files in `../gen` for the specification build. 39 There are many ways to invoke the Makefile in `..`. 40 This simple recipe only generates includes for the core Vulkan API 41 without any extensions. 42 See `../BUILD.adoc` for more. 43 * Repeat until the headers and/or includes are correct 44 * Commit your changes to your local git branch, push to your upstream git 45 server (your personal repository clone of KhronosGroup/Vulkan-Docs on 46 Github, for people outside Khronos; the Khronos member gitlab server, 47 otherwise), and create a pull or merge request against the default 48 branch (currently `main`) or other appropriate target. 49 50For a detailed description of the schema, go to `..` and `make registry`, 51which generates `gen/out/registry.html`. 52This document also includes some examples of how to make simple changes in 53the API via the XML. 54 55The generator scripts are written in Python 3, using the `etree` package for 56processing XML. 57See `../scripts/README.adoc` for script descriptions. 58 59=== Video Headers 60 61In addition to `vk.xml` this directory also includes `video.xml`. 62This is a similarly structured XML file used to produce headers for 63structures and other types (`StdVideo*`) associated with externally defined 64video standards. 65While these data types are passed into some of the Vulkan Video extension 66APIs, they are not treated as part of the Vulkan API. 67This is why they are defined in a separate XML file. 68 69The `validate` and `install` targets described above also generate the 70`StdVideo*` headers in `../gen/include/vk_video`. 71A separate test target, `vtest`, can be used as a simple compilation test of 72the `StdVideo*` headers. 73 74 75[[build]] 76== Build Environment 77 78We strongly recommend using the Khronos-provided Docker image, which has all 79needed build tools pre-installed. 80See `../BUILD.adoc` for details. 81 82It is possible to construct your own build environment on Linux, Windows, or 83MacOS by following the recipe in the Dockerfile for the Khronos-provided 84Docker image. 85 86 87[[files]] 88== Files 89 90 * `vk.xml` - XML API description. 91 * `registry.rnc` - RelaxNG compact schema for validating XML against the 92 schema. 93 * `Makefile` - generates headers from `vk.xml` (see <<targets,Makefile 94 Targets>> below). 95 * `../gen/include/vulkan/vulkan_core.h` - Generated Vulkan non-platform 96 API header. 97 * `../gen/include/vulkan/vulkan_<platform>.h` - Generated Vulkan platform 98 API headers. 99 * `video.xml` - `StdVideo*` API description. 100 * `../gen/include/vk_video/vulkan_video*.h` - Generated `StdVideo*` API 101 headers. 102 103 104[[targets]] 105== Makefile Targets 106 107 * `install` (default target) - regenerate Vulkan and `StdVideo*` header 108 files in `../gen/include/`. 109 * `test` - make sure Vulkan headers compile. 110 *Important!* Can also be used to test if platform headers compile by 111 specifying `make TESTDEFS=-DVK_USE_PLATFORM_<PLATFORM>_<AUTHORID> test`. 112 * `vtest` - make sure `StdVideo*` headers compile. 113 * `validate` - validate `vk.xml` and `video.xml` against the schema. 114 Requires installing `jing` (see <<linux,Software Dependencies>> below). 115 Also important! 116 * `clean_dirt` - remove intermediate files. 117 * `clean` - remove generated files. 118 119Generated files can be created in a directory other than the default 120`../gen/` by setting the Makefile variable `GENERATED` to that directory 121path. 122 123If you have trouble running the Makefile on your platform, the following 124steps will build the Vulkan headers and test that `vulkan_core.h` compiles: 125 126[source,sh] 127---- 128# Regenerate header from XML 129python3 ../scripts/genvk.py -registry vk.xml -o ../gen/include/vulkan vulkan_core.h 130# Verify that the resulting header compiles 131gcc -Wall -std=c99 -c -I../gen/include -I../tests ../tests/htest.c 132g++ -Wall -std=c++98 -c -I../gen/include -I../tests ../tests/htest.c 133rm -f htest.o 134---- 135 136 137[[history]] 138== Revision History 139 140 * 2021-12-13 - 141 Add `video.xml` for `StdVideo*` APIs and headers. 142 * 2020-08-25 - 143 Update for new default branch (`main`). 144 * 2019/05/12 - 145 Bring up to date with changes in file paths and build tools. 146 * 2019/03/10 - 147 Update for script reorganization. 148 * 2018/05/21 - 149 Do not generate vulkan_ext.[ch] from the `install` target. Add a new 150 shortcut `extloader` target for people still using this code and needing 151 to regenerate it. 152 * 2018/03/13 - 153 Update for new directory structure. 154 * 2018/03/06 - 155 Update for Vulkan 1.1 release and new default branch. 156 * 2015/09/18 - 157 Split platform-specific headers into their own vulkan_<platform>.h 158 files, move vulkan.h to vulkan_core.h, and add a new (static) vulkan.h 159 which includes appropriate combinations of the other headers. 160 * 2015/06/01 - 161 The header that is generated has been improved relative to the first 162 version. Function arguments are indented like the hand-generated header, 163 enumerant BEGIN/END_RANGE enums are named the same, etc. The ordering of 164 declarations is unlike the hand-generated header, and probably always 165 will because it results from a type/enum/function dependency analysis. 166 Some of this can be forced by being more explicit about it, if that is a 167 big deal. 168 * 2015/06/02 - 169 Per WG signoff, converted hex constant values to decimal (for 170 non-bitmasks) and VK_BIT macros to 'bitpos' attributes in the XML and 171 hex constants in the header. Updated schema to match. Changed <ptype> 172 tag to <type>. 173 * 2015/06/03 - 174 Moved into new 'vulkan' tree (did not bother preserving history in 175 previous repo). Added semantic knowledge about structs and unions to 176 <type> tags instead of just imbedding C struct definitions. Improved 177 registry.rnc schema a bit. 178 * 2015/06/07 - 179 Incorporate feedback from F2F including Python 3 and Windows fixes to 180 the scripts. Add documentation to readme.pdf. Fold in multiple merge 181 requests resulting from action items agreed at the F2F, to prepare 182 for everyone moving to XML instead of directly editing the header. 183 * 2015/06/20 - 184 Add vulkan-docs target and instructions for installing python3 and 185 python-lxml for Windows. 186 * 2015/08/13 - 187 Bring documentation up to date with Makefile targets (default is now 188 ../include/vulkan.h). 189 * 2015/09/02 - 190 Update README with required (or known working) versions of toolchain 191 components. 192 * 2015/09/02 - 193 Move include/vulkan.h to vulkan/vulkan.h so #include "vulkan/vulkan.h" 194 is the normal usage (Bug 14576). 195 * 2016/02/12 - 196 Update README and remove old files to stage for public release. 197 * 2016/05/31 - 198 Remove dependency on lxml. 199 * 2016/07/27 - 200 Update documentation for changes to schema and generator scripts. 201 * 2016/08/26 - 202 Move README to an asciidoc file and update for the single-branch model. 203 Use 'clean' target to remove generated files in both spec source and 204 registry Makefiles. 205 * 2017/02/20 - 206 Move registry.txt (schema documentation) to the Vulkan spec source 207 directory and update the README here. 208