diff options
Diffstat (limited to 'codegen/vulkan/xml/README.adoc')
| -rw-r--r-- | codegen/vulkan/xml/README.adoc | 184 |
1 files changed, 184 insertions, 0 deletions
diff --git a/codegen/vulkan/xml/README.adoc b/codegen/vulkan/xml/README.adoc new file mode 100644 index 00000000..1fee04d4 --- /dev/null +++ b/codegen/vulkan/xml/README.adoc @@ -0,0 +1,184 @@ +// 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. |