Vulkan Specification Build Instructions and Notes

This README describes important stuff for getting the Vulkan API specification and reference pages building properly.

Assuming you have all the right tools installed (see Software Dependencies below), go to …path-to-git-repo/vulkan/doc/specs/vulkan .

If the default values of ASCIIDOC and A2X are not correct for the asciidoc and a2x scripts on your platform, change them via environment variables, command line options, or by modifying the Makefile. The default script names have .py suffixes. These suffixes should be removed for Linux platforms, and possibly for other non-Windows environments.

or equivalently:

This will generate a variety of targets under $(OUTDIR) (by default, ../../../out/1.0). The checked-in file $(OUTDIR)/index.html links to them all, or they can individually be found as follows:

Once you have the basic build working, an appropriate parallelization option to make, such as

will significantly speed up the reference page builds.

If your asciidoc installation does not put the stylesheets and xsl files in the standard /etc/asciidoc/dblatex directory, set the environment variable DBLATEXPREFIX to the path to that directory (the one containing the asciidoc-dblatex.xsl and asciidoc-dblatex.sty files installed with asciidoc).

The manpages target is deprecated, as the resulting Unix man pages have issues with content like embedded latexmath: constructs, but is still available for third parties wishing to generate them:

We use a bunch of custom macros in the reference pages and API spec asciidoc sources. The validator scripts rely on these macros as part of their sanity checks, and you should use the macros whenever referring to an API command, struct, token, or enum name, so the documents are semantically tagged and more easily verifiable.

The supported macros are defined in config/vkspec.conf (for the API spec) and config/manpages.conf (for the reference pages).

The tags used are described in the style guide (styleguide.txt).

We will eventually tool up the spec and ref pages to the point that anywhere there’s a type or token referred to, clicking on (or perhaps hovering over) it in the HTML view and be taken to the definition of that type/token. That will take some more plumbing work to tag the stuff in the autogenerated include files, and do something sensible in the spec (e.g. resolve links to internal references).

Most of these macros deeply need more intuitive names.

Prior to the 1.0.20 update of the API spec, the reference pages in man/ were handwritten, incomplete, and often way out of date with respect to the spec.

Our initial effort to address this was to tag the API spec to help identify boundaries of language talking about different commands, structures, enumerants, and other types, then use a set of Python scripts to automatically extract that language into the corresponding ref page. Pages without corresponding content in the API spec are generated automatically, when possible.

This has generated a semantically complete set of ref pages. Although they are still far from ideal, they now fully document the API, and will stay in sync with it. A significant drawback of this approach is that the only place ref pages for extension interfaces can be generated is inside the corresponding extension branches.

If for some reason you want to regenerate the ref pages from scratch yourself, you can do so by

The genRef.py script will generate many warnings, but most are just reminders that some pages are automatically generated. If everything is working correctly, all the man/*.txt files will be regenerated, but their contents will not change.

This branch introduces a Vulkan-specific XHTML CSS stylesheet in config/vkspec-xhtml.css . It started as a clone of the default Asciidoc stylesheet, but added some new features. Similar CSS in config/vkman.css is used for the reference pages.

Equations should be written using the latexmath: inline and block macros. The contents of the latexmath: blocks should be LaTeX math notation, surrounded by appropriate delimiters - $$, \[\], \(\), or \begin{env}/\end{env} math environments such as {equation*} or {align*}.

The asciidoc macros and configuration files, as well as the dblatex customization layers, have been modified significantly so that LaTeX math is passed through unmodified to all HTML output forms (using the MathJax engine for real-time rendering of equations) and to dblatex for PDF output.

The following caveats apply:

In the API spec, sections can have anchors (labels) applied with the following syntax. In general the anchor should immediately precede the chapter or section title and should use the form [[chapter-section-label]]. For example,

For example, in chapter synchronization.txt:

Cross-references to those anchors can then be generated with, for example,

This section describes the software components used by the Vulkan spec toolchain. under the General Dependencies below, then describes specific considerations for Windows environments using Cygin under Cygwin Dependencies