386 lines
15 KiB
Plaintext
386 lines
15 KiB
Plaintext
= 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.
|