KhronosGroup/Vulkan-Docs: What the Vulkan Specification Repository Actually Contains

The Vulkan spec repository is not the Vulkan SDK

The most common mistake with this repository is expecting code. Vulkan-Docs holds the normative written specification for the Vulkan API and the Vulkan SC API, the XML registry those documents are generated from, and the design documents for extensions. There is no renderer here, no loader, no ICD, and no sample application. The README splits the audience explicitly: READMEVK.adoc covers Vulkan API documentation, READMESC.adoc covers Vulkan SC.

The people who need this repository fall into three groups. Driver and validation-layer authors who must match the specification text exactly. Extension authors writing proposals under proposals/. And tooling authors who parse xml/vk.xml to generate bindings, loaders, or validation rules. If you are learning to draw a triangle, this is the wrong repository, and the README does not pretend otherwise.

A useful signal about scope: the generated headers under include/vulkan/vulkan*.h are not checked into the repository. The README states that the header files and many parts of the specification and reference pages are generated from descriptions in the XML API Registry at xml/vk.xml. What you clone is source for those artifacts, not the artifacts themselves.

From vk.xml to a rendered specification

The data flow is one-directional. Authors edit the XML API Registry, xml/vk.xml, plus Asciidoctor sources in chapters/, appendices/, and the top-level vkspec.adoc. Generator scripts in scripts/ read the registry and emit headers, reference-page fragments, and other derived files. The top-level Makefile wires those dependencies together, and Asciidoctor renders the final documents into gen/out/, which the README calls the default directory for generated documents.

The Makefile is where the build's variability lives. A VULKAN_API variable selects the API, defaulting to vulkan, with vulkansc and vulkanbase as the other documented values. A VERSIONS variable takes a space-separated list of version names, and the Makefile comment is strict about ordering: including VK_VERSION_1_3 requires also including all previous versions such as VK_VERSION_1_1 and VK_VERSION_1_0. An EXTENSIONS variable does the same for optional extensions. Both are converted into generator script arguments and into an attributes file.

One detail worth noticing is .DELETE_ON_ERROR at the top of the Makefile. The comment explains that without it, a leftover file from a failed recipe can falsely satisfy dependencies on later runs. That is a build system designed for people who run it repeatedly and care whether a failure was real.

Building the spec and regenerating the headers

The README directs readers to BUILD.adoc for installing the toolchain and building the specification, so the exact package list lives there rather than in the README. The document sources are marked up in Asciidoctor format, and the project uses asciidoctor and related toolchain components to generate output documents.

For header regeneration, the README gives a concrete two-line path. The headers are produced from the registry, and if you change vk.xml you go into xml/ and run:

$ make clean install

That target lives in xml/README.adoc's territory, not the top-level Makefile, so run it from the xml/ directory as the README instructs. The other generated files are built as required through dependencies in the top-level Makefile, which means a plain make from the repository root is the entry point for the specification itself.

The package.json in the repository is minimal and private, with devDependencies on escape-string-regexp, he, and lunr pinned at specific versions. That is the JavaScript side of the toolchain, consistent with the repository's primary language listing. It is not an application dependency graph you install to use Vulkan.

Where the repository gets in your way

The build is heavy by design. Asciidoctor plus the generator scripts plus a full specification render is not a quick operation, and the repository ships no prebuilt specification you can read without building. The README points to BUILD.adoc rather than providing a one-command setup, and no releases are listed for the repository, so there is no packaged artifact to download from it.

The VERSIONS ordering rule is a real failure mode. Passing VK_VERSION_1_3 without VK_VERSION_1_1 and VK_VERSION_1_0 contradicts the Makefile's documented requirement, and the resulting build will not represent the API you intended. Similarly, EXTENSIONS must be listed explicitly; omitting one silently produces a specification without it.

Licensing is another place where the repository resists a single answer. The top-level LICENSE.adoc is described as a summary of licenses used by files in the repository, COPYING.adoc covers copyright and licensing information, and REUSE.toml holds license exceptions for the REUSE tool. The README file itself carries an SPDX-License-Identifier of CC-BY-4.0, while the Makefile carries Apache-2.0. The repository metadata reports NOASSERTION, which matches a tree where different files carry different terms. Check the per-file headers before reusing anything.

How this differs from the Vulkan SDK and from tutorials

The Vulkan SDK is a distribution: headers, loader, validation layers, and tools, packaged for installation. Vulkan-Docs is the upstream source those distributions derive their headers and specification text from. If you want to compile and run a Vulkan program, the SDK is the right starting point, and the README here does not claim to be one.

Tutorials are a different category again. They teach the API by example, while this repository defines it normatively. A tutorial can be out of date with the specification; the specification in chapters/ and appendices/ is the document a driver author is held to. If a tutorial and the spec disagree, the spec wins, and this is where you read it.

The third alternative is the XML registry on its own. Some binding and tooling projects consume xml/vk.xml without ever rendering the specification. If that is your use case, you can work from the registry and skip the Asciidoctor build entirely, which avoids the toolchain requirement that BUILD.adoc describes.

Maintenance, contribution, and licence checks before you fork

The repository is not archived, and the last push was on 2026-09-23, so the tree is current as of that date. ChangeLog.adoc tracks each public Vulkan spec update and ChangeLogSC.adoc does the same for Vulkan SC, which gives you a way to see what changed between versions without diffing the whole tree.

Contributions have their own rules. CONTRIBUTING.adoc states the requirements for external contributions, and the style/ directory holds the sources for the Vulkan Documentation and Extensions: Procedures and Conventions, referred to as the styleguide. Extension design documents live under proposals/ and the antora/ directory is described as a staging area for the docs.vulkan.org Antora proposals and spec modules. If you plan to submit an extension, read the styleguide before writing prose, because the conventions there govern the markup and terminology.

Upgrade cost is mostly toolchain cost. There is no released package to bump; you pull the branch and rebuild. The main thing to verify first is that your Asciidoctor toolchain matches BUILD.adoc, and that your VERSIONS and EXTENSIONS lists are complete and ordered as the Makefile requires. Licence-wise, the split between CC-BY-4.0 on README.adoc, Apache-2.0 on the Makefile, and the per-file summary in LICENSE.adoc means you should confirm the terms of the specific files you intend to reuse rather than assuming one licence covers the tree.

Editorial conclusion

Adopt Vulkan-Docs if you need the normative specification text, the XML API registry, or extension design documents, and if you can install the Asciidoctor toolchain described in BUILD.adoc. Do not clone it expecting a rendering library, a tutorial, or a Vulkan SDK; those live elsewhere, and the repository README points only to READMEVK.adoc and READMESC.adoc for API-specific documentation. Before relying on a build, verify that your Asciidoctor toolchain matches what BUILD.adoc requires and that you know which VERSIONS and EXTENSIONS values you passed on the make command line, since the Makefile converts them into generator arguments and an attributes file.

Frequently asked questions

Official sources

1. Issues
2. KhronosGroup/Vulkan-Docs on GitHub
3. README