Vulkan-Docs/doc/specs/vulkan/README.adoc

= Vulkan Specification Build Instructions and Notes =

* <<intro,Introduction>>
* <<building,Building the spec>>
* <<macros,Our asciidoc macros>>
* <<refpages,Reference Pages>>
* <<styles,Our stylesheets>>
* <<equations,Imbedding equations>>
* <<anchors,Anchors and xrefs>>
* <<depends,Software dependencies>> (general and platform-specific)
* <<history,Revision history>>


[[intro]]
== Introduction ==

This README describes important stuff for getting the Vulkan API
specification and reference pages building properly.


[[building]]
== Building The Spec ==

Assuming you have all the right tools installed (see <<depends,Software
Dependencies>> below), go to
+...path-to-git-repo/vulkan/doc/specs/vulkan+ .

If the default value of ASCIIDOC is not correct for the
+asciidoc+ script on your platform, change it via
environment variables, command line options, or by modifying the
+Makefile+. The default script names have +.py+ suffixes. These suffixes
should be removed for Linux platforms, and possibly for other
non-Windows environments.

    $ make all

or equivalently:

    $ make xhtml pdf styleguide manhtml manpdf manhtmlpages checkinc checklinks

will generate a variety of targets in the directory specified by the
Makefile variable +$(OUTDIR)+ (by default, +../../../out/1.0+). The
checked-in file +../../../out/1.0/index.html+ links to all these
targets, or they can individually be found as follows:

