diff options
Diffstat (limited to 'codegen/vulkan/BUILD.adoc')
| -rw-r--r-- | codegen/vulkan/BUILD.adoc | 459 |
1 files changed, 459 insertions, 0 deletions
diff --git a/codegen/vulkan/BUILD.adoc b/codegen/vulkan/BUILD.adoc new file mode 100644 index 00000000..855b7d33 --- /dev/null +++ b/codegen/vulkan/BUILD.adoc @@ -0,0 +1,459 @@ +// Copyright 2014-2021 The Khronos Group Inc. +// SPDX-License-Identifier: CC-BY-4.0 + += Vulkan^(R)^ Specification Build Instructions and Notes +:toc2: +:toclevels: 2 + +ifdef::env-github[] +:note-caption: :information_source: +endif::[] + +[[intro]] +== Introduction + +This README describes how to build the Vulkan API specification, reference +pages, and/or other related targets. + +It documents how to set up your build environment, build steps and targets, +and contains some troubleshooting advice. + +[[building]] +== Building The Spec + +First, clone the Khronos Github repository containing the Vulkan +specification to your local Linux, Windows, or Mac PC. +The repository is located at https://github.com/KhronosGroup/Vulkan-Docs/. + +Next, install all the necessary build tools (see <<depends,Software +Dependencies>> below). +If you are using the <<depends-docker, Khronos-Provided Docker Image>>, +which we strongly recommend, then one way to build using the image (assuming +a Linux docker host) is: + + $ docker run --user `id -u`:`id -g` -it --rm \ + -v <vulkan-path>:/vulkan \ + khronosgroup/docker-images:asciidoctor-spec /bin/bash + +where <vulkan-path> is the path to the cloned repository. This runs the +image with the cloned repository under /vulkan and accesses it as a +specified user (set to your own user and group ID above), so that it doesn't +get filled with files owned by another user. + +Then in the running image, + + $ cd /vulkan + $ ./makeSpec -spec core html + +which builds an HTML5 specification output for the core Vulkan 1.2 +specification, with no extensions included, or + + $ ./makeSpec -spec all all + +which builds the spec targets `html`, `pdf`, `styleguide`, `registry`, +`manhtmlpages`, and `allchecks`, with *all* registered extensions included. + +There are many other ways of using the image, including inside a Continuous +Integration pipeline; locally with persistent Docker volume storage of the +repository; and so on. + +If you are not using our Docker image to build with, and you have a +<<depends-nondocker, Non-Docker Build Environment>> with the entire +toolchain installed, you can go to <vulkan-path> and invoke the same `make` +commands there. + +[NOTE] +.Note +==== + * While it's possible to invoke `make` directly, this is rarely + appropriate or useful. + Usually dozens to hundreds of build options must be set to specify the + desired set of extensions to include in the specification. + The `makeSpec` python script, which is discussed in more detail + <<building-extensions, below>>, simplifies this process for common + cases. + * The `all` target takes a long time to run, and generates outputs that + are irrelevant for most users. + The `html` target just generates the HTML output, which is often all + that's needed for spec bugfixes not involving extensions. + * The default `make` options build a Vulkan 1.2 specification with no + optional extensions. + * The `validusage` target is not built as part of the `all` target, due to + it needing to be built with all extensions enabled (`-spec all`). + Building the `validusage` target will fail otherwise. +==== + +These targets generate a variety of output documents in the directory +specified by the Makefile variable `$(OUTDIR)` (by default, `out/`). +The checked-in file `out/index.html` links to all these +targets, or they can individually be found as follows: + +Vulkan Specification:: + * `html` -- Single-file HTML5 in `$(OUTDIR)/html/vkspec.html`, and KaTeX + dependency in $(OUTDIR)/katex + * `chunked` -- Chunked HTML5 in `$(OUTDIR)/html/chap?.html` + * `pdf` -- PDF in `$(OUTDIR)/pdf/vkspec.pdf` +"`styleguide`" (Vulkan Documentation and Extensions: Procedures and Conventions):: + * `styleguide` -- Single-file HTML5 in `$(OUTDIR)/styleguide.html` +XML Registry schema document:: + * `registry` -- Single-file HTML5 in `$(OUTDIR)/registry.html` +<<building-diff,Diff spec>>:: + * `diff_html` -- Single-file HTML5 in `$(OUTDIR)/html/diff.html` +<<refpages,Reference pages>>:: + * `manhtmlpages` -- File-per-entry-point HTML in `$(OUTDIR)/man/html/*`. + Must be built with all extensions enabled (using `makeSpec -spec all`). +<<validation-scripts,Validator output>>:: + * None at present. The `allchecks` target writes to standard output unless + the underlying script is given additional options. +Valid usage database:: + * `validusage` - json database of all valid usage statements in the + specification. Must be built with `./makeAllExts` (for now). + Output in `$(OUTDIR)/validation/validusage.json`. + A validated schema for the output of this is stored in + `$(CURDIR)/config/vu-to-json/vu_schema.json` + +Once you have the basic build working, an appropriate parallelization +option, such as `-j 8`, should significantly speed up the reference page +builds. + +If you encounter problems refer to the <<troubleshooting>> section. + + +[[building-versions]] +=== Building Specifications For Different API Versions + +The `Makefile` defaults to building a Vulkan 1.2 specification. +This is controlled by Asciidoctor attributes passed in the Makefile variable +`$(VERSIONS)` +To instead build a Vulkan 1.1 specification, pass + +---- +VERSIONS="VK_VERSION_1_0 VK_VERSION_1_1" +---- + +on the `makeSpec` command line. + + +[[building-extensions]] +=== Building With Extensions Included + +Extensions are defined in the same source as the core Specification, but +are only conditionally included in the output. +http://asciidoctor.org/docs/user-manual/#attributes[Asciidoctor attributes] +of the same name as the extension are used to define whether the extension +is included or not -- defining such an attribute will cause the output to +include the text for that extension. + +When building the specification, the extensions included are those specified +as a space-separated list of extension names (e.g. `VK_KHR_surface`) in the +Makefile variable `$(EXTENSIONS)`, usually 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)`. + +The `makeSpec` wrapper script can clean generated files and then build one +or more specification targets for a set of explicitly specified extensions, +including all implicit extension dependencies of that set. +It accepts these options: + + * -clean - remove generated targets before building + * -v - print actions as well as executing them + * -n - print actions without executing them + * -genpath *path* - specify path to generated files (default `gen`) + * -spec *type* - build with sepcified sets of extensions. + *type* may be + ** *core* - no extensions added (default if not specified) + ** *khr* - all KHR extensions added + ** *all* - all registered extensions added + * -extension *extname* - build with specified extension included, + as well as the set specified by `-spec`. + Can be given multiple times. + * All remaining targets are arbitrary `make` options or + targets in the Makefile. + +The `target(s)` passed to these scripts are arbitrary `make` options, and +can be used to set Makefile variables and options discussed above, as well +as specify actual build targets. +For example, to build the HTML specification with all KHR extensions +included as well as a single vendor extension: + +---- +$ ./makeSpec -clean -spec khr -extension VK_EXT_debug_report html +---- + +The scripts `makeAllExts`, `makeKHR`, and `makeExt` set appropriate options +and invoke `makeSpec`, for backwards compatibility, but are no longer used +by Khronos. + +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 `makeSpec` script already does this. + +The reference pages (the `manhtmlpages` target) must be built using the +`-spec all` option; there are markup and scripting issues which will +probably cause any more restricted set of refpages to fail to build. + + +[[building-diff]] +==== Building A Highlighted Extension Diff + +The `diff_html` target in the Makefile can be used to generate a version of +the specification which highlights changes made to the specification by the +inclusion of a particular set of extensions. + +Extensions in the Makefile variable `$(EXTENSIONS)` define the base +extensions to be enabled by the specification, and these will not be +highlighted in the output. +Extensions in the Makefile variable `$(DIFFEXTENSIONS)` define the set of +extensions whose changes to the text will be highlighted when they are +enabled. +Any extensions in both variables will be treated as if they were only +included in `$(DIFFEXTENSIONS)`. +`$(DIFFEXTENSIONS)` can be set when using the `makeSpec` script described +above. + +In the resulting HTML document, content that has been added by one of the +extensions will be highlighted with a lime background, and content that was +removed will be highlighted with a pink background. +Each section has an anchor of `#differenceN`, with an arrow (=>) at the end +of each section which links to the next difference section. +The first diff section is `#difference1`. + +[NOTE] +.Note +==== +This output is not without errors. +It may instead result in visible `+++[.added]##content##+++` and +`+++[.removed]##content##+++`, and so also highlights not being rendered. +But such visible markup still correctly encapsulates the modified content. +==== + +[[building-test]] +=== Alternate and Test Builds + +If you are just testing Asciidoctor formatting, macros, stylesheets, etc., +you may want to edit `vkspec.txt` to just include your test code. +The asciidoctor HTML build is very fast, even for the whole Specification, +but PDF builds take several minutes. + + +=== Images Used In The Specification + +All images used in the specification are in the `images/` directory in the +SVG format, and were created with Inkscape. +We recommend using Inkscape to modify or create new images, as we've had +problems using SVG files created by some other tools; especially in the PDF +builds. + + +[[validation-scripts]] +=== Validation Scripts + +The `allchecks` Makefile target runs a Python script that looks for markup +errors, missing interfaces, macro misuse, and inconsistencies in the +specification text. +This script is necessarily heuristic, since it's dealing with lots of +hand-written material, but it identifies many problems and can suggest +solutions. +This script is also run as part of the CI tests in the internal Khronos +gitlab repository. + + +[[macros]] +== Our Asciidoctor Macros + +We use many custom Ruby macros in the reference pages and API spec +Asciidoctor 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 the `config/spec-macros/extension.rb` +asciidoctor extension script. + +The tags used are described in the +link:https://www.khronos.org/registry/vulkan/specs/1.1/styleguide.html[style +guide] (generated from `styleguide.txt`). + +We (may) eventually tool up the spec and reference 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 will take reader 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 + +The reference pages are extracted from the API Specification source, which +has been tagged to help identify boundaries of language talking about +different commands, structures, enumerants, and other types. +A set of Python scripts extract and lightly massage the relevant tagged +language into corresponding reference page sources. + +To regenerate the reference page sources from scratch yourself, execute: + +---- +./makeSpec -spec all refpages +---- + +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 `$(GENERATED)/refpage/*.txt` +files will be regenerated, but their contents will not change. + +If you add new API features to the Specification in a branch, make sure that +the commands have the required tagging and that reference pages are +generated for them, and build properly. + +When executing the `manhtmlpages` target in the Makefile, after building +HTML versions of all reference pages extracted from the spec, symbolic links +from aliases to the reference page for the API they alias will also be +created. + + +[[styles]] +== Our stylesheets + +We use an HTML stylesheet `config/khronos.css` derived from the +http://asciidoctor.org/docs/produce-custom-themes-using-asciidoctor-stylesheet-factory/[Asciidoctor +stylesheet factory] "`colony`" theme, with the default Arial font family +replaced by the sans-serif https://en.wikipedia.org/wiki/Noto_fonts[Noto +font family]. + + +[[styleguide]] +== Vulkan Style Guide + + +If you're writing new spec language or modifying existing language, see the +link:https://www.khronos.org/registry/vulkan/specs/1.2/styleguide.html["`style +guide`"] (formally titled "`Vulkan Documentation and Extensions: Procedures +and Conventions`") document for details of our asciidoctor macros, +extensions, mathematical equation markup, writing style, etc. + + +[[depends]] +== Software Dependencies + +This section describes the software components used by the Vulkan spec +toolchain. + +In the past, we previously specified package versions and instructions for +installing the toolchain in multiple desktop environments including Linux, +MacOS X, and Microsoft Windows. +The underlying components evolve rapidly, and we have not kept those +instructions up to date. + + +[[depends-docker]] +=== Khronos-Provided Docker Image + +Khronos has published a Docker image containing a Debian Linux distribution +with the entire toolchain preinstalled. + +We will occasionally update this image if needed, and we recommend people +needing to build from this repository use the Docker image. + +Docker installation is beyond the scope of this document. +Refer to link:https://docs.docker.com/get-docker/[the Docker website] for +information about installing Docker on Linux, Windows, and MacOS X. + +The name of the build image is + + khronosgroup/docker-images:asciidoctor-spec + +It can be pulled from the +link:https://hub.docker.com/repository/docker/khronosgroup/docker-images[Dockerhub +repository] with the command + + docker pull khronosgroup/docker-images:asciidoctor-spec + +Once docker is installed and the image is available, it can be executed as +described above under <<building, Building the Spec>> to generate +Specification output documents or other Makefile targets. + +[NOTE] +.Note +==== +The old `vulkan-docs-base` and `vulkan-docs` images continue to be hosted, +but the new `asciidoctor-spec` image is preferred - the added functionality +of `vulkan-docs`, to set the user/group inside Docker based on environment +variables passed into Docker, is no longer needed with the Docker `--user` +option. +==== + + +[[depends-nondocker]] +=== Non-Docker Build Environments + +We do not actively support building outside of our Docker image, but it is +straightforward to reproduce our toolchain in a Debian (or similar APT-based +Linux) distribution by executing the same steps as the +link:https://github.com/KhronosGroup/DockerContainers/blob/master/asciidoctor-spec.dockerfile[Dockerfile] +used to build our Docker image. + +It should be possible to apply the same steps in a Windows Subsystem for +Linux (WSL2) environment on Windows 10, as well. + +For other native environments, such as MacOS X and older Unix-like +environments for Windows such as MinGW and Cygwin, we provided instructions +in older versions of this document. +While those instructions are out of date and have been removed from current +versions of this document, you may be able to make use of +link:https://github.com/KhronosGroup/Vulkan-Docs/blob/v1.2.135/BUILD.adoc#depends[the +version of BUILD.adoc in the v1.2.135 repository tag] + +[NOTE] +.Note +==== +While we have no intention of forcing people to use our Docker image, we +cannot support every possible environment. +The Docker image is a straightforward way to use the Vulkan-Docs repository +with almost all modern desktop environments. +==== + + +[[history]] +== Revision History + + * 2021-03-12 - Use the new Docker image. + * 2020-07-15 - Update to use `makeSpec` instead of `makeAllExts`. + * 2020-03-23 - Document Khronos' published Docker image for building the + spec, and remove all platform-specific instructions. + * 2018-12-04 - Update Rbenv and ruby gem installation instructions and + package dependencies for Linux and Ubuntu/Windows 10. + * 2018-10-25 - Update Troubleshooting, and Windows and Linux build. Plus + random editing. + * 2018-03-13 - Rename to BUILD.adoc and update for new directory + structure. + * 2018-03-05 - Update README for Vulkan 1.1 release. + * 2017-03-20 - Add description of prawn versioning problem and how to fix + it. + * 2017-03-06 - Add description of ruby-enum versioning problem and how to + fix it. + * 2017-02-13 - Move some comments here from ../../../README.md. Tweak + asciidoctor markup to more clearly delineate shell command blocks. + * 2017-02-10 - Add more Ruby installation guidelines and reflow the + document in accordance with the style guide. + * 2017-01-31 - Add rbenv instructions and update the README elsewhere. + * 2017-01-16 - Modified dependencies for Asciidoctor + * 2017-01-06 - Replace MathJax with KaTeX. + * 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 and 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. |