codegen/vulkan/vulkan-docs-next/xml/README.adoc - platform/hardware/google/gfxstream - Git at Google

 // Copyright 2014-2023 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 header files, 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 validate install test`
   ** This validates the XML files against the schema description; generates
      headers in `../gen/include/vulkan` including `vulkan_core.h` and a set
      of platform-dependent headers `vulkan_<platform>.h`; and runs a simple
      compilation test of the headers.
   * `(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.

 === Video Headers

 In addition to `vk.xml` this directory also includes `video.xml`.
 This is a similarly structured XML file used to produce headers for
 structures and other types (`StdVideo*`) associated with externally defined
 video standards.
 While these data types are passed into some of the Vulkan Video extension
 APIs, they are not treated as part of the Vulkan API.
 This is why they are defined in a separate XML file.

 The `validate` and `install` targets described above also generate the
 `StdVideo*` headers in `../gen/include/vk_video`.
 A separate test target, `vtest`, can be used as a simple compilation test of
 the `StdVideo*` headers.


 [[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.
   * `video.xml` - `StdVideo*` API description.
   * `../gen/include/vk_video/vulkan_video*.h` - Generated `StdVideo*` API
     headers.


 [[targets]]
 == Makefile Targets

   * `install` (default target) - regenerate Vulkan and `StdVideo*` header
     files in `../gen/include/`.
   * `test` - make sure Vulkan headers compile.
     *Important!* Can also be used to test if platform headers compile by
     specifying `make TESTDEFS=-DVK_USE_PLATFORM_<PLATFORM>_<AUTHORID> test`.
   * `vtest` - make sure `StdVideo*` headers compile.
   * `validate` - validate `vk.xml` and `video.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 the Vulkan headers and test that `vulkan_core.h` compiles:

 [source,sh]
 ----
 # Regenerate header from XML
 python3 ../scripts/genvk.py -registry vk.xml -o ../gen/include/vulkan vulkan_core.h
 # Verify that the resulting header compiles
 gcc -Wall -std=c99 -c -I../gen/include -I../tests ../tests/htest.c
 g++ -Wall -std=c++98 -c -I../gen/include -I../tests ../tests/htest.c
 rm -f htest.o
 ----


 [[history]]
 == Revision History

   * 2021-12-13 -
     Add `video.xml` for `StdVideo*` APIs and headers.
   * 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 -
     Do not 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 new default 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.
	// Copyright 2014-2023 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 header files, 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 validate install test`
	** This validates the XML files against the schema description; generates
	headers in `../gen/include/vulkan` including `vulkan_core.h` and a set
	of platform-dependent headers `vulkan_<platform>.h`; and runs a simple
	compilation test of the headers.
	* `(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.

	=== Video Headers

	In addition to `vk.xml` this directory also includes `video.xml`.
	This is a similarly structured XML file used to produce headers for
	structures and other types (`StdVideo*`) associated with externally defined
	video standards.
	While these data types are passed into some of the Vulkan Video extension
	APIs, they are not treated as part of the Vulkan API.
	This is why they are defined in a separate XML file.

	The `validate` and `install` targets described above also generate the
	`StdVideo*` headers in `../gen/include/vk_video`.
	A separate test target, `vtest`, can be used as a simple compilation test of
	the `StdVideo*` headers.


	[[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.
	* `video.xml` - `StdVideo*` API description.
	* `../gen/include/vk_video/vulkan_video.h` - Generated `StdVideo` API
	headers.


	[[targets]]
	== Makefile Targets

	* `install` (default target) - regenerate Vulkan and `StdVideo*` header
	files in `../gen/include/`.
	* `test` - make sure Vulkan headers compile.
	Important! Can also be used to test if platform headers compile by
	specifying `make TESTDEFS=-DVK_USE_PLATFORM_<PLATFORM>_<AUTHORID> test`.
	* `vtest` - make sure `StdVideo*` headers compile.
	* `validate` - validate `vk.xml` and `video.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 the Vulkan headers and test that `vulkan_core.h` compiles:

	[source,sh]
	----
	# Regenerate header from XML
	python3 ../scripts/genvk.py -registry vk.xml -o ../gen/include/vulkan vulkan_core.h
	# Verify that the resulting header compiles
	gcc -Wall -std=c99 -c -I../gen/include -I../tests ../tests/htest.c
	g++ -Wall -std=c++98 -c -I../gen/include -I../tests ../tests/htest.c
	rm -f htest.o
	----


	[[history]]
	== Revision History

	* 2021-12-13 -
	Add `video.xml` for `StdVideo*` APIs and headers.
	* 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 -
	Do not 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 new default 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.