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, specification/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 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
- On Windows, colorama is also recommended.
- On apt-based systems, sudo apt install python3-termcolor python3-tabulate 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.
Ruby (ruby, version: 2.3.3)
- 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"
Ghostscript (ghostscript, version: 9.10). This is for the PDF build, and it can still progress without it. Ghostscript is used to optimize the size of the PDF, so will be a lot smaller if it is included.

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: 1.5.5)
Coderay (coderay, version 1.1.1)
JSON Schema (json-schema, version 2.0.0)
Asciidoctor PDF (asciidoctor-pdf, version: 1.5.0.alpha15)
- If using gem to install, you need to use gem install --pre -- the --pre is important.
Asciidoctor Mathematical (asciidoctor-mathematical, version 0.2.2)
Dependencies for asciidoctor-mathematical (There are a lot of these! but, they will automatically come in with gem)
Bundled in this repo: KaTeX distribution (version 0.7.0 from https://github.com/Khan/KaTeX . This is cached under specifications/scripts/katex/, and need not be installed from GitHub.

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 and coderay gems are needed if you don't intend to build PDF versions of the spec and supporting documents.

json-schema is only required in order to validate the output of the valid usage extraction scripts to a JSON file. If not installed, validation will be skipped when the JSON is built.

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.

Platform-specific toolchain instructions follow:

Microsoft Windows
Mac OS X
Linux

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. For now, there are three options for Windows users: Ubuntu / Windows 10, MinGW, or Cygwin.

Windows Subsystem for Linux (Windows 10 with Ubuntu)

When using the "Ubuntu Subsystem" for Windows 10, most dependencies can be installed via apt-get:

sudo apt -y install build-essential python3 git cmake bison flex \
    libffi-dev libxml2-dev libgdk-pixbuf2.0-dev libcairo2-dev \
    libpango1.0-dev ttf-lyx gtk-doc-tools ghostscript \
    python3-termcolor python3-tabulate

The default ruby packages on Ubuntu are fairly out of date. Ubuntu only provides ruby and ruby2.0 - the latter is multiple revisions behind the current stable branch, and would require wrangling to get the makefile working with it.

Luckily, there are better options; either rvm or rbenv is recommended to install a more recent version.

Note:

If you are new to Ruby, you should completely remove (through the package manager, e.g. sudo apt-get remove *packagename*) all existing Ruby and asciidoctor infrastructure on your machine before trying to use rvm or rbenv for the first time. dpkg -l | egrep 'asciidoctor|ruby|rbenv|rvm' will give you a list of candidate package names to remove.
- If you already have a favorite Ruby package manager, ignore this advice, and just install the required OS packages and gems.
- In addition, rvm and rbenv are mutually incompatible. They both rely on inserting shims and $PATH modifications in your bash shell. If you already have one of these installed and are familiar with it, it's probably best to stay with that one. One of the editors, who is new to Ruby, found rbenv far more comprehensible than rvm. The other editor likes rvm better.
- Neither rvm nor rbenv work, out of the box, when invoked from non-Bash shells like tcsh. This can be hacked up by setting the right environment variables and PATH additions based on a bash environment.
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.

Ubuntu Subsystem Using Rbenv

Rbenv is a lighter-weight Ruby environment manager with less functionality than rvm. Its primary task is to manage different Ruby versions, while rvm has additional functionality such as managing "gemsets" that is irrelevant to our needs.

A complete installation script for the toolchain on Ubuntu for Windows, developed on an essentially out-of-the-box environment, follows. If you try this, don't try to execute the entire thing at once. Do each step separately in case of errors we didn't encounter.

# Install packages needed by `ruby_build` and by toolchain components.
# See https://github.com/rbenv/ruby-build/wiki and
# https://github.com/asciidoctor/asciidoctor-mathematical#dependencies

sudo apt-get install autoconf bison build-essential libssl-dev \
    libyaml-dev libreadline6-dev zlib1g-dev libncurses5-dev \
    libffi-dev libgdbm3 libgdbm-dev cmake libxml2 \
    libxml2-dev flex pkg-config libglib2.0-dev \
    libcairo-dev libpango1.0-dev libgdk-pixbuf2.0-dev \
    libpangocairo-1.0

# Install Python packages
sudo apt install python3-termcolor python3-tabulate

# Install rbenv from https://github.com/rbenv/rbenv
git clone https://github.com/rbenv/rbenv.git ~/.rbenv

# Set path to shim layers in .bashrc
echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> .bashrc

~/.rbenv/bin/rbenv init

# Set .rbenv environment variables in .bashrc
echo 'eval "$(rbenv init -)"' >> .bashrc

# Restart your shell (e.g. open a new terminal window). Note that
# you do not need to use the `-l` option, since the modifications
# were made to .bashrc rather than .bash_profile. If successful,
# `type rbenv` should print 'rbenv is a function' followed by code.

# Install `ruby_build` plugin from https://github.com/rbenv/ruby-build

git clone https://github.com/rbenv/ruby-build.git ~/.rbenv/plugins/ruby-build

# Install Ruby 2.3.3
# This takes in excess of 20 min. to build!
# https://github.com/rbenv/ruby-build/issues/1054#issuecomment-276934761
# suggests:
# "You can speed up Ruby installs by avoiding generating ri/RDoc
# documentation for them:
# RUBY_CONFIGURE_OPTS=--disable-install-doc rbenv install 2.3.3
# We have not tried this.

rbenv install 2.3.3

# Configure rbenv globally to always use Ruby 2.3.3.
echo "2.3.3" > ~/.rbenv/version

# Finally, install toolchain components.
# asciidoctor-mathematical also takes in excess of 20 min. to build!
# The same RUBY_CONFIGURE_OPTS advice above may apply here as well.

gem install asciidoctor coderay json-schema
gem install --pre asciidoctor-pdf
MATHEMATICAL_SKIP_STRDUP=1 gem install asciidoctor-mathematical

Ubuntu Subsystem Using RVM

Here are (sparser) instructions for using rvm to setup version 2.3.x:

gpg --keyserver hkp://keys.gnupg.net --recv-keys 409B6B1796C275462A1703113804BB82D39DC0E3
curl -sSL https://get.rvm.io | bash -s stable --ruby
source ~/.rvm/scripts/rvm
rvm install ruby-2.3
rvm use ruby-2.3

Note:

Windows 10 Bash will need to be launched with the "-l" option appended, so that it runs a login shell; otherwise RVM won't function correctly on future launches.

Ubuntu 16 using system Ruby

The Ubuntu 16.04.1 default Ruby install (version 2.3.1) seems to be up-to-date enough to run all the required gems, but also needs the ruby-dev package installed through the package manager.

In addition, the library /var/lib/gems/2.3.0/gems/mathematical-1.6.7/ext/mathematical/lib/liblasem.so has to be copied or linked into a directory where the loader can find it. This requirement appears to be due to a problem with the asciidoctor-mathematical build process.

As with other Debian-based systems, you can install the Python packages with:

sudo apt install python3-termcolor python3-tabulate

MinGW

MinGW can be obtained here: http://www.mingw.org/

Once the installer has run its initial setup, following the instructions on the website, you should install the mingw-developer-tools, mingw-base and msys-base packages. The msys-base package allows you to use a bash terminal from windows with whatever is normally in your path on Windows, as well as the unix tools installed by MinGW.

In the native Windows environment, you should also install the following native packages:

Python 3.x (https://www.python.org/downloads/)
Ruby 2.x (https://rubyinstaller.org/)
Git command-line client (https://git-scm.com/download)

Once this is setup, and the necessary Ruby Gems are installed, launch the msys bash shell, and navigate to the spec Makefile. From there, you'll need to set PYTHON= to the location of your python executable for version 3.x before your make command - but otherwise everything other than pdf builds should just work.

NOTE: Building the PDF spec via this path has not yet been tested but may be possible - liblasem is the main issue and it looks like there is now a mingw32 build of it available.

Cygwin

When installing Cygwin, you should install the following packages via setup:

// "curl" is only used to download fonts, can be done in another way
autoconf
bison
cmake
curl
flex
gcc-core
gcc-g++
ghostscript
git
libbz2-devel
libcairo-devel
libcairo2
libffi-devel
libgdk_pixbuf2.0-devel
libiconv
libiconv-devel
liblasem0.4-devel
libpango1.0-devel
libpango1.0_0
libxml2
libxml2-devel
make
python3
ruby
ruby-devel

Note:

Native versions of some of these packages are usable, but care should be taken for incompatibilities with various parts of cygwin - e.g. paths. Ruby in particular is unable to resolve Windows paths correctly via the native version. Python and Git for Windows can be used, though for Python you'll need to set the path to it via the PYTHON environment variable, before calling make.

When it comes to installing the mathematical ruby gem, there are two things that will require tweaking to get it working. Firstly, instead of:

MATHEMATICAL_SKIP_STRDUP=1 gem install asciidoctor-mathematical

You should use

MATHEMATICAL_USE_SYSTEM_LASEM=1 gem install asciidoctor-mathematical

The latter causes it to use the lasem package already installed, rather than trying to build a fresh one.

The mathematical gem also looks for "liblasem" rather than "liblasem0.4" as installed by the lasem0.4-devel package, so it is necessary to add a symlink to your /lib directory using:

ln -s /lib/liblasem-0.4.dll.a /lib/liblasem.dll.a

Ruby Gems are not installed to a location that is in your path normally. Gems are installed to ~/bin/ - you should add this to your path before calling make:

export PATH=~/bin:$PATH

Finally, you'll need to manually install fonts for lasem via the following commands:

mkdir /usr/share/fonts/truetype cd /usr/share/fonts/truetype
curl -LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/cmex10.ttf \
     -LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/cmmi10.ttf \
     -LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/cmr10.ttf \
     -LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/cmsy10.ttf \
     -LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/esint10.ttf \
     -LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/eufm10.ttf \
     -LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/msam10.ttf \
     -LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/msbm10.ttf

Mac OS X

Mac OS X should work in the same way as for ubuntu by using the Homebrew package manager, with the exception that you can simply install the ruby package via brew rather than using a ruby-specific version manager.

You'll likely also need to install additional fonts for the PDF build via mathematical, which you can do with:

cd ~/Library/Fonts
curl -LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/cmex10.ttf \
     -LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/cmmi10.ttf \
     -LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/cmr10.ttf \
     -LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/cmsy10.ttf \
     -LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/esint10.ttf \
     -LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/eufm10.ttf \
     -LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/msam10.ttf \
     -LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/msbm10.ttf

Then install the required Ruby Gems.

Linux

The instructions for the Windows 10 Ubuntu Subsystem installation are generally applicable to native Linux environments using Debian packages, such as Debian and Ubuntu, although the exact list of packages to install may differ. Other distributions using different package managers, such as RPM (Fedora) and Yum (SuSE) will have different requirements.

Using rbenv or rvm is necessary, since the system Ruby packages are often well out of date.

Once the environment manager, Ruby, and ruby_build have been installed, install the required Ruby Gems.

Ruby Gems

The following ruby gems can be installed directly via the gem install command, once the platform is set up:

gem install rake asciidoctor coderay json-schema

# Required only for pdf builds
MATHEMATICAL_SKIP_STRDUP=1 gem install asciidoctor-mathematical
gem install --pre asciidoctor-pdf

Ruby Gem Versioning Errors

ruby-enum

As of 2017-03-06, there appears to be a problem with the ruby-enum version 0.7.1 gem which breaks the PDF build. Make sure you are using ruby-enum 0.7.0, as follows:

gem uninstall ruby-enum
gem install -v 0.7.0 ruby-enum

Hopefully this will soon be fixed. See gjtorikian/mathematical#69 for a report of this problem.

prawn

As of 2017-03-20, there are incompatibilities between asciidoctor-pdf and certain versions of prawn and prawn-templates affecting the PDF build. Make sure to update to prawn 2.2.1 and prawn-templates 0.0.5. See

KhronosGroup/Vulkan-Docs#476

If Gems still 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, unintstall 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.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README.md

README.md

Building the Specification

Conditional Inclusion of Extensions

Helper Scripts

Makefile Specification Targets

Makefile Other Targets

Installing the Prerequisite Tools

Windows

Windows Subsystem for Linux (Windows 10 with Ubuntu)

Ubuntu Subsystem Using Rbenv

Ubuntu Subsystem Using RVM

Ubuntu 16 using system Ruby

MinGW

Cygwin

Mac OS X

Linux

Ruby Gems

Ruby Gem Versioning Errors

If Gems still not working

Files

README.md

Latest commit

History

README.md

File metadata and controls

Building the Specification

Conditional Inclusion of Extensions

Helper Scripts

Makefile Specification Targets

Makefile Other Targets

Installing the Prerequisite Tools

Windows

Windows Subsystem for Linux (Windows 10 with Ubuntu)

Ubuntu Subsystem Using Rbenv

Ubuntu Subsystem Using RVM

Ubuntu 16 using system Ruby

MinGW

Cygwin

Mac OS X

Linux

Ruby Gems

Ruby Gem Versioning Errors

If Gems still not working