OpenXR-SDK: generated headers and loader sources

A repository that is generated, and effectively read-only

The repository description says it plainly: generated headers and sources for the OpenXR loader. The README expands it. It contains OpenXR headers, as well as source code and build scripts for the OpenXR loader, and it contains all generated source files and headers pre-generated for minimum dependencies.

The word generated is the whole story of how to work with this repository, and the README says so directly. The public repository containing the scripts that generate the files in this repository is OpenXR-SDK-Source, and that repository hosts the public issue tracker and accepts patches from the general public. It is also where the sample code, hello_xr, and the API layer source can be found.

And then the note that saves people a wasted pull request: this repo is effectively read-only, and changes to it should be made in the OpenXR-SDK-Source repo instead.

So the relationship is a source and output pair. OpenXR-SDK-Source holds the generator, the API layer and the samples, and OpenXR-SDK holds what the generator produced. If you want to change a header, you change the generator and regenerate; if you want to report a bug, you file it in the other repository. The pre-generated for minimum dependencies phrase explains why the build is as simple as it is: the generated files do not require a specific version of a code generator to be present on your machine when you compile the loader.

The release tags follow the same pattern of an upstream project with a public cadence. They are release-1.1.61 on 2026-07-06, release-1.1.62 on 2026-08-01 and release-1.1.63 on 2026-09-02, and the last push to the repository was on 2026-10-16.

What is in include/ and src/loader

The directory structure section is short, and it maps directly onto the shape of the deliverable.

There is BUILDING.md with instructions for building the projects, README.md, COPYING.md with copyright and licensing information, and CODE_OF_CONDUCT.md. Then external/, described as external code for projects in the repo, include/, which holds the OpenXR header files, src/external/jsoncpp, which is the jsoncpp project source code and an included dependency of the loader, and src/loader, described as OpenXR loader code, including generated code.

Two things stand out. First, the headers and the loader are in the same repository, so the version of the API you compile against and the version of the loader you build are guaranteed to match. That matters for a project whose whole job is to be the portable interface between an application and whatever runtime is underneath.

Second, jsoncpp is vendored rather than pulled in as a dependency. The loader ships the source of the JSON parser it uses, inside src/external/jsoncpp, which means a loader build has no external package manager step for that dependency. For a component that is embedded in applications and distributed by runtime vendors, that is a deliberate choice about reproducible builds.

The wider repository layout backs this up. Besides include/ and src/ there is specification/, which holds the OpenXR specification documents, and a LICENSES/ directory, plus a .reuse/ directory, a CHANGELOG.SDK.md, a CMakeLists.txt at the root, an .azure-pipelines/ directory and an .appveyor.yml, which together describe a project built and tested on several platforms by continuous integration.

Building on Linux with CMake

The project is set up to build using CMake, and the README gives per platform instructions with the assumption that if you are already familiar with building a project with CMake you may skim them.

The Linux path is the cleanest to describe. A debug build is:

mkdir -p build/linux_debug
cd build/linux_debug
cmake -DCMAKE_BUILD_TYPE=Debug ../..
make

and the release build is the same with a different directory and a different build type:

mkdir -p build/linux_release
cd build/linux_release
cmake -DCMAKE_BUILD_TYPE=Release ../..
make

The out of source build is what the README expects, and the CMAKE_BUILD_TYPE selection is the only thing that differs between the two.

Before any of that, the Linux prerequisites are a specific list of Debian and Ubuntu packages, and the README says they provide all required libs for building for xlib or xcb with OpenGL and Vulkan support. The list is build-essential, cmake of somewhat recent vintage with 3.10 and above known working, libgl1-mesa-dev, libvulkan-dev, libx11-xcb-dev, libxcb-dri2-0-dev, libxcb-glx0-dev, libxcb-icccm4-dev, libxcb-keysyms1-dev, libxcb-randr0-dev, libxrandr-dev, libxxf86vm-dev and mesa-common-dev.

That list is the interface requirement in one place. The xcb packages and libx11-xcb-dev are for the X11 window system integration, libgl1-mesa-dev and mesa-common-dev for OpenGL, and libvulkan-dev for Vulkan. If you are building for a platform without X11, this list is not your list, and the README does not describe an alternative set for you.

The DYNAMIC_LOADER option and the Windows static default

One build decision is worth reading twice, because the default differs by platform and that asymmetry surprises people.

By default, the OpenXR loader is built as a static library on Windows and a dynamic library on other platforms. To specify alternate behavior, define the CMake option DYNAMIC_LOADER, for example by adding -DDYNAMIC_LOADER=ON or -DDYNAMIC_LOADER=OFF to your CMake command line.

