Vulkan-Docs/src/spec/README.adoc

= 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.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 done only when defining a new extension, or when adding
missing validity language to existing APIs.

* Create a git branch to work in locally
* Edit vk.xml
* make ; make test
** This generates ../vulkan/vulkan.h
* make install doc_install
** This generates header and registry documentation.
* (cd ../../doc/specs/vulkan && 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 header and/or includes are correct.
* Commit your changes to your local git branch, push to the Khronos git
  server, and create a merge request against the specification branch
  ("1.0") or other appropriate target.

See 'registry.txt' for a detailed description of the schema, and 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 header and asciidoc includes from XML (see
  <<targets,Makefile Targets>> below).
* vk.xml - XML API description.
* genvk.py - Python script to generate vulkan.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.
** hostsyncgenerator.py - Asciidoc host sync table generator.
** pygenerator.py - Generates python encoding of the API description.
** validitygenerator.py - Asciidoc validity language generator.
* ../vulkan/vulkan.h - Generated Vulkan header.


[[targets]]
== Makefile Targets ==

* install or ../vulkan/vulkan.h (default target) - regenerate
  ../vulkan/vulkan.h .
* doc_install - generates detailed description of the XML schema from
  registry.txt in $(OUTDIR)/registry.html . In general this should be left
  until a branch is merged to 1.0.
* test - make sure ../vulkan/vulkan.h compiles. Important!
* validate - validate vk.xml against the schema. Requires installing 'jing'
  (see <<linux,Software Dependencies>> below).
* clean_dirt - remove intermediate files.
* clean - remove generated files. Usually done when preparing to merge to
  1.0 via 'make clean ; make install doc_install'.

If you have trouble running the Makefile on your platform, the following
steps will build vulkan.h and test that it compiles:

* # Regenerate header from XML
** python3 genvk.py ../vulkan/vulkan.h
* # Test the resulting header compiles
** gcc -Wall -c -I.. test.c
** g++ -Wall -c -std=c++98 -I.. test.c
** g++ -Wall -c -std=c++11 -I.. test.c


[[linux]]
== Linux Software Depencies ==

These are the 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)
* g++/gcc 4.9 (g++-4.9 / gcc-4.9, version: 4.9.2-10 - gcc 4.8 also reported
  to work, just needs to support the -std=c++11 target)
* 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 ==

Instructions from Daniel Johnston, daniel.johnston 'at' intel.com. There are
a variety of ways to run on Windows, this is just one.

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


[[history]]
== Revision History ==

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