Introduction

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

Building The Spec

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 value of ASCIIDOC is not correct for the asciidoc script on your platform, change it 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.

$ make all

or equivalently:

$ make xhtml pdf styleguide manhtml manpdf manhtmlpages checkinc checklinks

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

  • API spec:

    • xhtml - Single-file XHTML in $(OUTDIR)/xhtml/vkspec.html

    • pdf - PDF in $(OUTDIR)/pdf/vkspec.pdf

  • “Vulkan Documentation and Extensions” guide:

    • styleguide - Single-file HTML5 in $(OUTDIR)/styleguide.html

  • Reference pages:

    • manhtml - Single-file HTML in $(OUTDIR)/apispec.html

    • manpdf - Single-file PDF in $(OUTDIR)/apispec.html

    • manhtmlpages - File-per-entry-point HTML in $(OUTDIR)/man/html/*

  • Validator output:

    • checkinc - List of commands, structs, etc. missing from the API spec in $(OUTDIR)/checks/notInSpec.txt

    • checklinks - Validator script output for API spec in $(OUTDIR)/checks/specErrs.txt and for reference pages in +$(OUTDIR)/checks/manErrs.txt

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

$ make -j 8

may 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:

  • manpages - File-per-entry-point nroff source in $(OUTDIR)/man/3/*

Building With Extensions Included

As of version 1.0.25 of the Specification, we are using a “single-branch model”, where extensions are included in the same 1.0 branch as the core Specification, instead of the older model where each extension lived in a separate Git branch. Whether a given extension is generated in the output depends on asciidoc and generator script options being specified.

The extensions included are those specified as a space-separated list of extension names (e.g. VK_KHR_surface) in the Makefile variable $(EXTENSIONS), normally set on the make command line. When changing the list of extensions, it is critical to remove all generated files using the clean_generated Makefile target, as the contents of generated files depends on $(EXTENSIONS). There are two helper scripts which clean these files and then build one or more specified targets for specified extensions:

  • makeExt - generate outputs with a single extension enabled. Usage is makeExt extension-name target(s), where extension-name is the extension name string, such as VK_EXT_debug_report.

  • makeKHR - generate outputs with all Khronos (VK_KHR_*) extensions enabled. Usage is makeKHR target(s).

The Makefile variable $(APITITLE) defines an additional string which is appended to the specification title. When building with extensions enabled, this should be set to something like (with extension VK_extension_name). The makeExt and makeKHR scripts already do this.

Alternate and Test Builds

If you are just testing asciidoc formatting, macros, stylesheets, etc., it is much faster to edit vkspec.txt to comment out most of the chapter includes.

In addition to the XHTML and PDF targets, there is also a single-file HTML5 target, html, which generates output directly from asciidoc without going through Docbook. This is quicker to generate, but formatting and section numbers aren’t neccessarily consistent with the other builds and it is not for publication - just testing. The html target will generate the file $(OUTDIR)/html/vkspec.html .

Rebuilding The Generated Images

There are some images in the images/ directory which are maintained in one format but need to be converted to another format for corresponding types of output. Most are SVG converted to PDF, some are PPT converted to PDF converted to SVG. SVG and PDF forms are needed for the HTML and PDF output formats, respectively.

These files are not automatically converted by the Makefile. Instead, all output forms required are checked into images/ . On the rare occasions that someone changes a source document and needs to regenerate the other forms:

cd images
make

Our Asciidoc Macros

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.

Reference Pages

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.

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

$ rm man/apispec.txt
$ make apispec.txt

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.

Our stylesheets

Note
 Section mostly TBD.

There is 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.

Marking Changes

There is the start of support for marking added, removed, and changed text in the spec body. Currently this is supported only in the XHTML targets (xhtml and chunked), and only for paragraphs and spans of words.

Added, removed, and changed material is marked with the asciidoc roles named added, removed, and changed respectively. They can be used to mark an entire paragraph, as follows:

[role="change"]
This paragraph shows change markings.

Or a few words in a sentence, as follows:

This sentence contains [added]#some added words# and [removed]#some
removed words#.

The formatting of these roles text depends on the stylesheet. Currently it all three roles are red text, and the "removed" role is also strike-through text.

We don’t use this capability yet; it’s just a proof of concept. It would be a huge amount of work to insert this markup automatically for each spec update, and it would be very difficult to do automatically based on git diffs.

Marking Normative Language

There is support for marking normative language in the document. Currently this is supported only in the XHTML targets (xhtml and chunked).

Normative language is marked with the asciidoc role named normative. It can be used to mark entire paragraphs or spans of words, in the same fashion as change markings (described above). In addition, the normative terminology macros, such as must and may and cannot, always use this role.

The formatting of normative language depends on the stylesheet. Currently it just comes out in purple. We may add a way to disable this formatting at build time.

Imbedding Equations

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:

  • The special characters < , > , and & can currently be used only in [latexmath] block macros, not in latexmath:[] inline macros. Instead use \lt for < and \gt for >. & is an alignment construct for multiline equations, and should only appear in block macros anyway.

  • AMSmath environments (e.g. \begin{equation*}, {align*}, etc.) can be used, to the extent MathJax supports them.

  • When using AMSmath environments, do not also surround the equation block with \[\] brackets. That is not legal LaTeX math and will break the PDF build. It is good practice to make sure all spec targets build properly before proposing a merge to master.

  • Arbitrary LaTeX constructs cannot be used with MathJax. It is an equation renderer, not an full LaTeX engine. So imbedding LaTeX like \Large or \hbox{\tt\small VK\_FOO} may not work in any of the HTML backends, and should be avoided.

Asciidoc Anchors And Xrefs

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:

Synchronization Primitives

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

See the <> section for discussion of fences, semaphores, and events.

You can also add anchors on arbitrary paragraphs, using a similar naming scheme.

Anything whose definition comes from one of the autogenerated API include files (.txt files in the directories basetypes, enums, flags, funcpointers, handles, protos, and structs) has a corresponding anchor whose name is the name of the function, struct, etc. being defined. Therefore you can say something like:

Fences are used with the +++<<vkQueueSubmit>>+++ command...

Software Dependencies

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

General Dependencies

These are versions of required tools in one of the editors' development environment (Debian 8, shown as Debian package names). Earlier versions may work but unless they are verified by someone else, there’s no way to know that. Later versions should work.

  • GNU make (make version: 4.0.8-1; older versions probably OK)

  • Asciidoc (asciidoc version: 8.6.9-3)

  • Python 3 (python, version: 3.4.2)

  • Git command-line client (git, version: 2.1.4) Only needed if regenerating specversion.txt. Any version supporting the operations  — git symbolic-ref --short HEAD and  — git log -1 --format="%H" should work).

  • Docbook LaTeX toolchain (dblatex, version: 0.3.5-2)

  • Source code highlighter (source-highlight, version: 3.1.7-1+b1)

  • LaTeX distribution (texlive, version: 2014.20141024-2)

Cygwin Dependencies

The cygwin installer is at http://www.cygwin.org. Use the 64-bit version, because the 32-bit version does not include the latest version of asciidoc required for this project.

Required Cygwin packages (current version):

  • Devel/make (4.1-1)

  • Python/python (2.7.10-1) - Needed for asciidoc toolchain

  • Python/python3 (3.4.3-1)

  • Python/python3-lxml (3.4.4-1) - Needed for generating vulkan.h

  • Text/asciidoc (8.6.8-1)

  • Text/dblatex (0.3.4-1)

  • Text/source-highlight (3.1.8-1)

Optional Cygwin packages (current version):

  • Devel/gcc-core (4.9.3-1) - Needed for validating generated headers

  • Devel/gcc-g++ (4.9.3-1) - Needed for validating generated headers

  • Devel/git (2.5.1-1) - Needed for updating specversion.txt

Revision History

  • 2016-08-25 - Update for the single-branch model.

  • 2016-07-10 - Update for current state of spec and ref page generation.

  • 2015-11-11 - Add new can etc. macros and DBLATEXPREFIX variable.

  • 2015-09-21 - Convert document to asciidoc and rename to README.md in the hope the gitlab browser will render it in some fashion.

  • 2015-09-21 - Add descriptions of LaTeX+MathJax math support for all output formats.

  • 2015-09-02 - Added Cygwin package info.

  • 2015-09-02 - Initial version documenting macros, required toolchain components and versions, etc.