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