So on Windows you get a static library unless you ask otherwise, and everywhere else you get a shared one unless you ask otherwise. The reason to care is distribution. A static loader is linked into the application and has no separate file to ship, while a dynamic loader is a shared object or DLL that the runtime loading has to find, and which has to match the version the application was built against. A toolkit that is embedded in other people's software and distributed by runtime vendors needs to make both available, and the option lets the packager choose.

The Windows build instructions add a detail that saves a confusing failure. Building on Windows is supported using Visual Studio 2013 and newer, and before beginning you must make sure the appropriate msbuild.exe is in your PATH. When generating the solutions and projects with CMake you also have to use the correct compiler version number, and the README supplies the mapping:

| Visual Studio | Version Number | | -------------------- |:--------------:| | Visual Studio 2017 | 15 | | Visual Studio 2019 | 16 | | Visual Studio 2022 | 17 |

The generation itself is the same shape as the Linux build, with a 64-bit variant that creates build\win64, changes into it and runs cmake with a Visual Studio generator, then open build\win64\OPENXR.sln in Visual Studio to build the loader, and a 32-bit variant that creates build\win32 and runs cmake with a generator without the Win64 suffix before opening build\win32\OPENXR.sln.

For macOS, the README supports Xcode 14.0 and newer, and you may need to install the Xcode Command Line Tools and cmake. You create build/macos, change into it, run cmake with the Xcode generator, and then open build/macos/OPENXR.xcodeproj in Xcode to build the samples.

Licensing is per file, not per repository

The licence arrangement in this repository is more careful than the single field in the metadata suggests, and it is worth understanding before you ship anything built from it.

The licence field in the repository's own metadata says Apache-2.0. The README file itself carries a different identifier, with an SPDX-License-Identifier of CC-BY-4.0 in its copyright header for the Khronos Group, which is a documentation licence applied to that file rather than to the code. And the repository root has both COPYING.adoc and a LICENSES/ directory, together with a .reuse/ directory, which is the layout used by the REUSE specification for recording the licence of every file individually.

That means the correct answer to what licence applies to a given file is the answer in its own metadata, not the answer in the repository settings. For the loader source and the headers, the identifiers recorded in the LICENSES/ directory and in the file headers are the ones that govern.

This is a point about where the terms are, not an interpretation of them. Practically, it means an organisation with a policy that keys on the SPDX tag per file will get a different answer for the README than for the loader, which is exactly what the REUSE layout is designed to make explicit.

The copyright header also dates the project, with The Khronos Group Inc. and the years 2017 to 2026, and the licence file for the documentation is COPYING.md while COPYING.adoc covers the code, with a CODE_OF_CONDUCT.md alongside.

Where OpenXR-SDK is the wrong repository to work in

The limits here are mostly about the split between the generated artefact and its source, and the mistakes that follow from ignoring it.

The first is the obvious one, and the README warns about it explicitly. Patching the generated files in this repository means your change is overwritten the next time the generator runs, and it will be rejected anyway, because changes here are supposed to be made in OpenXR-SDK-Source. If you need a different header, a different loader behaviour or a fix to the API layer, the work belongs in the other repository, which is where the issue tracker and the pull request process live.

The second is the sample code. hello_xr and the API layer source are not in this repository, they are in OpenXR-SDK-Source, so a reader looking for the smallest complete OpenXR program will not find it here.

The third is the dependency profile. The Linux package list is specific to xlib or xcb with OpenGL and Vulkan, and the README does not describe a build for a platform without X11, so a loader for a different windowing system is not covered by these instructions. The same applies to the Windows and macOS instructions, which assume Visual Studio and Xcode respectively.

The fourth is what this repository is good at, which is being a dependency. If you are writing an application against OpenXR, the practical use of this repository is the headers in include/ and, if you are shipping a runtime, the loader source in src/loader. Everything else about it is the machinery that produces those two things.

Editorial conclusion

Adopt OpenXR-SDK if you are building an OpenXR loader or application against the official headers and want the reference loader source with the platform layers already in place. Do not open pull requests against it, because the README states the repository is effectively read-only and that changes belong in OpenXR-SDK-Source, and do not assume the repository level licence covers every file, since the REUSE metadata assigns per file identifiers. Verify first which OpenXR release you are targeting against the tag list, that your Linux build has the X11, xcb, OpenGL and Vulkan development packages the README lists, and whether you want a static or a dynamic loader before you set the DYNAMIC_LOADER option.

Frequently asked questions

Official sources

1. KhronosGroup/OpenXR-SDK on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases