registry/vulkan/xml/README.adoc - platform/external/gfxstream-protocols - Git at Google

 = 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.
   * genvk.py - Python script to generate vulkan_core.h and other targets.
   * readme.txt - Source for detailed description of the XML schema.
   * registry.rnc - RelaxNG compact schema for validating XML against the
     schema.
   * reg.py - Python tools to read XML file and convert it into C headers.
   * generator.py - output generator base class.
   ** cgenerator.py - C header output generator.
   ** docgenerator.py - Asciidoc interface language include generator.
   ** extensionmetadocgenerator.py - Generator for Asciidoc extension
      descriptions in spec appendices.
   ** extensionStubSource.py - Simple loader C source generator. Unsupported.
   ** hostsyncgenerator.py - Asciidoc host sync table generator.
   ** pygenerator.py - Generates python encoding of the API description.
   ** 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.
   * indexExt.py - generate HTML index of all extensions for inclusion into
     the Vulkan registry index page.
   * 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```.
   * `extloader` - generate simple extension loader source code in
     `../src/vulkan_ext/`. Unsupported.

 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 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

   * 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.
	= 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.
	* genvk.py - Python script to generate vulkan_core.h and other targets.
	* readme.txt - Source for detailed description of the XML schema.
	* registry.rnc - RelaxNG compact schema for validating XML against the
	schema.
	* reg.py - Python tools to read XML file and convert it into C headers.
	* generator.py - output generator base class.
	** cgenerator.py - C header output generator.
	** docgenerator.py - Asciidoc interface language include generator.
	** extensionmetadocgenerator.py - Generator for Asciidoc extension
	descriptions in spec appendices.
	** extensionStubSource.py - Simple loader C source generator. Unsupported.
	** hostsyncgenerator.py - Asciidoc host sync table generator.
	** pygenerator.py - Generates python encoding of the API description.
	** 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.
	* indexExt.py - generate HTML index of all extensions for inclusion into
	the Vulkan registry index page.
	* 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```.
	* `extloader` - generate simple extension loader source code in
	`../src/vulkan_ext/`. Unsupported.

	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 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

	* 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.