Building the Specification

Before building the specification, install the necessary prerequisite tools as described later in this document.

You may instead choose to use the open-in-docker.sh script, which will mount the repository in a container built from an image with all the necessary tools installed. See that script for more details. You can find the associated Dockerfile at https://github.com/KhronosGroup/DockerContainers/blob/master/Dockerfile.openxr

Conditional Inclusion of Extensions

By default, the specification is built without including the content belonging to any extensions.

You can build the specification without any extensions by simply using:

make html

to build the HTML version of the specification.

To include extension content, set the EXTENSIONS Make variable when invoking make. For example:

make EXTENSIONS="XR_KHR_performance_stats" APITITLE="(with XR_KHR_performance_stats)" html

• EXTENSIONS is a blank-separated list of extension name strings that you want included in the specification.
• APITITLE is a string used to annotate the specification title. Here, it is used to indicate which specification is included in this specification build.
• html is a Makefile target specifying what type of document to generate. See below for a list of targets.

Helper Scripts

Since specifying lists of extensions is tedious, there are several "helper" scripts that invoke make for you with a list of functions generated by these scripts.

• makeAllExt - includes all extensions defined in the registry
• makeExt - includes only extensions specified as an argument
• makeKHR - includes only KHR extensions defined in the registry
• makeKHRAndKHX - includes only KHR and KHX extensions defined in the registry

These are invoked as follows:

./makeAllExt target
./makeExt extension_name target
./makeKHR target
./makeKHRAndKHX target

• target is one of the targets listed below
• extension_name is a string containing one or more space-separated extension name strings.

Makefile Specification Targets

These targets generate a variety of output documents in the directory specified by the Makefile variable $(OUTDIR) (by default, out/1.0/).

It is recommended to build these targets using a "helper" script from above, unless you want to only build the core spec without any extensions.

These targets are currently supported.

• API spec:
  • html - Single-file HTML5 in $(OUTDIR)/openxr.html
  • pdf - PDF in $(OUTDIR)/openxr.pdf (Letter [8x5 x 11] paper size)
  • pdfA4 - PDF in $(OUTDIR)/openxr.pdf (A4 paper size)
