185 lines
7.0 KiB
Plaintext
185 lines
7.0 KiB
Plaintext
// Copyright 2014-2021 The Khronos Group Inc.
|
|
//
|
|
// SPDX-License-Identifier: CC-BY-4.0
|
|
|
|
= Vulkan^(R)^ API Registry Build Instructions and Notes
|
|
|
|
Jon Leech
|
|
|
|
* <<intro,Introduction>>
|
|
* <<build,Build Environment>>
|
|
* <<files,Files>>
|
|
* <<targets,Makefile Targets>>
|
|
* <<linux,Linux Software Dependencies>>
|
|
* <<windows,Windows Software Dependencies>>
|
|
* <<history,Revision History>>
|
|
|
|
|
|
[[intro]]
|
|
== Introduction
|
|
|
|
This is the Vulkan XML API Registry. It is used to generate the canonical
|
|
`vulkan_core.h`, the API Asciidoc include files used by the Vulkan
|
|
Specification and Reference Pages, and many other types of generated files.
|
|
|
|
When changes to generated files are needed, follow this workflow.
|
|
Normally changes are needed only when defining a new extension or core
|
|
version of the API.
|
|
|
|
* Clone the repository and create a branch to work in locally
|
|
* Edit `vk.xml`
|
|
* `make install test`
|
|
** This generates headers in `../gen/include/vulkan` including
|
|
`vulkan_core.h` and a set of platform-dependent headers
|
|
`vulkan_<platform>.h`.
|
|
* `(cd .. && make generated)`
|
|
** This uses `vk.xml` to generate asciidoc includes and other intermediate
|
|
files in `../gen` for the specification build.
|
|
There are many ways to invoke the Makefile in `..`.
|
|
This simple recipe only generates includes for the core Vulkan API
|
|
without any extensions.
|
|
See `../BUILD.adoc` for more.
|
|
* Repeat until the headers and/or includes are correct
|
|
* Commit your changes to your local git branch, push to your upstream git
|
|
server (your personal repository clone of KhronosGroup/Vulkan-Docs on
|
|
Github, for people outside Khronos; the Khronos member gitlab server,
|
|
otherwise), and create a pull or merge request against the default
|
|
branch (currently `main`) or other appropriate target.
|
|
|
|
For a detailed description of the schema, go to `..` and `make registry`,
|
|
which generates `gen/out/registry.html`.
|
|
This document also includes some examples of how to make simple changes in
|
|
the API via the XML.
|
|
|
|
The generator scripts are written in Python 3, using the `etree` package for
|
|
processing XML.
|
|
See `../scripts/README.adoc` for script descriptions.
|
|
|
|
|
|
[[build]]
|
|
== Build Environment
|
|
|
|
We strongly recommend using the Khronos-provided Docker image, which has all
|
|
needed build tools pre-installed.
|
|
See `../BUILD.adoc` for details.
|
|
|
|
It is possible to construct your own build environment on Linux, Windows, or
|
|
MacOS by following the recipe in the Dockerfile for the Khronos-provided
|
|
Docker image.
|
|
|
|
|
|
[[files]]
|
|
== Files
|
|
|
|
* `vk.xml` - XML API description.
|
|
* `registry.rnc` - RelaxNG compact schema for validating XML against the
|
|
schema.
|
|
* `Makefile` - generates headers from `vk.xml` (see <<targets,Makefile
|
|
Targets>> below).
|
|
* `../gen/include/vulkan/vulkan_core.h` - Generated Vulkan non-platform
|
|
API header.
|
|
* `../gen/include/vulkan/vulkan_<platform>.h` - Generated Vulkan platform
|
|
API headers.
|
|
|
|
|
|
[[targets]]
|
|
== Makefile Targets
|
|
|
|
* `install` (default target) - regenerate header files in
|
|
`../include/vulkan`.
|
|
* `test` - make sure `../include/vulkan/vulkan_core.h` compiles.
|
|
*Important!* Can also be used to test if platform headers compile by
|
|
specifying `make TESTDEFS=-DVK_USE_PLATFORM_<PLATFORM>_<AUTHORID> test`.
|
|
* `validate` - validate `vk.xml` against the schema. Requires installing
|
|
`jing` (see <<linux,Software Dependencies>> below). Also important!
|
|
* `clean_dirt` - remove intermediate files.
|
|
* `clean` - remove generated files.
|
|
|
|
Generated files can be created in a directory other than the default
|
|
`../gen/` by setting the Makefile variable `GENERATED` to that directory
|
|
path.
|
|
|
|
If you have trouble running the Makefile on your platform, the following
|
|
steps will build `vulkan_core.h` and test that it compiles:
|
|
|
|
[source,sh]
|
|
----
|
|
# Regenerate header from XML
|
|
python3 ../scripts/genvk.py -o ../include/vulkan vulkan_core.h
|
|
# Verify that the resulting header compiles
|
|
gcc -Wall -c -I../include testcore.c
|
|
g++ -Wall -c -std=c++98 -I../include testcore.c
|
|
g++ -Wall -c -std=c++11 -I../include testcore.c
|
|
----
|
|
|
|
|
|
[[history]]
|
|
== Revision History
|
|
|
|
* 2020-08-25 -
|
|
Update for new default branch (`main`).
|
|
* 2019/05/12 -
|
|
Bring up to date with changes in file paths and build tools.
|
|
* 2019/03/10 -
|
|
Update for script reorganization.
|
|
* 2018/05/21 -
|
|
Don't generate vulkan_ext.[ch] from the `install` target. Add a new
|
|
shortcut `extloader` target for people still using this code and needing
|
|
to regenerate it.
|
|
* 2018/03/13 -
|
|
Update for new directory structure.
|
|
* 2018/03/06 -
|
|
Update for Vulkan 1.1 release and `master` branch.
|
|
* 2015/09/18 -
|
|
Split platform-specific headers into their own vulkan_<platform>.h
|
|
files, move vulkan.h to vulkan_core.h, and add a new (static) vulkan.h
|
|
which includes appropriate combinations of the other headers.
|
|
* 2015/06/01 -
|
|
The header that is generated has been improved relative to the first
|
|
version. Function arguments are indented like the hand-generated header,
|
|
enumerant BEGIN/END_RANGE enums are named the same, etc. The ordering of
|
|
declarations is unlike the hand-generated header, and probably always
|
|
will because it results from a type/enum/function dependency analysis.
|
|
Some of this can be forced by being more explicit about it, if that is a
|
|
big deal.
|
|
* 2015/06/02 -
|
|
Per WG signoff, converted hex constant values to decimal (for
|
|
non-bitmasks) and VK_BIT macros to 'bitpos' attributes in the XML and
|
|
hex constants in the header. Updated schema to match. Changed <ptype>
|
|
tag to <type>.
|
|
* 2015/06/03 -
|
|
Moved into new 'vulkan' tree (did not bother preserving history in
|
|
previous repo). Added semantic knowledge about structs and unions to
|
|
<type> tags instead of just imbedding C struct definitions. Improved
|
|
registry.rnc schema a bit.
|
|
* 2015/06/07 -
|
|
Incorporate feedback from F2F including Python 3 and Windows fixes to
|
|
the scripts. Add documentation to readme.pdf. Fold in multiple merge
|
|
requests resulting from action items agreed at the F2F, to prepare
|
|
for everyone moving to XML instead of directly editing the header.
|
|
* 2015/06/20 -
|
|
Add vulkan-docs target and instructions for installing python3 and
|
|
python-lxml for Windows.
|
|
* 2015/08/13 -
|
|
Bring documentation up to date with Makefile targets (default is now
|
|
../include/vulkan.h).
|
|
* 2015/09/02 -
|
|
Update README with required (or known working) versions of toolchain
|
|
components.
|
|
* 2015/09/02 -
|
|
Move include/vulkan.h to vulkan/vulkan.h so #include "vulkan/vulkan.h"
|
|
is the normal usage (Bug 14576).
|
|
* 2016/02/12 -
|
|
Update README and remove old files to stage for public release.
|
|
* 2016/05/31 -
|
|
Remove dependency on lxml.
|
|
* 2016/07/27 -
|
|
Update documentation for changes to schema and generator scripts.
|
|
* 2016/08/26 -
|
|
Move README to an asciidoc file and update for the single-branch model.
|
|
Use 'clean' target to remove generated files in both spec source and
|
|
registry Makefiles.
|
|
* 2017/02/20 -
|
|
Move registry.txt (schema documentation) to the Vulkan spec source
|
|
directory and update the README here.
|