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