203 lines
8.2 KiB
Plaintext
203 lines
8.2 KiB
Plaintext
= Vulkan^(R)^ API Registry Build Instructions and Notes
|
|
|
|
Jon Leech
|
|
|
|
* <<intro,Introduction>>
|
|
* <<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` and the API Asciidoc include files used by the Vulkan
|
|
Specification and Reference Pages.
|
|
|
|
When changes to the header or the includes are needed, follow this workflow.
|
|
Normally changes are needed only when defining a new extension or core
|
|
version of the API.
|
|
|
|
* Create a git branch to work in locally
|
|
* Edit `vk.xml`
|
|
* `make ; make test`
|
|
** This generates headers in `../include/vulkan` including `vulkan_core.h`
|
|
and a set of platform-dependent headers `vulkan_<platform>.h`.
|
|
* `(cd .. && make generated)`
|
|
** This generates asciidoc includes for the spec. There are many ways to
|
|
invoke the Makefile in the spec directory; this simple recipe only
|
|
generates includes for the core Vulkan API without any extensions.
|
|
* 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 specification
|
|
branch (`master`) or other appropriate target.
|
|
|
|
For a detailed description of the schema, go to `..` and `make registry`,
|
|
which generates $(OUTDIR)/registry.html. This 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.
|
|
|
|
|
|
[[files]]
|
|
== Files
|
|
|
|
* Makefile - generates headers and extension loader sources from XML (see
|
|
<<targets,Makefile Targets>> below).
|
|
* vk.xml - XML API description.
|
|
* registry.rnc - RelaxNG compact schema for validating XML against the
|
|
schema.
|
|
* Python scripts in ../scripts/ which operate on vk.xml.
|
|
** ../scripts/genvk.py - Python script to generate vulkan_core.h and other
|
|
targets.
|
|
** ../scripts/reg.py - Python tools to read XML file and convert it into C
|
|
headers.
|
|
** ../scripts/generator.py - output generator base class.
|
|
** ../scripts/cgenerator.py - C header output generator.
|
|
** ../scripts/docgenerator.py - Asciidoc interface language include
|
|
generator.
|
|
** ../scripts/extensionmetadocgenerator.py - Generator for Asciidoc
|
|
extension descriptions in spec appendices.
|
|
** ../scripts/hostsyncgenerator.py - Asciidoc host sync table generator.
|
|
** ../scripts/pygenerator.py - Generates python encoding of the API
|
|
description.
|
|
** ../scripts/validitygenerator.py - Asciidoc validity language generator.
|
|
* ../include/vulkan/vulkan_core.h - Generated Vulkan non-platform API
|
|
header.
|
|
* ../include/vulkan/vulkan_<platform>.h - Generated Vulkan platform API
|
|
headers.
|
|
* ../scripts/indexExt.py - generate HTML index of all extensions for
|
|
inclusion into the Vulkan registry index page.
|
|
* ../scripts/extDependency.py - generate extension dependencies in Bash
|
|
and Python form for use when building the specification.
|
|
|
|
[[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. Usually done when preparing to merge
|
|
to `master` branch via ```make clean ; make install```.
|
|
|
|
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
|
|
----
|
|
|
|
|
|
[[linux]]
|
|
== Linux Software Depencies
|
|
|
|
These are the minimum versions of required tools in a Debian 8 development
|
|
environment. Earlier versions *may* work, but unless they are verified by
|
|
someone else, there's no way to know that:
|
|
|
|
* Python 3 (`python3`, version: 3.4.2)
|
|
* pass:[g++] and gcc (`g++-4.9` / `gcc-4.9`, version: 4.9.2-10 - gcc 4.8
|
|
also reported to work)
|
|
* GNU make (`make` version: 4.0.8-1; older versions probably OK)
|
|
* Jing (`jing` version: 20131210+dfsg+1-1; needed only for optional XML
|
|
validation)
|
|
|
|
|
|
[[windows]]
|
|
== Windows Software Dependencies
|
|
|
|
Using the Windows 10 Ubuntu subsystem, if available, is probably the most
|
|
pleasant way of building. Cygwin64 is also a viable approach.
|
|
|
|
On native Windows without a Linux emulation environment, one way to build on
|
|
Windows is:
|
|
|
|
* Install python (32-bit works great): https://www.python.org/downloads/
|
|
* Ensure the pip module is installed (should be by default)
|
|
* Run the `genvk.py` script in C:\PathToVulkan\src\specfile
|
|
** ```C:\PathToPython\python3.exe genvk.py vulkan_core.h```
|
|
|
|
|
|
[[history]]
|
|
== Revision History
|
|
|
|
* 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.
|