= Vulkan Specification Build Instructions and Notes = * <> * <> * <> * <> * <> * <> * <> * <> (general and platform-specific) * <> [[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 <> 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 <> 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 +++<>+++ command... [[depends]] == Software Dependencies == This section describes the software components used by the Vulkan spec toolchain. under the <> below, then describes specific considerations for Windows environments using Cygin under <> [[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.