README.adoc
1 = Vulkan^(R)^ API Registry Build Instructions and Notes 2 3 Jon Leech 4 5 * <<intro,Introduction>> 6 * <<files,Files>> 7 * <<targets,Makefile Targets>> 8 * <<linux,Linux Software Dependencies>> 9 * <<windows,Windows Software Dependencies>> 10 * <<history,Revision History>> 11 12 13 [[intro]] 14 == Introduction 15 16 This is the Vulkan XML API Registry. It is used to generate the canonical 17 `vulkan_core.h` and the API Asciidoc include files used by the Vulkan 18 Specification and Reference Pages. 19 20 When changes to the header or the includes are needed, follow this workflow. 21 Normally changes are needed only when defining a new extension or core 22 version of the API. 23 24 * Create a git branch to work in locally 25 * Edit `vk.xml` 26 * `make ; make test` 27 ** This generates headers in `../include/vulkan` including `vulkan_core.h` 28 and a set of platform-dependent headers `vulkan_<platform>.h`. 29 * `(cd .. && make generated)` 30 ** This generates asciidoc includes for the spec. There are many ways to 31 invoke the Makefile in the spec directory; this simple recipe only 32 generates includes for the core Vulkan API without any extensions. 33 * Repeat until the headers and/or includes are correct. 34 * Commit your changes to your local git branch, push to your upstream git 35 server (your personal repository clone of KhronosGroup/Vulkan-Docs on 36 Github, for people outside Khronos; the Khronos member gitlab server, 37 otherwise), and create a pull or merge request against the specification 38 branch (`master`) or other appropriate target. 39 40 For a detailed description of the schema, go to `..` and `make registry`, 41 which generates $(OUTDIR)/registry.html. This includes some examples of how 42 to make simple changes in the API via the XML. 43 44 The generator scripts are written in Python 3, using the `etree` package for 45 processing XML. 46 47 48 [[files]] 49 == Files 50 51 * Makefile - generates headers and extension loader sources from XML (see 52 <<targets,Makefile Targets>> below). 53 * vk.xml - XML API description. 54 * registry.rnc - RelaxNG compact schema for validating XML against the 55 schema. 56 * Python scripts in ../scripts/ which operate on vk.xml. 57 ** ../scripts/genvk.py - Python script to generate vulkan_core.h and other 58 targets. 59 ** ../scripts/reg.py - Python tools to read XML file and convert it into C 60 headers. 61 ** ../scripts/generator.py - output generator base class. 62 ** ../scripts/cgenerator.py - C header output generator. 63 ** ../scripts/docgenerator.py - Asciidoc interface language include 64 generator. 65 ** ../scripts/extensionmetadocgenerator.py - Generator for Asciidoc 66 extension descriptions in spec appendices. 67 ** ../scripts/hostsyncgenerator.py - Asciidoc host sync table generator. 68 ** ../scripts/pygenerator.py - Generates python encoding of the API 69 description. 70 ** ../scripts/validitygenerator.py - Asciidoc validity language generator. 71 * ../include/vulkan/vulkan_core.h - Generated Vulkan non-platform API 72 header. 73 * ../include/vulkan/vulkan_<platform>.h - Generated Vulkan platform API 74 headers. 75 * ../scripts/indexExt.py - generate HTML index of all extensions for 76 inclusion into the Vulkan registry index page. 77 * ../scripts/extDependency.py - generate extension dependencies in Bash 78 and Python form for use when building the specification. 79 80 [[targets]] 81 == Makefile Targets 82 83 * `install` (default target) - regenerate header files in 84 `../include/vulkan`. 85 * `test` - make sure `../include/vulkan/vulkan_core.h` compiles. 86 *Important!* Can also be used to test if platform headers compile by 87 specifying `make TESTDEFS=-DVK_USE_PLATFORM_<PLATFORM>_<AUTHORID> test`. 88 * `validate` - validate `vk.xml` against the schema. Requires installing 89 `jing` (see <<linux,Software Dependencies>> below). Also important! 90 * `clean_dirt` - remove intermediate files. 91 * `clean` - remove generated files. Usually done when preparing to merge 92 to `master` branch via ```make clean ; make install```. 93 94 If you have trouble running the Makefile on your platform, the following 95 steps will build `vulkan_core.h` and test that it compiles: 96 97 [source,sh] 98 ---- 99 # Regenerate header from XML 100 python3 ../scripts/genvk.py -o ../include/vulkan vulkan_core.h 101 # Verify that the resulting header compiles 102 gcc -Wall -c -I../include testcore.c 103 g++ -Wall -c -std=c++98 -I../include testcore.c 104 g++ -Wall -c -std=c++11 -I../include testcore.c 105 ---- 106 107 108 [[linux]] 109 == Linux Software Depencies 110 111 These are the minimum versions of required tools in a Debian 8 development 112 environment. Earlier versions *may* work, but unless they are verified by 113 someone else, there's no way to know that: 114 115 * Python 3 (`python3`, version: 3.4.2) 116 * pass:[g++] and gcc (`g++-4.9` / `gcc-4.9`, version: 4.9.2-10 - gcc 4.8 117 also reported to work) 118 * GNU make (`make` version: 4.0.8-1; older versions probably OK) 119 * Jing (`jing` version: 20131210+dfsg+1-1; needed only for optional XML 120 validation) 121 122 123 [[windows]] 124 == Windows Software Dependencies 125 126 Using the Windows 10 Ubuntu subsystem, if available, is probably the most 127 pleasant way of building. Cygwin64 is also a viable approach. 128 129 On native Windows without a Linux emulation environment, one way to build on 130 Windows is: 131 132 * Install python (32-bit works great): https://www.python.org/downloads/ 133 * Ensure the pip module is installed (should be by default) 134 * Run the `genvk.py` script in C:\PathToVulkan\src\specfile 135 ** ```C:\PathToPython\python3.exe genvk.py vulkan_core.h``` 136 137 138 [[history]] 139 == Revision History 140 141 * 2019/03/10 - 142 Update for script reorganization. 143 * 2018/05/21 - 144 Don't generate vulkan_ext.[ch] from the `install` target. Add a new 145 shortcut `extloader` target for people still using this code and needing 146 to regenerate it. 147 * 2018/03/13 - 148 Update for new directory structure. 149 * 2018/03/06 - 150 Update for Vulkan 1.1 release and `master` branch. 151 * 2015/09/18 - 152 Split platform-specific headers into their own vulkan_<platform>.h 153 files, move vulkan.h to vulkan_core.h, and add a new (static) vulkan.h 154 which includes appropriate combinations of the other headers. 155 * 2015/06/01 - 156 The header that is generated has been improved relative to the first 157 version. Function arguments are indented like the hand-generated header, 158 enumerant BEGIN/END_RANGE enums are named the same, etc. The ordering of 159 declarations is unlike the hand-generated header, and probably always 160 will because it results from a type/enum/function dependency analysis. 161 Some of this can be forced by being more explicit about it, if that is a 162 big deal. 163 * 2015/06/02 - 164 Per WG signoff, converted hex constant values to decimal (for 165 non-bitmasks) and VK_BIT macros to 'bitpos' attributes in the XML and 166 hex constants in the header. Updated schema to match. Changed <ptype> 167 tag to <type>. 168 * 2015/06/03 - 169 Moved into new 'vulkan' tree (did not bother preserving history in 170 previous repo). Added semantic knowledge about structs and unions to 171 <type> tags instead of just imbedding C struct definitions. Improved 172 registry.rnc schema a bit. 173 * 2015/06/07 - 174 Incorporate feedback from F2F including Python 3 and Windows fixes to 175 the scripts. Add documentation to readme.pdf. Fold in multiple merge 176 requests resulting from action items agreed at the F2F, to prepare 177 for everyone moving to XML instead of directly editing the header. 178 * 2015/06/20 - 179 Add vulkan-docs target and instructions for installing python3 and 180 python-lxml for Windows. 181 * 2015/08/13 - 182 Bring documentation up to date with Makefile targets (default is now 183 ../include/vulkan.h). 184 * 2015/09/02 - 185 Update README with required (or known working) versions of toolchain 186 components. 187 * 2015/09/02 - 188 Move include/vulkan.h to vulkan/vulkan.h so #include "vulkan/vulkan.h" 189 is the normal usage (Bug 14576). 190 * 2016/02/12 - 191 Update README and remove old files to stage for public release. 192 * 2016/05/31 - 193 Remove dependency on lxml. 194 * 2016/07/27 - 195 Update documentation for changes to schema and generator scripts. 196 * 2016/08/26 - 197 Move README to an asciidoc file and update for the single-branch model. 198 Use 'clean' target to remove generated files in both spec source and 199 registry Makefiles. 200 * 2017/02/20 - 201 Move registry.txt (schema documentation) to the Vulkan spec source 202 directory and update the README here.