• Reference pages:
  • manhtmlpages - Both combined ($(OUTDIR)/man/html/openxr.html) and per-entity ($(OUTDIR)/man/html/*.html) reference pages, extracted from the AsciiDoc spec chapters.
• OpenXR Header:
  • header - C language header files:
    • $(OUTDIR)/openxr/openxr.h
    • $(OUTDIR)/openxr/openxr_platform.h
    • $(OUTDIR)/openxr/openxr_reflection.h
  • header-test Compile-tests the header files
• Combined testing and output target (preview of some CI testing):
  • all

Makefile Other Targets

These targets can be built by simply invoking make without using the "helper" scripts mentioned above.

For example:

make styleguide

• "OpenXR Documentation and Extensions" guide (aka Style Guide):
  • styleguide - Single-file HTML5 in $(OUTDIR)/styleguide.html
• OpenXR Extensions Process guide:
  • extprocess - Single-file HTML5 in $(OUTDIR)/extprocess.html
• "OpenXR Loader - Design and Operation" guide (aka Loader Spec)
  • loader
• Extract example code from AsciiDoc and try to compile them.
  • build-examples
• Run a variety of self-tests and internal validations of the registry and spec
  • check-spec-links
• Remove targets and intermediate files
  • clean
• Remove intermediate files only
  • clean_dirt

Installing the Prerequisite Tools

This section describes the software components used by the OpenXR spec toolchain.

Before building the OpenXR spec, you must install the following tools:

• GNU make (make version: 4.0.8-1; older versions probably OK)
• Python 3 (python, version: 3.4.2 or newer, preferably 3.6 or newer)
  • These packages are recommended for check_spec_links on all platforms: termcolor tabulate
  • networkx is required for scripts/xml_consistency.py, which is run by the all target in the Makefile.
  • On Windows, colorama is also recommended.
  • On apt-based systems, sudo apt install python3-termcolor python3-tabulate python3-networkx will install the versions of those packages that are in your distribution, which are likely sufficient.
  • To install with pip, the typical pip3 install -r requirements.txt will work.
  • To be able to generate the Python docs, or perform spec diffs, you'll additionally need: sudo apt install python3-pytest python3-pypdf2 and python3 -m pip install pdoc3 pdf_diff
• Ruby (ruby, version 2.3.3 tested, anything newer should work)
  • The Ruby development package (ruby-dev) may also be required in some environments.
  • See below for required gems.
• Git command-line client (git, tested with version: 2.1.4). The build can progress without a git client, but branch/commit information will be omitted from the build. Any version supporting the following operations should work:
  • git symbolic-ref --short HEAD
  • git log -1 --format="%H"

For (optional) verification of the registry XML against its schema in make check-spec-links and make all, at least some of the following packages must be installed:

• jing for the validating XML against the schema, with the most usable error messages. (apt package jing)
• trang for RELAX-NG schema format verification and conversion. (apt package trang) Note: Related to jing, may be in the same package if you're using some other system.
• xmllint for validating XML against the schema. (apt package libxml2-utils) Also requires trang.
• xmlstarlet for validating XML against the schema. (apt package xmlstarlet) Also requires trang.

A recommended install of XML tooling for apt-based systems would be

sudo apt install jing trang

while a complete install of XML tooling (including redundant verifiers) would be

sudo apt install jing trang libxml2-utils xmlstarlet

The following Ruby Gems and platform package dependencies must also be installed. This process is described in more detail for individual platforms and environment managers below. Please read the remainder of this document (other than platform-specific parts you don't use) completely before trying to install.

• Asciidoctor (asciidoctor, version: 2.0.10 or compatible)
• Asciidoctor PDF (asciidoctor-pdf, version: 1.5.0 or compatible)

Note:

Asciidoctor-pdf versions before 1.5.0.alpha15 have issues with multi-page valid usage blocks, in that the background only renders for the first page. alpha.15 fixes this issue (as well as a few others); do not use prior versions.

Only the asciidoctor gem (and its dependencies) is needed if you don't intend to build PDF versions of the spec and supporting documents.

Note:

While it's easier to install just the toolchain components for HTML builds, people submitting MRs with substantial changes to the Specification are responsible for verifying that their branches build both html and pdf targets.

Platforms and System Packages

Windows

Most of the dependencies on Linux packages are light enough that it's possible to build the spec natively in Windows, but it means bypassing the makefile and calling functions directly. This might be solved in future. However, given how well Windows Subsystem for Linux works for most uses, it is unlikely to be worth the effort to fully enable a native build.

When using Ubuntu 16.04 or 18.04 via the Windows 10 Subsystem for Linux, most dependencies can be installed via apt-get, with the two ruby gems installed with gem in the user's directory. The Ubuntu 16.04.6 default Ruby install (version 2.3.1) seems to be up-to-date enough to run all the required gems. Just follow the Debian-derived Linux instructions below.

Notes:

• If you're already using rvm or rbenv to upgrade your version of Ruby, that's OK, but it's no longer necessary. Ubuntu 16.04 and newer (as well as probably most any distribution you'd find for WSL) contains a new enough Ruby, just not new enough AsciiDoctor and AsciiDoctor-PDF. Ubuntu 20.04 and newer contains a new-enough everything.
• Most of the tools on Bash for Windows are quite happy with Windows line endings (CR LF), but bash scripts expect Unix line endings (LF). The file .gitattributes at the top of the repo forces such scripts to be checked out with the proper line endings on non-Linux platforms. If you add new scripts whose names don't end in .sh, they should be included in .gitattributes as well.
• For building spec, you might have a better experience if you clone the repository using git installed inside WSL, rather than a native Windows build of Git.

Debian-derived Linux (including Ubuntu and Ubuntu on WSL)

Other distributions using different package managers, such as RPM (Fedora) and Yum (SuSE) will have different requirements.

# Absolute bare minimum for only these makefile targets:
# header html manhtmlpages extprocess styleguide loader
sudo apt install make git ruby python3
gem install --user asciidoctor

# More complete, for building these makefile targets:
# header html pdf pdfA4 manhtmlpages styleguide loader header-test: build-examples check-spec-links release
sudo apt -y install build-essential python3 git libxml2-dev ttf-lyx ghostscript ruby \
  python3-termcolor python3-tabulate python3-networkx
gem install --user asciidoctor asciidoctor-pdf

# Full build: supports all makefile targets, including the "all" target
sudo apt -y install build-essential python3 git libxml2-dev ttf-lyx ghostscript ruby \
  trang jing python3-termcolor python3-tabulate python3-networkx
gem install --user asciidoctor asciidoctor-pdf

Ubuntu 20.04+, Debian Bullseye, and Debian Buster Backports all have new enough asciidoctor and asciidoctor-pdf in their repositories (Buster has asciidoctor-pdf 1.5.0 alpha17 which isn't ideal but should work) so the gem lines below can be replaced with something like this (adding -t buster-backports if you're still on Buster):

sudo apt install asciidoctor

# or this, if you also want to build PDFs:
sudo apt install asciidoctor ruby-asciidoctor-pdf

macOS

It should be possible to install equivalent dependencies using Homebrew. If you know how, please contribute instructions.

Installing Gems

Since most Linux distributions do not have new enough AsciiDoctor/AsciiDoctor-PDF, these can be installed by gem separately.

Something like this will work:

# Bare minimum install
gem install --user "asciidoctor:~>2.0.10"

# Adding PDF support
gem install --user "asciidoctor:~>2.0.10" "asciidoctor-pdf:~>1.5.0"

After the gem install --user, you may see a message that a directory isn't on the path. You can run the following, modifying the version number as necessary to match the error message.

echo 'export PATH=$HOME/.gem/ruby/2.3.0/bin:$PATH' >> ~/.bashrc

Restart your shell (e.g. open a new terminal window). Opening a new tab in your existing terminal application is usually not enough. Note that you do not need to use the -l option, since the modifications were made to .bashrc rather than .bash_profile. If successful, which asciidoctor should print something that starts with your home directory.

(If you run something other than bash, you'll want to do the equivalent in your shell.)

If Gems not working

If you've installed Ruby Gems before, sometimes things can get out of sync. This is especially true after a system update. In fact, you may have installed some under your personal account and some under the system account (using sudo).

If you have used "sudo" to install any gems before, you should either remove all your "sudo" gems, or all your personal gems.

I removed all my personal gems to fix collisions and reinstalled the system ones using the steps below.

First, uninstall the personal gems:

gem uninstall asciidoctor-pdf \
              asciidoctor-mathematical \
              asciidoctor \
              rake \
              coderay \
              json-schema \
              mathematical \
              ruby-enum

Then, I uninstalled all the same packages for the system:

sudo gem uninstall asciidoctor-pdf \
                   asciidoctor-mathematical \
                   asciidoctor \
                   rake \
                   coderay \
                   json-schema \
                   mathematical \
                   ruby-enum

Then, update Gem in one location. Again, I used "sudo", but you don't have to here.

sudo gem pristine --all
sudo gem update --system

This actually restored the packages I had installed before. But, just in case, I asked to install them again.

sudo gem install asciidoctor \
                 rake \
                 coderay \
                 json-schema \
                 mathematical \
                 ruby-enum \
                 rubygems-update
MATHEMATICAL_SKIP_STRDUP=1 sudo gem install asciidoctor-mathematical
sudo gem install asciidoctor-pdf --pre

Notice, that I also installed rubygems-update, not sure if it helped, but I found this online.

This allowed my system to be properly setup again.