* API spec:
** +xhtml+ - Single-file XHTML in +$(OUTDIR)/xhtml/vkspec.html+
** +pdf+ - PDF in +$(OUTDIR)/pdf/vkspec.pdf+
* ``Vulkan Documentation and Extensions'' guide:
** +styleguide+ - Single-file HTML5 in +$(OUTDIR)/styleguide.html+
* Reference pages:
** +manhtml+ - Single-file HTML in +$(OUTDIR)/apispec.html+
** +manpdf+ - Single-file PDF in +$(OUTDIR)/apispec.html+
** +manhtmlpages+ - File-per-entry-point HTML in +$(OUTDIR)/man/html/*+
* Validator output:
** +checkinc+ - List of commands, structs, etc. missing from the API
   spec in +$(OUTDIR)/checks/notInSpec.txt+
** +checklinks+ - Validator script output for API spec in
   +$(OUTDIR)/checks/specErrs.txt and for reference pages in
   +$(OUTDIR)/checks/manErrs.txt+

Once you have the basic build working, an appropriate parallelization
option to make, such as

    $ make -j 8

may significantly speed up the reference page builds.

If your asciidoc installation does not put the stylesheets and xsl files in
the standard +/etc/asciidoc/dblatex+ directory, set the environment variable
+DBLATEXPREFIX+ to the path to that directory (the one containing the
+asciidoc-dblatex.xsl+ and +asciidoc-dblatex.sty+ files installed with
asciidoc).

The +manpages+ target is deprecated, as the resulting Unix man pages have
issues with content like embedded latexmath: constructs, but is still
available for third parties wishing to generate them:

* +manpages+ - File-per-entry-point nroff source in +$(OUTDIR)/man/3/*+


[[building-extensions]]
=== Building With Extensions Included ===

As of version 1.0.25 of the Specification, we are using a ``single-branch
model'', where extensions are included in the same +1.0+ branch as the core
Specification, instead of the older model where each extension lived in a
separate Git branch. Whether a given extension is generated in the output
depends on asciidoc and generator script options being specified.

The extensions included are those specified as a space-separated list of
extension names (e.g. +VK_KHR_surface+) in the Makefile variable
+$(EXTENSIONS)+, normally set on the make command line. When changing
the list of extensions, it is critical to remove all generated files
using the +clean_generated+ Makefile target, as the contents of
generated files depends on +$(EXTENSIONS)+. There are two helper scripts
which clean these files and then build one or more specified targets for
specified extensions:

* +makeExt+ - generate outputs with a single extension enabled. Usage is
  +makeExt extension-name target(s)+, where +extension-name+ is the
  extension name string, such as +VK_EXT_debug_report+.
* +makeKHR+ - generate outputs with all Khronos (+VK_KHR_*+) extensions
  enabled. Usage is +makeKHR target(s)+.

The Makefile variable +$(APITITLE)+ defines an additional string which is
appended to the specification title. When building with extensions enabled,
this should be set to something like +(with extension VK_extension_name)+.
The +makeExt+ and +makeKHR+ scripts already do this.


[[building-test]]
=== Alternate and Test Builds ===

If you are just testing asciidoc formatting, macros, stylesheets, etc.,
it is much faster to edit +vkspec.txt+ to comment out most of the chapter
includes.

In addition to the XHTML and PDF targets, there is also a single-file HTML5
target, +html+, which generates output directly from asciidoc without going
through Docbook. This is quicker to generate, but formatting and section
numbers aren't neccessarily consistent with the other builds and it is not for
publication - just testing. The +html+ target will generate the file
+$(OUTDIR)/html/vkspec.html+ .


=== Rebuilding The Generated Images ===

There are some images in the +images/+ directory which are maintained in one
format but need to be converted to another format for corresponding types of
output. Most are SVG converted to PDF, some are PPT converted to PDF
converted to SVG. SVG and PDF forms are needed for the HTML and PDF output
formats, respectively.

These files are not automatically converted by the Makefile. Instead, all
output forms required are checked into +images/+ . On the rare occasions that
someone changes a source document and needs to regenerate the other forms:

    cd images
    make


[[macros]]
== Our Asciidoc Macros ==

We use a bunch of custom macros in the reference pages and API spec asciidoc
sources. The validator scripts rely on these macros as part of their sanity
checks, and you should use the macros whenever referring to an API command,
struct, token, or enum name, so the documents are semantically tagged and
more easily verifiable.

The supported macros are defined in +config/vkspec.conf+ (for the API spec)
and +config/manpages.conf+ (for the reference pages).

The tags used are described in the style guide (+styleguide.txt+).

We will eventually tool up the spec and ref pages to the point that anywhere
there's a type or token referred to, clicking on (or perhaps hovering over)
it in the HTML view and be taken to the definition of that type/token. That
will take some more plumbing work to tag the stuff in the autogenerated
include files, and do something sensible in the spec (e.g. resolve links to
internal references).

Most of these macros deeply need more intuitive names.


[[refpages]]
== Reference Pages ==

Prior to the 1.0.20 update of the API spec, the reference pages in +man/+
were handwritten, incomplete, and often way out of date with respect to the
spec.

Our initial effort to address this was to tag the API spec to help identify
boundaries of language talking about different commands, structures,
enumerants, and other types, then use a set of Python scripts to
automatically extract that language into the corresponding ref page. Pages
without corresponding content in the API spec are generated automatically,
when possible.

This has generated a semantically complete set of ref pages. Although they
are still far from ideal, they now fully document the API, and will stay in
sync with it.

If for some reason you want to regenerate the ref pages from scratch
yourself, you can do so by

    $ rm man/apispec.txt
    $ make apispec.txt

The +genRef.py+ script will generate many warnings, but most are just
reminders that some pages are automatically generated. If everything is
working correctly, all the +man/*.txt+ files will be regenerated, but their
contents will not change.


[[styles]]
== Our stylesheets ==

NOTE: Section mostly TBD.

There is a Vulkan-specific XHTML CSS stylesheet in
+config/vkspec-xhtml.css+ . It started as a clone of the default
Asciidoc stylesheet, but added some new features. Similar CSS in
+config/vkman.css+ is used for the reference pages.


=== Marking Changes ===

There is the start of support for marking added, removed, and changed text
in the spec body. Currently this is supported *only* in the XHTML targets
(+xhtml+ and +chunked+), and *only* for paragraphs and spans of words.

Added, removed, and changed material is marked with the asciidoc *roles*
named _added_, _removed_, and _changed_ respectively. They can be used to
mark an entire paragraph, as follows:

    [role="change"]
    This paragraph shows change markings.

Or a few words in a sentence, as follows:

    This sentence contains [added]#some added words# and [removed]#some
    removed words#.

The formatting of these roles text depends on the stylesheet. Currently it
all three roles are red text, and the "removed" role is also strike-through
text.

We don't use this capability yet; it's just a proof of concept. It would
be a huge amount of work to insert this markup automatically for each
spec update, and it would be very difficult to do automatically based on
git diffs.



=== Marking Normative Language ===

There is support for marking normative language in the document. Currently
this is supported *only* in the XHTML targets (+xhtml+ and +chunked+).

Normative language is marked with the asciidoc *role* named _normative_.
It can be used to mark entire paragraphs or spans of words, in the
same fashion as change markings (described above). In addition, the
normative terminology macros, such as must: and may: and cannot:,
always use this role.

The formatting of normative language depends on the stylesheet. Currently it
just comes out in purple. We may add a way to disable this formatting at
build time.


[[equations]]
== Imbedding Equations

Equations should be written using the latexmath: inline and block macros.
The contents of the latexmath: blocks should be LaTeX math notation,
surrounded by appropriate delimiters - pass:[$$], +++\[\\]+++, pass:[\(\)],
or pass:[\begin{env}/\end{env}] math environments such as pass:[{equation*}]
or pass:[{align*}].

The asciidoc macros and configuration files, as well as the dblatex
customization layers, have been modified significantly so that LaTeX math is
passed through unmodified to all HTML output forms (using the MathJax engine
for real-time rendering of equations) and to dblatex for PDF output.

The following caveats apply:

* The special characters +<+ , +>+ , and +&+ can currently be used only in
  +++[latexmath]+++ block macros, not in +++latexmath:[]+++ inline macros.
  Instead use +\lt+ for +<+ and +\gt+ for +>+. +&+ is an alignment construct
  for multiline equations, and should only appear in block macros anyway.
* AMSmath environments (e.g. pass:[\begin{equation*}], pass:[{align*}],
  etc.) can be used, to the extent MathJax supports them.
* When using AMSmath environments, do *not* also surround the equation block
  with +++\[\\]+++ brackets. That is not legal LaTeX math and will break the
  PDF build. It is good practice to make sure all spec targets build
  properly before proposing a merge to master.
* Arbitrary LaTeX constructs cannot be used with MathJax. It is an equation
  renderer, not an full LaTeX engine. So imbedding LaTeX like \Large or
  pass:[\hbox{\tt\small VK\_FOO}] may not work in any of the HTML backends,
  and should be avoided.


[[anchors]]
== Asciidoc Anchors And Xrefs

In the API spec, sections can have anchors (labels) applied with the
following syntax. In general the anchor should immediately precede the
chapter or section title and should use the form
'+++[[chapter-section-label]]+++'. For example,

For example, in chapter +synchronization.txt+:

++++
[[synchronization-primitives]]
Synchronization Primitives
++++

Cross-references to those anchors can then be generated with, for example,

++++
See the <<synchronization-primitives>> section for discussion
of fences, semaphores, and events.
++++

You can also add anchors on arbitrary paragraphs, using a similar naming
scheme.

Anything whose definition comes from one of the autogenerated API include
files (+.txt+ files in the directories +basetypes+, +enums+, +flags+,
+funcpointers+, +handles+, +protos+, and +structs+) has a corresponding
anchor whose name is the name of the function, struct, etc. being defined.
Therefore you can say something like:

    Fences are used with the +++<<vkQueueSubmit>>+++ command...


[[depends]]
== Software Dependencies ==

This section describes the software components used by the Vulkan spec
toolchain. under the <<depends-general,General Dependencies>> below, then
describes specific considerations for Windows environments using Cygin under
<<depends-cygwin,Cygwin Dependencies>>


[[depends-general]]
=== General Dependencies ===

These are versions of required tools in one of the editors' development
environment (Debian 8, shown as Debian package names). Earlier versions
*may* work but unless they are verified by someone else, there's no way to
know that. Later versions should work.

  - GNU make (make version: 4.0.8-1; older versions probably OK)
  - Asciidoc (asciidoc version: 8.6.9-3)
  - Python 3 (python, version: 3.4.2)
  - Git command-line client (git, version: 2.1.4)
    Only needed if regenerating specversion.txt. Any version supporting the
    operations
  -- +git symbolic-ref --short HEAD+ and
  -- +git log -1 --format="%H"+ should work).
  - Docbook LaTeX toolchain (dblatex, version: 0.3.5-2)
  - Source code highlighter (source-highlight, version: 3.1.7-1+b1)
  - LaTeX distribution (texlive, version: 2014.20141024-2)


[[depends-cygwin]]
=== Cygwin Dependencies ===

The cygwin installer is at http://www.cygwin.org. Use the 64-bit version,
because the 32-bit version does not include the latest version of asciidoc
required for this project.

Required Cygwin packages (current version):

* Devel/make (4.1-1)
* Python/python (2.7.10-1) - Needed for asciidoc toolchain
* Python/python3 (3.4.3-1)
* Python/python3-lxml (3.4.4-1) - Needed for generating vulkan.h
* Text/asciidoc (8.6.8-1)
* Text/dblatex (0.3.4-1)
* Text/source-highlight (3.1.8-1)

Optional Cygwin packages (current version):

* Devel/gcc-core (4.9.3-1) - Needed for validating generated headers
* Devel/gcc-g++ (4.9.3-1) - Needed for validating generated headers
* Devel/git (2.5.1-1) - Needed for updating specversion.txt


[[history]]
== Revision History

* 2016/08/25 - Update for the single-branch model.
* 2016/07/10 - Update for current state of spec and ref page generation.
* 2015/11/11 - Add new can: etc. macros and DBLATEXPREFIX variable.
* 2015/09/21 - Convert document to asciidoc and rename to README.md
  in the hope the gitlab browser will render it in some fashion.
* 2015/09/21 - Add descriptions of LaTeX+MathJax math support for all
  output formats.
* 2015/09/02 - Added Cygwin package info.
* 2015/09/02 - Initial version documenting macros, required toolchain
  components and versions, etc.