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), you should be able to go to …path-to-git-repo/vulkan/doc/specs/vulkan and:

or equivalently:

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

We strongly sugges that once you have the basic build working, you use e.g. -j 8 (or other appropriate number depending on the number of cores in your CPU) to parallelize the reference page builds, since there are so many of them.

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 installed with asciidoc).

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).

Tags used in both the specification and reference pages:

Tags used only in the specification, at present:

The [efs]link: macros are used for validation, and are also expanded into xref links to the correspondingly named anchor.

The [efsp]name: macros are used for validation, but are not expanded into links.

The [efs]text: macros are not used for validation, and are not expanded into links.

We will eventually tool up the spec and ref pages to the point that anywhere there’s a type or token referred to, you could click/hover on 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).

In that light, the [fs]name: vs. [fs]link: distinction seems mostly unneeded. Probably the only time we would not want a tag to be a link to its definition is when tagging a function name inside its own ref page. So once the plumbing is done, most of the [fs]name: tags can turn into [fs]link: tags.

The ename: vs. elink: distinction is different since they’re referring to different namespaces - individual enumerant names vs. "enum" type names - rather than different ways of presenting the same command or struct name as for the other tags.

Most of these macros deeply need more intuitive names.

This branch introduces a Vulkan-specific XHTML CSS stylesheet in config/vkspec-xhtml.css. Mostly it just clones the default Asciidoc stylesheet, but adds some new features:

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