Vulkan-Docs/src/spec

Table of contents:
    INTRODUCTION
    FILES
    MAKEFILE TARGETS
    SOFTWARE DEPENDENCIES
    RUNNING ON WINDOWS
    CHANGE LOG

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 ref pages and
Specification.

When patches to the header or the includes are needed, follow this workflow:

  - Create a git branch to work in locally
  - Edit vk.xml
  - make ; make test
    (this just generates ../vulkan/vulkan.h)
  - make full_install
    (this generates all targets)
  - Repeat until the header and/or includes are correct
  - Commit your changes to your local git branch
  - Push the branch to the git server and create a merge request against the
    specification branch ("1.0") or other appropriate target.

See 'readme.pdf' 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 very nice
lxml.etree package for processing XML.

    Jon Leech

FILES
-----

    Makefile - generates header and JSON from XML (see below)
    vk.xml - XML API description
    genvk.py - Python script to generate vulkan.h and other targets.
    readme.tex - Source for detailed description of the XML schema
    readme.pdf - Generated document describing the XML schema and giving
        some examples of making simple changes to add API features
    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 for C. Others are possible, although
        vk.xml contains C-isms which would have to be factored out.
    ../vulkan/vulkan.h - Generated header

MAKEFILE TARGETS
----------------

    install or ../vulkan/vulkan.h (default target) - regenerate vulkan.h in
        ../vulkan .
    vulkan-docs - regenerate spec/ref page API include .txt files and
        install under ../../doc/specs/vulkan/*/ . In general, this should be
        left until a branch is merged to master.
    full_install - combination of 'install' and 'vulkan-docs' targets.
        Again, in general this should be left until a branch is merged to
        master.
    readme.pdf - detailed description of the XML schema. Normally this need
        not be rebuilt unless you're changing the schema and updating
        readme.tex.
    test - make sure ../vulkan/vulkan.h compiles. Important!
    validate - validate vk.xml against the schema. Requires 'jing' tool
        installed.
    clobber - remove generated and cache files, including the API include
        files. Usually done while merging to master via 'make clobber ; make
        full_install'

    If you have trouble running the Makefile on your platorm, try using
    the command line:

    # 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
    # Then commit/push changes to git

SOFTWARE DEPENDENCIES
---------------------

RUNNING ON LINUX
----------------

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)
  - Python 3 version of lxml package (python3-lxml, version: 3.4.0-1)
  - 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)

RUNNING ON WINDOWS
------------------

(Instructions from Daniel Johnston, daniel.johnston@intel.com)

1) Install python (32-bit works great): https://www.python.org/downloads/
  a) Ensure the pip module is installed (should be by default)
2) Download the lxml package from
    http://www.lfd.uci.edu/~gohlke/pythonlibs/#lxml
  a) 32-bit latest is: lxml-3.4.4-cp34-none-win32.whl
3) Install the lxml package:
    C:\PathToPython\python.exe pip install c:\PathToDownload\lxml-3.4.4-cp34-none-win32.whl
4) Run the genvk.py script in C:\PathToVulkan\src\specfile :
  a) C:\PathToPython\python.exe genvk.py vulkan.h

CHANGE LOG
----------

2015/06/01

    The header that's 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's 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.