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

```bash
make html
```

to build the HTML version of the specification.

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

```bash
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:

```bash
./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:

```bash
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.
* 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

```sh
sudo apt install jing trang
```

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

```sh
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](https://rvm.io) or
  [rbenv](https://github.com/rbenv/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.
* 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.

```sh
# Absolute bare minimum for only these makefile targets:
# header html manhtmlpages extprocess styleguide loader
sudo apt install make git ruby python3

# 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

# 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 "~>2.0.10"
```

#### 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 are installed by gem separately.

Something like this will work:

```sh
# 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.

```sh
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:

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

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

```sh
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.

```sh
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.

```sh
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.
