• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1// Copyright 2014-2023 The Khronos Group Inc.
2// SPDX-License-Identifier: CC-BY-4.0
3
4= Vulkan^(R)^ Specification Build Instructions and Notes
5:toc2:
6:toclevels: 2
7
8ifdef::env-github[]
9:note-caption: :information_source:
10endif::[]
11
12
13[[intro]]
14== Introduction
15
16This README describes how to build the Vulkan API specification, reference
17pages, and/or other related targets.
18
19It documents how to set up your build environment, build steps and targets,
20and contains some troubleshooting advice.
21
22
23[[building]]
24== Building the Spec
25
26First, clone the Khronos GitHub repository containing the Vulkan
27specification to your local Linux, Windows, or Mac PC.
28The repository is located at https://github.com/KhronosGroup/Vulkan-Docs/.
29
30Next, install all the necessary build tools (see <<depends,Software
31Dependencies>> below).
32If you are using the <<depends-docker, Khronos-Provided Docker Image>>,
33which we strongly recommend, one way to build using the image (assuming a
34Linux docker host) is:
35
36    $ scripts/runDocker
37
38executed from the specification repository root.
39
40`runDocker` runs the Docker image with the cloned repository mounted under
41/vulkan and accesses it as a specified user (set to your own user and group
42ID), so that it does not get filled with files owned by another user.
43The script leaves you inside a bash shell in the running image.
44Execute the commands:
45
46    $ cd /vulkan
47    $ ./makeSpec -spec core html
48
49to build an HTML5 specification output for the core Vulkan 1.3
50specification, with no extensions included, or
51
52    $ cd /vulkan
53    $ ./makeSpec -spec all all
54
55to build the spec targets `html`, `pdf`, `styleguide`, `registry`,
56`manhtmlpages`, and `allchecks`, with *all* registered extensions included.
57
58There are many other ways of using the image, including inside a Continuous
59Integration pipeline; locally with persistent Docker volume storage of the
60repository; and so on.
61
62If you are not using our Docker image to build with, and you have a
63<<depends-nondocker, Non-Docker Build Environment>> with the entire
64toolchain installed, you can just invoke the same `make` commands from the
65repository root.
66
67[NOTE]
68.Note
69====
70You can modify the `runDocker` script to change the `docker` command-line
71options, but it is important to always use the Docker image specified in
72that script, so you have the latest version of the spec toolchain.
73====
74
75[NOTE]
76.Note
77====
78  * While it is possible to invoke `make` directly, this is rarely
79    appropriate or useful.
80    Usually dozens to hundreds of build options must be set to specify the
81    desired set of extensions to include in the specification.
82    The `makeSpec` python script, which is discussed in more detail
83    <<building-extensions, below>>, simplifies this process for common
84    cases.
85  * The `all` target takes a long time to run, and generates outputs that
86    are irrelevant for most users.
87    The `html` target just generates the HTML output, which is often all
88    that is needed for spec bugfixes not involving extensions.
89  * The default `make` options build a Vulkan 1.3 specification with no
90    optional extensions.
91  * The `validusage` target is not built as part of the `all` target, due to
92    it needing to be built with all extensions enabled (`-spec all`).
93    Building the `validusage` target will fail otherwise.
94====
95
96These targets generate a variety of output documents in the directory
97specified by the Makefile variable `$(OUTDIR)` (by default, `out/`).
98The checked-in file `out/index.html` links to all these
99targets, or they can individually be found as follows:
100
101Vulkan Specification::
102  * `html` -- Single-file HTML5 in `$(OUTDIR)/html/vkspec.html`, and KaTeX
103    dependency in $(OUTDIR)/katex
104  * `chunked` -- Chunked HTML5 in `$(OUTDIR)/html/chap?.html`
105  * `pdf` -- PDF in `$(OUTDIR)/pdf/vkspec.pdf`
106"`styleguide`" (Vulkan Documentation and Extensions: Procedures and Conventions)::
107  * `styleguide` -- Single-file HTML5 in `$(OUTDIR)/styleguide.html`
108XML Registry schema document::
109  * `registry` -- Single-file HTML5 in `$(OUTDIR)/registry.html`
110<<building-diff,Diff spec>>::
111  * `diff_html` -- Single-file HTML5 in `$(OUTDIR)/html/diff.html`
112<<refpages,Reference pages>>::
113  * `manhtmlpages` -- File-per-entry-point HTML in `$(OUTDIR)/man/html/*`.
114    Must be built with all extensions enabled (using `makeSpec -spec all`).
115<<validation-scripts,Validator output>>::
116  * None at present. The `allchecks` target writes to standard output unless
117    the underlying script is given additional options.
118Valid usage database::
119  * `validusage` - json database of all valid usage statements in the
120     specification. Must be built with `./makeAllExts` (for now).
121     Output in `$(OUTDIR)/validation/validusage.json`.
122     A validated schema for the output of this is stored in
123     `$(CURDIR)/config/vu-to-json/vu_schema.json`
124
125Once you have the basic build working, an appropriate parallelization
126option, such as `-j 8`, should significantly speed up the reference page
127builds.
128
129If you encounter problems refer to the <<troubleshooting>> section.
130
131
132[[building-versions]]
133=== Building Specifications for Different API Versions
134
135The `Makefile` defaults to building a Vulkan 1.3 specification.
136This is controlled by Asciidoctor attributes passed in the Makefile variable
137`$(VERSIONS)`
138To instead build a Vulkan 1.1 specification, pass
139
140----
141VERSIONS="VK_VERSION_1_0 VK_VERSION_1_1"
142----
143
144on the `makeSpec` command line.
145
146
147[[building-vulkansc]]
148=== Building the Vulkan SC Specification
149
150To build the Vulkan SC 1.0 specification, it is necessary both specify the
151API type via the `VULKAN_API` environment variable and specify the `sc1.0`
152version to the `makeSpec` command.
153
154To build the html spec for Vulkan SC API:
155
156----
157VULKAN_API="vulkansc" ./makeAllExts -version sc1.0 html
158----
159
160To build the Vulkan SC header files:
161
162----
163cd xml
164VULKAN_API="vulkansc" make
165----
166
167Valid values for the `VULKAN_API` environment are:
168
169  * `vulkan` - build the Vulkan API variant.
170  * `vulkansc` - build the Vulkan SC API variant.
171
172If `VULKAN_API` is not set, the repository default is used.
173
174[[building-extensions]]
175=== Building With Extensions Included
176
177Extensions are defined in the same source as the core Specification, but
178are only conditionally included in the output.
179https://asciidoctor.org/docs/user-manual/#attributes[Asciidoctor attributes]
180of the same name as the extension are used to define whether the extension
181is included or not -- defining such an attribute will cause the output to
182include the text for that extension.
183
184When building the specification, the extensions included are those specified
185as a space-separated list of extension names (e.g. `VK_KHR_surface`) in the
186Makefile variable `$(EXTENSIONS)`, usually set on the make command line.
187When changing the list of extensions, it is critical to remove all generated
188files using the `clean_generated` Makefile target, as the contents of
189generated files depends on `$(EXTENSIONS)`.
190
191The `makeSpec` wrapper script can clean generated files and then build one
192or more specification targets for a set of explicitly specified extensions,
193including all implicit extension dependencies of that set.
194It accepts these options:
195
196  * -clean - remove generated targets before building
197  * -v - print actions as well as executing them
198  * -n - print actions without executing them
199  * -genpath *path* - specify path to generated files (default `gen`)
200  * -spec *type* - build with specified sets of extensions.
201    *type* may be
202  ** *core* - no extensions added (default if not specified)
203  ** *khr* - all KHR extensions added
204  ** *ratified* - all ratified extensions (KHR and some EXT) added
205  ** *all* - all registered extensions added
206  * -extension *extname* - build with specified extension included,
207    as well as the set specified by `-spec`.
208    Can be given multiple times.
209  * All remaining targets are arbitrary `make` options or
210    targets in the Makefile.
211
212The `target(s)` passed to these scripts are arbitrary `make` options, and
213can be used to set Makefile variables and options discussed above, as well
214as specify actual build targets.
215For example, to build the HTML specification with all KHR extensions
216included as well as a single vendor extension:
217
218----
219$ ./makeSpec -clean -spec khr -extension VK_EXT_debug_report html
220----
221
222The scripts `makeAllExts`, `makeKHR`, and `makeExt` set appropriate options
223and invoke `makeSpec`, for backwards compatibility, but are no longer used
224by Khronos.
225
226The Makefile variable `$(APITITLE)` defines an additional string which is
227appended to the specification title.
228When building with extensions enabled, this should be set to something like
229`(with extension VK_extension_name)`.
230The `makeSpec` script already does this.
231
232The reference pages (the `manhtmlpages` target) must be built using the
233`-spec all` option; there are markup and scripting issues which will
234probably cause any more restricted set of refpages to fail to build.
235
236
237[[building-diff]]
238==== Building a Highlighted Extension Diff
239
240The `diff_html` target in the Makefile can be used to generate a version of
241the specification which highlights changes made to the specification by the
242inclusion of a particular set of extensions.
243
244Extensions in the Makefile variable `$(EXTENSIONS)` define the base
245extensions to be enabled by the specification, and these will not be
246highlighted in the output.
247Extensions in the Makefile variable `$(DIFFEXTENSIONS)` define the set of
248extensions whose changes to the text will be highlighted when they are
249enabled.
250Any extensions in both variables will be treated as if they were only
251included in `$(DIFFEXTENSIONS)`.
252`$(DIFFEXTENSIONS)` can be set when using the `makeSpec` script described
253above.
254
255In the resulting HTML document, content that has been added by one of the
256extensions will be highlighted with a lime background, and content that was
257removed will be highlighted with a pink background.
258Each section has an anchor of `#differenceN`, with an arrow (=>) at the end
259of each section which links to the next difference section.
260The first diff section is `#difference1`.
261
262[NOTE]
263.Note
264====
265This output is not without errors.
266It may instead result in visible `+++[.added]##content##+++` and
267`+++[.removed]##content##+++`, and so also highlights not being rendered.
268But such visible markup still correctly encapsulates the modified content.
269====
270
271
272[[building-test]]
273=== Alternate and Test Builds
274
275If you are just testing Asciidoctor formatting, macros, stylesheets, etc.,
276you may want to edit `vkspec.adoc` to just include your test code.
277The asciidoctor HTML build is very fast, even for the whole Specification,
278but PDF builds take several minutes.
279
280
281=== Images Used in the Specification
282
283All images used in the specification are in the `images/` directory in the
284SVG format, and were created with Inkscape.
285We recommend using Inkscape to modify or create new images, due to problems
286using SVG files created by some other tools; especially in the PDF builds.
287
288
289[[validation-scripts]]
290=== Validation Scripts
291
292The `allchecks` Makefile target runs a Python script that looks for markup
293errors, missing interfaces, macro misuse, and inconsistencies in the
294specification text.
295This script is necessarily heuristic, since it is dealing with lots of
296hand-written material, but it identifies many problems and can suggest
297solutions.
298This script is also run as part of the CI tests in the internal Khronos
299gitlab repository.
300
301
302[[macros]]
303== Our Asciidoctor Macros
304
305We use many custom Ruby macros in the reference pages and API spec
306Asciidoctor sources.
307The validator scripts rely on these macros as part of their checks.
308and you should use the macros whenever referring to an API command, struct,
309token, or enum name, so the documents are semantically tagged and more
310easily verifiable.
311
312The supported macros are defined in the `config/spec-macros/extension.rb`
313asciidoctor extension script.
314
315The tags used are described in the
316link:https://registry.khronos.org/vulkan/specs/1.1/styleguide.html[style
317guide] (generated from `styleguide.adoc`).
318
319We (may) eventually tool up the spec and reference pages to the point that
320anywhere there is a type or token referred to, clicking on (or perhaps
321hovering over) it in the HTML view will take reader to the definition of
322that type/token.
323That will take some more plumbing work to tag the stuff in the autogenerated
324include files, and do something sensible in the spec (e.g. resolve links to
325internal references).
326
327Most of these macros deeply need more intuitive names.
328
329
330[[refpages]]
331== Reference Pages
332
333The reference pages are extracted from the API Specification source, which
334has been tagged to help identify boundaries of language talking about
335different commands, structures, enumerants, and other types.
336A set of Python scripts extract and lightly massage the relevant tagged
337language into corresponding reference page sources.
338
339To regenerate the reference page sources from scratch yourself, execute:
340
341----
342./makeSpec -spec all refpages
343----
344
345The `genRef.py` script will generate many warnings, but most are just
346reminders that some pages are automatically generated.
347If everything is working correctly, all the `$(GENERATED)/refpage/*.adoc`
348files will be regenerated, but their contents will not change.
349
350If you add new API features to the Specification in a branch, make sure that
351the commands have the required tagging and that reference pages are
352generated for them, and build properly.
353
354When executing the `manhtmlpages` target in the Makefile, after building
355HTML versions of all reference pages extracted from the spec, symbolic links
356from aliases to the reference page for the API they alias will also be
357created.
358
359
360[[styles]]
361== Our Stylesheets
362
363We use an HTML stylesheet `config/khronos.css` derived from the
364https://asciidoctor.org/docs/produce-custom-themes-using-asciidoctor-stylesheet-factory/[Asciidoctor
365stylesheet factory] "`colony`" theme, with the default Arial font family
366replaced by the sans-serif https://en.wikipedia.org/wiki/Noto_fonts[Noto
367font family].
368
369
370[[styleguide]]
371== Vulkan Style Guide
372
373If you are writing new spec language or modifying existing language, see the
374link:https://registry.khronos.org/vulkan/specs/1.3/styleguide.html["`style
375guide`"] (formally titled "`Vulkan Documentation and Extensions: Procedures
376and Conventions`") document for details of our asciidoctor macros,
377extensions, mathematical equation markup, writing style, etc.
378
379
380[[depends]]
381== Software Dependencies
382
383This section describes the software components used by the Vulkan spec
384toolchain.
385
386In the past, we previously specified package versions and instructions for
387installing the toolchain in multiple desktop environments including Linux,
388MacOS X, and Microsoft Windows.
389The underlying components evolve rapidly, and we have not kept those
390instructions up to date.
391
392
393[[depends-docker]]
394=== Khronos-Provided Docker Image
395
396Khronos has published a Docker image containing a Debian Linux distribution
397with the entire toolchain preinstalled.
398
399We will occasionally update this image if needed, and we recommend people
400needing to build from this repository use the Docker image.
401
402Docker installation is beyond the scope of this document.
403Refer to link:https://docs.docker.com/get-docker/[the Docker website] for
404information about installing Docker on Linux, Windows, and MacOS X.
405
406The build image is *named* `khronosgroup/docker-images:asciidoctor-spec`.
407However, due to local and CI caching problems when this image is updated on
408dockerhub, we use the SHA256 of the latest image update, rather than the
409image name. The SHA256 can be determined from
410
411    $ git grep -h sha256: .gitlab-ci.yml
412
413which will print a line like
414
415    image: khronosgroup/docker-images@sha256:42123ba13792c4e809d037b69152c2230ad97fbf43b677338075ab9c928ab6ed
416
417Everything following `image: ` is the <imagename> to use. The first time you
418try to run Docker with this <imagename>, as is done by the `runDocker`
419script described above under <<building, Building the Spec>>, the image will
420be pulled from Dockerhub and cached locally on your machine.
421
422This image is used to build Specification output documents or other Makefile
423targets.
424
425[NOTE]
426.Note
427====
428When we update the image on Dockerhub, it is to add new components or update
429versions of components used in the specification toolchain.
430To save space, you may want to periodically purge old images using `docker
431images` and `docker rmi -f`.
432====
433
434
435[[depends-nondocker]]
436=== Non-Docker Build Environments
437
438We do not actively support building outside of our Docker image, but it is
439straightforward to reproduce our toolchain in a Debian (or similar APT-based
440Linux) distribution by executing the same steps as the
441link:https://github.com/KhronosGroup/DockerContainers/blob/main/asciidoctor-spec.Dockerfile[Dockerfile]
442used to build our Docker image.
443
444It should be possible to apply the same steps in a Windows Subsystem for
445Linux (WSL2) environment on Windows 10, as well.
446
447For other native environments, such as MacOS X and older Unix-like
448environments for Windows such as MinGW and Cygwin, we provided instructions
449in older versions of this document.
450While those instructions are out of date and have been removed from current
451versions of this document, you may be able to make use of
452link:https://github.com/KhronosGroup/Vulkan-Docs/blob/v1.2.135/BUILD.adoc#depends[the
453version of BUILD.adoc in the v1.2.135 repository tag]
454
455[NOTE]
456.Note
457====
458While you do not have to use our Docker image, we cannot support every
459possible build environment.
460The Docker image is a straightforward way to build the specification in most
461modern desktop environments, without needing to install and update the spec
462toolchain yourself.
463====
464
465
466[[history]]
467== Revision History
468
469  * 2023-05-29 - Add Vulkan SC spec build instructions.
470  * 2022-10-11 - Update descriptions of using the Docker image to use the
471    `runDocker` script and the same SHA256 of the latest image as used by
472    CI.
473  * 2021-03-12 - Use the new Docker image.
474  * 2020-07-15 - Update to use `makeSpec` instead of `makeAllExts`.
475  * 2020-03-23 - Document Khronos' published Docker image for building the
476    spec, and remove all platform-specific instructions.
477  * 2018-12-04 - Update Rbenv and ruby gem installation instructions and
478    package dependencies for Linux and Ubuntu/Windows 10.
479  * 2018-10-25 - Update Troubleshooting, and Windows and Linux build. Plus
480    random editing.
481  * 2018-03-13 - Rename to BUILD.adoc and update for new directory
482    structure.
483  * 2018-03-05 - Update README for Vulkan 1.1 release.
484  * 2017-03-20 - Add description of prawn versioning problem and how to fix
485    it.
486  * 2017-03-06 - Add description of ruby-enum versioning problem and how to
487    fix it.
488  * 2017-02-13 - Move some comments here from ../../../README.md. Tweak
489    asciidoctor markup to more clearly delineate shell command blocks.
490  * 2017-02-10 - Add more Ruby installation guidelines and reflow the
491    document in accordance with the style guide.
492  * 2017-01-31 - Add rbenv instructions and update the README elsewhere.
493  * 2017-01-16 - Modified dependencies for Asciidoctor
494  * 2017-01-06 - Replace MathJax with KaTeX.
495  * 2016-08-25 - Update for the single-branch model.
496  * 2016-07-10 - Update for current state of spec and ref page generation.
497  * 2015-11-11 - Add new can: etc.
498    macros and DBLATEXPREFIX variable.
499  * 2015-09-21 - Convert document to asciidoc and rename to README.md in the
500    hope the gitlab browser will render it in some fashion.
501  * 2015-09-21 - Add descriptions of LaTeX and MathJax math support for all
502    output formats.
503  * 2015-09-02 - Added Cygwin package info.
504  * 2015-09-02 - Initial version documenting macros, required toolchain
505    components and versions, etc.
506