status-im
/
Vulkan-Docs
mirror of https://github.com/status-im/Vulkan-Docs.git
2
0
Fork 0
Code Issues Projects Releases Wiki Activity

Update BUILD.adoc 

- Windows & Linux build
 - Troubleshooting
 - Random editing
This commit is contained in:
Petr Kraus 2018-10-25 02:33:52 +02:00
parent 8d6a7b23a7
commit 8a20479bc6
1 changed files with 415 additions and 281 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

696
BUILD.adoc
View File

@ -2,74 +2,82 @@
:toc2: :toc2:
:toclevels: 2 :toclevels: 2
ifdef::env-github[]
:note-caption: :information_source:
endif::[]
[[intro]] [[intro]]
== Introduction == Introduction
This README describes important stuff for getting the Vulkan API This README describes how to build the Vulkan API specification,
specification and reference pages building properly. 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]]
== Building The Spec == Building The Spec
First, clone the Khronos Github repository containing the Vulkan First, clone the Khronos Github repository containing the Vulkan
specification to your local Linux, Windows, or Mac PC. The repository is specification to your local Linux, Windows, or Mac PC.
located at https://github.com/KhronosGroup/Vulkan-Docs/ . The repository is located at https://github.com/KhronosGroup/Vulkan-Docs/.
Next, install all the necessary build tools (see <<depends,Software Next, install all the necessary build tools (see <<depends,Software
Dependencies>> below). Dependencies>> below).
Finally, go to the root directory of your local repository clone, and Finally, go to the root directory of your local repository clone, and do
$ make html $ make html
builds an HTML5 specification output. which builds an HTML5 specification output.
$ make all $ make all
builds the spec targets `html`, `pdf`, `styleguide`, `manhtml`, `manpdf`, builds the spec targets `html`, `pdf`, `styleguide`, `registry`, `manhtml`,
`manhtmlpages`, `checkinc`, and `checklinks`. `manpdf`, `manhtmlpages`, `checkinc`, and `checklinks`.
[NOTE] [NOTE]
.Notes .Note
==== ====
* `make all` takes a long time to run, and generates outputs that are * `make all` takes a long time to run, and generates outputs that are
irrelevant for most users. irrelevant for most users.
Usually `make html` is used to update the HTML target, which is all Usually `make html` is used to update the HTML target, which is all
that's needed for quick verification and viewing of changes. that's needed for quick review of changes made.
* The default `make` options build a Vulkan 1.1 specification with no * The default `make` options build a Vulkan 1.1 specification with no
optional extensions. optional extensions.
* The `validusage` target is not built as part of `make all`, due to it * The `validusage` target is not built as part of `make all`, due to it
needing to be built with all extensions enabled. Building this target needing to be built with all extensions enabled.
will fail otherwise. Building this target will fail otherwise.
==== ====
These targets generate a variety of output documents in the directory These targets generate a variety of output documents in the directory
specified by the Makefile variable `$(OUTDIR)` (by default, `out`). specified by the Makefile variable `$(OUTDIR)` (by default, `out/`).
The checked-in file `out/index.html` links to all these The checked-in file `out/index.html` links to all these
targets, or they can individually be found as follows: targets, or they can individually be found as follows:
* API spec: Vulkan^(R)^ Specification::
** `html` - HTML5 in `$(OUTDIR)/html/vkspec.html` * `html` -- Single-file HTML5 in `$(OUTDIR)/html/vkspec.html`, and KaTeX
** `pdf` - PDF in `$(OUTDIR)/pdf/vkspec.pdf` dependency in $(OUTDIR)/katex
* "`Vulkan Documentation and Extensions`" guide: * `pdf` -- PDF in `$(OUTDIR)/pdf/vkspec.pdf`
** `styleguide` - Single-file HTML5 in `$(OUTDIR)/styleguide.html` "`styleguide`" (Vulkan^(R)^ Documentation and Extensions: Procedures and Conventions)::
* Diff spec: * `styleguide` -- Single-file HTML5 in `$(OUTDIR)/styleguide.html`
** `diff_html` - Single-file HTML5 in `$(OUTDIR)/html/diff.html` XML Registry schema document::
* Reference pages: * `registry` -- Single-file HTML5 in `$(OUTDIR)/registry.html`
** `manhtml` - Single-file HTML in `$(OUTDIR)/apispec.html` <<building-diff,Diff spec>>::
** `manpdf` - Single-file PDF in `$(OUTDIR)/apispec.html` * `diff_html` -- Single-file HTML5 in `$(OUTDIR)/html/diff.html`
** `manhtmlpages` - File-per-entry-point HTML in `$(OUTDIR)/man/html/*` <<refpages,Reference pages>>::
* Validator output: * `manhtml` -- Single-file HTML in `$(OUTDIR)/apispec.html`
** `checkinc` - List of commands, structs, etc. * `manpdf` -- Single-file PDF in `$(OUTDIR)/apispec.pdf`
* `manhtmlpages` -- File-per-entry-point HTML in `$(OUTDIR)/man/html/*`
<<validation-scripts,Validator output>>::
* `checkinc` -- List of commands, structs, etc.
missing from the API spec in `$(OUTDIR)/checks/notInSpec.txt` missing from the API spec in `$(OUTDIR)/checks/notInSpec.txt`
** `checklinks` - Validator script output for API spec in * `checklinks` -- Validator script output for API spec in
`$(OUTDIR)/checks/specErrs.txt` and for reference pages in `$(OUTDIR)/checks/specErrs.txt` and for reference pages in
`$(OUTDIR)/checks/manErrs.txt` `$(OUTDIR)/checks/manErrs.txt`
* Valid usage database: Valid usage database::
** `validusage` - json database of all valid usage statements in the * `validusage` - json database of all valid usage statements in the
specification. Must be built with ./makeAllExts (for now). specification. Must be built with `./makeAllExts` (for now).
Output in `$(OUTDIR)/validation/validusage.json`. Output in `$(OUTDIR)/validation/validusage.json`.
A validated schema for the output of this is stored in A validated schema for the output of this is stored in
`$(CURDIR)/config/vu-to-json/vu_schema.json` `$(CURDIR)/config/vu-to-json/vu_schema.json`
@ -83,23 +91,13 @@ make -j 8
may significantly speed up the reference page builds. may significantly speed up the reference page builds.
If you encounter problems refer to the <<troubleshooting>> section.
[[build-bugs]]
=== Asciidoctor Build Errors
If you see an error like this from the `pdf` target:
/home/jon/.rbenv/versions/2.3.3/lib/ruby/gems/2.3.0/gems/ruby-enum-0.7.1/lib/ruby-enum/enum.rb:34:in `const_set': asciidoctor: FAILED: /home/tree/git/vulkan/vkspec.txt: Failed to load AsciiDoc document - wrong constant name default (NameError)
then try <<ruby-enum-downgrade,downgrading ruby-enum>>
as described below
[[building-versions]] [[building-versions]]
=== Building Specifications For Different API Versions === Building Specifications For Different API Versions
The `Makefile` defaults to building a Vulkan 1.1 specification. The `Makefile` defaults to building a Vulkan 1.1 specification.
This is controlled by asciidoc attributes passed in the Makefile variable This is controlled by Asciidoctor attributes passed in the Makefile variable
`$(VERSIONS)` `$(VERSIONS)`
To instead build a Vulkan 1.0 specification, pass To instead build a Vulkan 1.0 specification, pass
@ -115,39 +113,45 @@ on the `make` command line.
Extensions are defined in the same source as the core Specification, but Extensions are defined in the same source as the core Specification, but
are only conditionally included in the output. are only conditionally included in the output.
Asciidoctor http://asciidoctor.org/docs/user-manual/#attributes[attributes] http://asciidoctor.org/docs/user-manual/#attributes[Asciidoctor attributes]
of the same name as the extension are used to define whether the extension 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 is included or not -- defining such an attribute will cause the output to
include the text for that extension. include the text for that extension.
When building the specification, the extensions included are those specified 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 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. Makefile variable `$(EXTENSIONS)`, usually set on the make command line.
When changing the list of extensions, it is critical to remove all generated When changing the list of extensions, it is critical to remove all generated
files using the `clean_generated` Makefile target, as the contents of files using the `clean_generated` Makefile target, as the contents of
generated files depends on `$(EXTENSIONS)`. generated files depends on `$(EXTENSIONS)`.
There are several helper scripts which clean these files and then build one There are several helper scripts which clean these files and then build one
or more specified targets for specified extensions: or more specified targets for specified extensions:
* `makeExt` - generate outputs with one or more extensions enabled. * `makeExt` -- generate outputs with one or more extensions enabled.
Usage is `makeExt extension-names target(s)`, where `extension-names` is Usage is `makeExt extension-names target(s)`, where `extension-names` is
a space-separated list of extension names, such as a space-separated list of extension names, such as
`VK_EXT_debug_report`. `VK_EXT_debug_report`.
If more than one extension is specified, `extension-names` must be If more than one extension is specified, `extension-names` must be
quoted on the command line. quoted on the command line.
* `makeKHR` - generate outputs with all Khronos (`VK_KHR_*`) extensions * `makeKHR` -- generate outputs with all Khronos (`VK_KHR_*`) extensions
enabled. enabled.
Usage is `makeKHR target(s)`. Usage is `makeKHR target(s)`.
* `makeAllExts` -- generate outputs with all Vulkan extensions enabled.
Usage is `makeAllExts target(s)`.
The `target(s)` passed to these scripts are arbitrary `make` options, and The `target(s)` passed to these scripts are arbitrary `make` options, and
can be used to set Makefile variables and options, as well as specify actual can be used to set Makefile variables and options, as well as specify actual
build targets. build targets; you can, for example, do:
----
$ ./makeAllExts -j 8 VERSIONS="VK_VERSION_1_0" html
----
The Makefile variable `$(APITITLE)` defines an additional string which is The Makefile variable `$(APITITLE)` defines an additional string which is
appended to the specification title. appended to the specification title.
When building with extensions enabled, this should be set to something like When building with extensions enabled, this should be set to something like
`(with extension VK_extension_name)`. `(with extension VK_extension_name)`.
The `makeExt` and `makeKHR` scripts already do this. The `makeExt`, `makeKHR`, and `makeAllExts` scripts already do this.
[[building-diff]] [[building-diff]]
@ -171,29 +175,37 @@ above.
In the resulting HTML document, content that has been added by one of the 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 extensions will be highlighted with a lime background, and content that was
removed will be highlighted with a pink background. removed will be highlighted with a pink background.
Each section has an anchor of `"#differenceN"`, with an arrow (=>) at the end Each section has an anchor of `#differenceN`, with an arrow (=>) at the end
of each section which links to the next difference section. of each section which links to the next difference section.
The first diff section is "difference1". 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]] [[building-test]]
=== Alternate and Test Builds === Alternate and Test Builds
If you are just testing asciidoc formatting, macros, stylesheets, etc., you If you are just testing Asciidoctor formatting, macros, stylesheets, etc.,
may want to edit `vkspec.txt` to just include your test code. 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, The asciidoctor HTML build is very fast, even for the whole Specification,
but PDF builds take several minutes. but PDF builds take several minutes.
=== Images Used In The Specification === Images Used In The Specification
All images used in the specification are in the `images/` directory in SVG All images used in the specification are in the `images/` directory in the
format, and were created with Inkscape. SVG format, and were created with Inkscape.
We recommend using Inkscape to modify or create new images, as we've had 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 problems using SVG files created by some other tools; especially in the PDF
builds. builds.
[[validation-scripts]]
=== Validation Scripts === Validation Scripts
[NOTE] [NOTE]
@ -204,7 +216,7 @@ work properly at present due to numerous changes in the macro and
conditional markup used in the specification sources. conditional markup used in the specification sources.
==== ====
There are a several Makefile targets which look for inconsistencies and There are several Makefile targets which look for inconsistencies and
missing material between the specification and ref pages, and the canonical missing material between the specification and ref pages, and the canonical
description of the API in `vk.xml` : description of the API in `vk.xml` :
@ -214,16 +226,13 @@ description of the API in `vk.xml` :
They are necessarily heuristic since they're dealing with lots of They are necessarily heuristic since they're dealing with lots of
hand-written material. hand-written material.
To use them you'll also need to install:
* `python3`
The `checkinc` target uses Unix filters to determine which autogenerated API The `checkinc` target uses Unix filters to determine which autogenerated API
include files are used (and not used) in the spec. include files are used (and not used) in the spec.
It generates several output files, but the only one you're likely to care It generates `notInSpec.txt` report.
about is `actual.only`. This contains a list of the include files which are *not* referenced
This is a list of the include files which are *not* referenced anywhere in anywhere in the spec, and probably correspond to undocumented material in
the spec, and probably correspond to undocumented material in the spec. the spec.
The `checklinks` target validates the various internal tagged links in the The `checklinks` target validates the various internal tagged links in the
man pages and spec (e.g. the `fname:vkFuncBlah`, `sname:VkStructBlah`, etc.) man pages and spec (e.g. the `fname:vkFuncBlah`, `sname:VkStructBlah`, etc.)
@ -234,10 +243,10 @@ found.
[[macros]] [[macros]]
== Our Asciidoc Macros == Our Asciidoctor Macros
We use a bunch of custom macros in the reference pages and API spec asciidoc We use a bunch of custom macros in the reference pages and API spec
sources. Asciidoctor sources.
The validator scripts rely on these macros as part of their sanity checks, 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, 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 token, or enum name, so the documents are semantically tagged and more
@ -246,12 +255,14 @@ easily verifiable.
The supported macros are defined in the `config/vulkan-macros/extension.rb` The supported macros are defined in the `config/vulkan-macros/extension.rb`
asciidoctor extension script. asciidoctor extension script.
The tags used are described in the style guide (`styleguide.txt`). 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 ref pages to the point that We (may) 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 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 hovering over) it in the HTML view will take reader to the definition of
type/token. that type/token.
That will take some more plumbing work to tag the stuff in the autogenerated 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 include files, and do something sensible in the spec (e.g. resolve links to
internal references). internal references).
@ -300,11 +311,13 @@ font family].
=== Marking Normative Language === Marking Normative Language
// editing-note: Chapter should probably be merged with styleguide to reduce size
Normative language is marked as *bold*, and also with the [purple]#purple# Normative language is marked as *bold*, and also with the [purple]#purple#
role for HTML output. role for HTML output.
It can be used to mark entire paragraphs or spans of words. It can be used to mark entire paragraphs or spans of words.
In addition, the normative terminology macros, such as must: and may: and In addition, the normative terminology macros, such as `must:` and `may:`
cannot:, always use this role. and `cannot:`, always use this role.
The formatting of normative language depends on the stylesheet. The formatting of normative language depends on the stylesheet.
Currently it just comes out in purple. Currently it just comes out in purple.
@ -314,6 +327,8 @@ We may add a way to disable this formatting at build time.
[[equations]] [[equations]]
== Imbedding Equations == Imbedding Equations
// editing-note: Chapter should probably be merged with styleguide to reduce size
Where possible, equations should be written using straight asciidoc markup Where possible, equations should be written using straight asciidoc markup
with the _eq_ role. with the _eq_ role.
This covers many common equations and is faster than the alternatives. This covers many common equations and is faster than the alternatives.
@ -323,9 +338,9 @@ These symbols are defined using attribute names the same as the comparable
LaTeX macro names, where possible. LaTeX macro names, where possible.
For more complex equations, such as multi-case statements, matrices, and For more complex equations, such as multi-case statements, matrices, and
complex fractions, equations should be written using the latexmath: inline complex fractions, equations should be written using the `latexmath:` inline
and block macros. and block macros.
The contents of the latexmath: blocks should be LaTeX math notation. The contents of the `latexmath:` blocks should be LaTeX math notation.
LaTeX math markup delimiters are now inserted by the asciidoctor toolchain. LaTeX math markup delimiters are now inserted by the asciidoctor toolchain.
LaTeX math is passed through unmodified to all HTML output forms, which is LaTeX math is passed through unmodified to all HTML output forms, which is
@ -342,26 +357,31 @@ The following caveats apply:
`>=` respectively. `>=` respectively.
`&` is an alignment construct for multiline equations, and should only `&` is an alignment construct for multiline equations, and should only
appear in block macros anyway. appear in block macros anyway.
* AMSmath environments (e.g. pass:[\begin{equation*}], pass:[{align*}], * AMSmath environments (e.g. `pass:[\begin{equation*}]`,
etc.) cannot be used in KaTeX at present, and have been replaced with `pass:[{align*}]`, etc.) cannot be used in KaTeX at present, and have
constructs supported by KaTeX such as pass:[{aligned}]. been replaced with constructs supported by KaTeX such as
`pass:[{aligned}]`.
* Arbitrary LaTeX constructs cannot be used. * Arbitrary LaTeX constructs cannot be used.
KaTeX and asciidoctor-mathematical are only equation renderers, not full KaTeX and asciidoctor-mathematical are only equation renderers, not full
LaTeX engines. LaTeX engines.
Imbedding LaTeX like \Large or pass:[\hbox{\tt\small VK\_FOO}] may not Imbedding LaTeX like `\Large` or `pass:[\hbox{\tt\small VK\_FOO}]` may
work in any of the backends, and should be avoided. not work in any of the backends, and should be avoided.
See the "`Vulkan Documentation and Extensions`" document for more details of See the
supported LaTeX math constructs. link:https://www.khronos.org/registry/vulkan/specs/1.1/styleguide.html#writing-latexmath["`style guide`"]
(Vulkan Documentation and Extensions) document for more details of supported
LaTeX math constructs.
[[anchors]] [[anchors]]
== Asciidoc Anchors And Xrefs == Asciidoc Anchors And Xrefs
// editing-note: Chapter should probably be merged with styleguide to reduce size
In the API spec, sections can have anchors (labels) applied with the In the API spec, sections can have anchors (labels) applied with the
following syntax. following syntax.
In general the anchor should immediately precede the chapter or section In general the anchor should immediately precede the chapter or section
title and should use the form '+++[[chapter-section-label]]+++'. title and should use the form `pass:[[[chapter-section-label]]]`.
For example, For example,
For example, in chapter `synchronization.txt`: For example, in chapter `synchronization.txt`:
@ -392,6 +412,7 @@ Therefore you can say something like:
Fences are used with the +++<<vkQueueSubmit>>+++ command... Fences are used with the +++<<vkQueueSubmit>>+++ command...
---- ----
// editing-note: why would I though. There are xlink: macros for that.
[[depends]] [[depends]]
== Software Dependencies == Software Dependencies
@ -403,21 +424,21 @@ Before building the Vulkan spec, you must install the following tools.
Minimum versions known to be working are shown. Later versions will probably Minimum versions known to be working are shown. Later versions will probably
work at least as well. work at least as well.
* GNU make (make version: 4.0.8-1; older versions probably OK) * GNU make (`make` version: 4.0.8-1; older versions probably OK)
* Python 3 (python, version: 3.4.2) * Python 3 (`python`, version: 3.4.2)
* Ruby (ruby, version: 2.3.3) * Ruby (`ruby`, version: 2.3.3)
** The Ruby development package (ruby-dev) may also be required in some ** The Ruby development package (`ruby-dev`) may also be required in some
environments. environments.
* Git command-line client (git, version: 2.1.4). * Git command-line client (`git`, version: 2.1.4).
The build can progress without a git client, but branch/commit The build can progress without a git client, but branch/commit
information will be omitted from the build. information will be omitted from the build.
Any version supporting the following operations should work: Any version supporting the following operations should work:
** `git symbolic-ref --short HEAD` ** `git symbolic-ref --short HEAD`
** `git log -1 --format="%H"` ** `git log -1 --format="%H"`
* Ghostscript (ghostscript, version: 9.10). * Ghostscript (`ghostscript`, version: 9.10).
This is for the PDF build, and it can still progress without it. This is for the PDF build, and it can still progress without it.
Ghostscript is used to optimize the size of the PDF, so will be a lot Ghostscript is used to optimize the size of the PDF, so it will be order
smaller if it is included. of magnitude smaller if it is included.
The following Ruby Gems and platform package dependencies must also be The following Ruby Gems and platform package dependencies must also be
installed. installed.
@ -426,28 +447,28 @@ environment managers below.
Please read the remainder of this document (other than platform-specific Please read the remainder of this document (other than platform-specific
parts you don't use) completely before trying to install. parts you don't use) completely before trying to install.
* Asciidoctor (asciidoctor, version: 1.5.6.1) * Asciidoctor (`asciidoctor`, version: 1.5.6.1)
* Coderay (coderay, version 1.1.2) * Coderay (`coderay`, version 1.1.2)
* JSON Schema (json-schema, version 2.8.0) * JSON Schema (`json-schema`, version 2.8.0)
* Asciidoctor PDF (asciidoctor-pdf, version: 1.5.0.alpha16) * Asciidoctor PDF (`asciidoctor-pdf`, version: 1.5.0.alpha16)
* Asciidoctor Mathematical (asciidoctor-mathematical, version 0.2.2) * Asciidoctor Mathematical (`asciidoctor-mathematical`, version 0.2.2)
* https://github.com/asciidoctor/asciidoctor-mathematical#dependencies[Dependencies * https://github.com/asciidoctor/asciidoctor-mathematical#dependencies[Dependencies
for asciidoctor-mathematical] (There are a lot of these!) for `asciidoctor-mathematical`] (There are a lot of these!)
* KaTeX distribution (version 0.7.0 from https://github.com/Khan/KaTeX . * KaTeX distribution (version 0.7.0 from https://github.com/Khan/KaTeX.
This is cached under `katex/`, and need not be This is cached under `katex/`, and need not be installed from github.
installed from github.
.Note .Note
[NOTE] [NOTE]
==== ====
Older versions of these packages may work, but are not recommended. Older versions of these packages may work, but are not recommended.
In particular, the latest versions of asciidoctor-pdf and In particular, the latest versions of `asciidoctor-pdf` and
asciidoctor-mathematical contain important patches working around issues `asciidoctor-mathematical` contain important patches working around issues
we've discovered, and those patches may not be present in earlier versions. we've discovered, and those patches may not be present in earlier versions.
==== ====
Only the `asciidoctor` and `coderay` gems are needed if you don't intend to Only the `asciidoctor` and `coderay` gems are needed for the HTML `make`
build PDF versions of the spec and supporting documents. targets.
Rest is needed for the PDF builds.
`json-schema` is only required in order to validate the output of the valid `json-schema` is only required in order to validate the output of the valid
usage extraction scripts to a JSON file. usage extraction scripts to a JSON file.
@ -478,166 +499,32 @@ Platform-specific toolchain instructions follow:
Most of the dependencies on Linux packages are light enough that it's Most of the dependencies on Linux packages are light enough that it's
possible to build the spec natively in Windows, but it means bypassing the possible to build the spec natively in Windows, but it means bypassing the
makefile and calling functions directly. makefile and calling functions directly.
This might be solved in future. Considering how easy it is to get an Unix subsystem or VM on Windows, this
For now, there are three options for Windows users: Ubuntu / Windows 10, is not recommended and it is unlikely a direct path will become supported in
the future.
There are three supported options for Windows users: Ubuntu / Windows 10,
MinGW, or Cygwin. MinGW, or Cygwin.
[[depends-ubuntu]] [[depends-ubuntu]]
==== Ubuntu / Windows 10 ==== Ubuntu / Windows 10
When using the "`Ubuntu Subsystem`" for Windows 10, most dependencies can be At the time of writing Ubuntu Subsystem is provided in 18.04 LTS and
installed via apt-get: 16.04 LTS versions.
These versions are perfectly suitable for building this repo.
You can install Ubuntu Subsystem as described in the official documentation:
https://docs.microsoft.com/en-us/windows/wsl/install-win10
The distro image is not kept up-to-date, so it is recommended to run:
---- ----
sudo apt-get -qq -y install build-essential python3 git cmake bison flex \ sudo apt update
libffi-dev libxml2-dev libgdk-pixbuf2.0-dev libcairo2-dev \ sudo apt full-upgrade
libpango1.0-dev ttf-lyx gtk-doc-tools ghostscript
---- ----
The default ruby packages on Ubuntu are fairly out of date. Rest is identical to <<depends-linux,Linux instructions>>.
Ubuntu only provides `ruby` and `ruby2.0` - the latter is multiple revisions
behind the current stable branch, and would require wrangling to get the
makefile working with it.
Luckily, there are better options; either https://rvm.io[rvm] or
https://github.com/rbenv/rbenv[rbenv] is recommended to install a more
recent version.
[NOTE]
.Note
====
* If you are new to Ruby, you should *completely remove* (through the
package manager, e.g. `sudo apt-get remove *packagename*`) all existing
Ruby and asciidoctor infrastructure on your machine before trying to use
rvm or rbenv for the first time.
`dpkg -l | egrep 'asciidoctor|ruby|rbenv|rvm'` will give you a list of
candidate package names to remove.
** If you already have a favorite Ruby package manager, ignore this
advice, and just install the required OS packages and gems.
* In addition, `rvm` and `rbenv` are *mutually incompatible*.
They both rely on inserting shims and `$PATH` modifications in your bash
shell.
If you already have one of these installed and are familiar with it,
it's probably best to stay with that one.
One of the editors, who is new to Ruby, found `rbenv` far more
comprehensible than `rvm`.
The other editor likes `rvm` better.
** Neither `rvm` nor `rbenv` work, out of the box, when invoked from
non-Bash shells like tcsh.
This can be hacked up by setting the right environment variables and
PATH additions based on a bash environment.
* Most of the tools on Bash for Windows are quite happy with Windows line
endings (CR LF), but bash scripts expect Unix line endings (LF).
The file `.gitattributes` at the top of the vulkan tree in the 1.0
branch forces such scripts to be checked out with the proper line
endings on non-Linux platforms.
If you add new scripts whose names don't end in `.sh`, they should be
included in .gitattributes as well.
====
[[depends-ubuntu-rbenv]]
===== Ubuntu/Windows 10 Using Rbenv
Rbenv is a lighter-weight Ruby environment manager with less functionality
than rvm.
Its primary task is to manage different Ruby versions, while rvm has
additional functionality such as managing "`gemsets`" that is irrelevant to
our needs.
A complete installation script for the toolchain on Ubuntu for Windows,
developed on an essentially out-of-the-box environment, follows.
If you try this, don't try to execute the entire thing at once.
Do each step separately in case of errors we didn't encounter.
----
# Install packages needed by `ruby_build` and by toolchain components.
# See https://github.com/rbenv/ruby-build/wiki and
# https://github.com/asciidoctor/asciidoctor-mathematical#dependencies
sudo apt-get install autoconf bison build-essential libssl-dev \
libyaml-dev libreadline6-dev zlib1g-dev libncurses5-dev \
libffi-dev libgdbm3 libgdbm-dev cmake libxml2 \
libxml2-dev flex pkg-config libglib2.0-dev \
libcairo-dev libpango1.0-dev libgdk-pixbuf2.0-dev \
libpangocairo-1.0
# Install rbenv from https://github.com/rbenv/rbenv
git clone https://github.com/rbenv/rbenv.git ~/.rbenv
# Set path to shim layers in .bashrc
echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> .bashrc
~/.rbenv/bin/rbenv init
# Set .rbenv environment variables in .bashrc
echo 'eval "$(rbenv init -)"' >> .bashrc
# Restart your shell (e.g. open a new terminal window). Note that
# you do not need to use the `-l` option, since the modifications
# were made to .bashrc rather than .bash_profile. If successful,
# `type rbenv` should print 'rbenv is a function' followed by code.
# Install `ruby_build` plugin from https://github.com/rbenv/ruby-build
git clone https://github.com/rbenv/ruby-build.git ~/.rbenv/plugins/ruby-build
# Install Ruby 2.3.3
# This takes in excess of 20 min. to build!
# https://github.com/rbenv/ruby-build/issues/1054#issuecomment-276934761
# suggests:
# "You can speed up Ruby installs by avoiding generating ri/RDoc
# documentation for them:
# RUBY_CONFIGURE_OPTS=--disable-install-doc rbenv install 2.3.3
# We have not tried this.
rbenv install 2.3.3
# Configure rbenv globally to always use Ruby 2.3.3.
echo "2.3.3" > ~/.rbenv/version
# Finally, install toolchain components.
# asciidoctor-mathematical also takes in excess of 20 min. to build!
# The same RUBY_CONFIGURE_OPTS advice above may apply here as well.
gem install asciidoctor coderay json-schema
gem install --pre asciidoctor-pdf
MATHEMATICAL_SKIP_STRDUP=1 gem install asciidoctor-mathematical
----
[[depends-ubuntu-rvm]]
===== Ubuntu/Windows 10 Using RVM
Here are (sparser) instructions for using rvm to setup version 2.3.x:
----
gpg --keyserver hkp://keys.gnupg.net --recv-keys 409B6B1796C275462A1703113804BB82D39DC0E3
\curl -sSL https://get.rvm.io | bash -s stable --ruby
source ~/.rvm/scripts/rvm
rvm install ruby-2.3
rvm use ruby-2.3
----
NOTE: Windows 10 Bash will need to be launched with the "-l" option
appended, so that it runs a login shell; otherwise RVM won't function
correctly on future launches.
[[depends-ubuntu-sys]]
===== Ubuntu 16.04 using system Ruby
The Ubuntu 16.04.1 default Ruby install (version 2.3.1) seems to be
up-to-date enough to run all the required gems, but also needs the
`ruby-dev` package installed through the package manager.
In addition, the library
`/var/lib/gems/2.3.0/gems/mathematical-1.6.7/ext/mathematical/lib/liblasem.so`
has to be copied or linked into a directory where the loader can find it.
This requirement appears to be due to a problem with the
asciidoctor-mathematical build process.
[[depends-mingw]] [[depends-mingw]]
@ -768,6 +655,34 @@ curl -LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/cmex10.ttf \
-LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/msbm10.ttf -LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/msbm10.ttf
---- ----
[[depends-linux]]
=== Linux (Debian, Ubuntu, etc.)
System dependencies can be installed via apt:
----
sudo apt install build-essential python3 git cmake bison flex \
libffi-dev libxml2-dev libgdk-pixbuf2.0-dev libcairo2-dev \
libpango1.0-dev fonts-lyx ghostscript
----
These instructions are for the Ubuntu installation and are generally
applicable to native Linux environments that use Debian packages, although
the exact list of packages to install may differ.
Other distributions using different package managers, such as RPM (Fedora)
and Yum (SuSE) will have different requirements.
Ruby can also be installed as a system package:
----
sudo apt install ruby ruby-dev
----
Ruby packages are often well out of date, so using <<ruby-env,alternative
ruby environments>> such as `rbenv` or `rvm` might be preferable.
Once the Ruby environment is set up, install the required
<<depends-gems,Ruby Gems>>.
[[depends-osx]] [[depends-osx]]
=== Mac OS X === Mac OS X
@ -794,23 +709,6 @@ curl -LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/cmex10.ttf \
Then install the required <<depends-gems,Ruby Gems>>. Then install the required <<depends-gems,Ruby Gems>>.
[[depends-linux]]
=== Linux (Debian, Ubuntu, etc.)
The instructions for the <<depends-ubuntu,Ubuntu / Windows 10>> installation
are generally applicable to native Linux environments using Debian packages,
such as Debian and Ubuntu, although the exact list of packages to install
may differ.
Other distributions using different package managers, such as RPM (Fedora)
and Yum (SuSE) will have different requirements.
Using `rbenv` or `rvm` is neccessary, since the system Ruby packages are
often well out of date.
Once the environment manager, Ruby, and `ruby_build` have been installed,
install the required <<depends-gems,Ruby Gems>>.
[[depends-gems]] [[depends-gems]]
=== Ruby Gems === Ruby Gems
@ -818,35 +716,271 @@ The following ruby gems can be installed directly via the `gem install`
command, once the platform is set up: command, once the platform is set up:
---- ----
gem install rake asciidoctor coderay json-schema gem install asciidoctor coderay json-schema
# Required only for pdf builds # Required only for pdf builds
MATHEMATICAL_SKIP_STRDUP=1 gem install asciidoctor-mathematical gem install asciidoctor-mathematical
gem install --pre asciidoctor-pdf gem install --pre asciidoctor-pdf
---- ----
[[ruby-enum-downgrade]] Depending on Ruby environment `gem` may require `sudo`.
==== Ruby Gem Versioning Errors
It may significantly speed up installation if you skip documentation build
by passing `--no-rdoc --no-ri` arguments.
It may be beneficial to use updated packages via:
----
gem update
gem clean
----
[[troubleshooting]]
== Troubleshooting
This section goes over known problems and solutions for toolchain
installation or for build.
If you get arbitrary build errors it can't hurt to first try resolve it by
cleaning the tree:
----
make clean
git clean -dxf
----
=== STEM SVG Errors
If you happen to have `_` or other Asciidoctor formating characters in your
path, then PDF build using `asciidoctor-mathematical` may fail with:
----
asciidoctor: WARNING: image to embed not found or not readable: whatever/<em>stuff/Vulkan-Docs/out/equations_temp/stem-d3355033150173c1d397e342237db405.svg
----
See https://github.com/asciidoctor/asciidoctor-mathematical/issues/43.
You simply need to have the repository cloned in a simpler path.
=== Ghostscript Errors
Ghostscript optimization of the PDF may produce:
----
**** Error reading a content stream. The page may be incomplete.
Output may be incorrect.
**** Error: File did not complete the page properly and may be damaged.
Output may be incorrect.
----
Usually, it is just a problem with the Asciidoc sources (e.g. silent failure
to render content that does not fit in the page; such as SVG equations where
there is no line break opportunity).
=== Ruby Gem Versioning Errors
Sometimes, when updating ruby gem packages incompatibilities arise.
It is resoleved by identifying the offending packages and downgrading them:
----
$ gem uninstall package_name
$ gem install package_name --version good_version_number
----
If you already have the gem dependencies previously installed, if there are
new versions, then updating to them instead might help:
----
$ gem update
----
*ruby-enum* *ruby-enum*
Make sure you are using ruby-enum 0.7.1 or later, and mathematical 1.6.8 or We have seen this PDF build error:
later. If you are forced to use earlier versions, see ----
Failed to load AsciiDoc document - wrong constant name default (NameError)
----
It should not be occuring with updated packages.
Make sure you are using `ruby-enum 0.7.1` or later, and `mathematical 1.6.8`
or later.
If you are forced to use earlier versions, see
https://github.com/gjtorikian/mathematical/issues/69 for a report of a https://github.com/gjtorikian/mathematical/issues/69 for a report of a
related versioning problem. related versioning problem.
*prawn* *prawn*
Make sure you are using prawn 2.2.1 or later, and prawn-templates 0.0.5 or Make sure you are using prawn 2.2.1 or later, and prawn-templates 0.0.5 or
later. Incompatibilities between asciidoctor-pdf and earlier versions of later. Incompatibilities between `asciidoctor-pdf` and earlier versions of
these gems affects the PDF build. See these gems affects the PDF build. See
https://github.com/KhronosGroup/Vulkan-Docs/issues/476 https://github.com/KhronosGroup/Vulkan-Docs/issues/476
=== asciidoctor-mathematical gem native extension errors
Installing `mathematical` gem builds `lasem` and `mtex2MML` native binaries.
The <<depends,Dependencies>> we list should be sufficient for the install to
build those native extensions successfully.
If you encounter problems, it is possible to use those binaries from
preinstalled locations.
See https://github.com/gjtorikian/mathematical#troubleshooting.
=== Asciidoctor include errors
If you get errors like:
----
asciidoctor: ERROR: chapters/???.txt: line 189: include file not found: ???/Vulkan-Docs/api/protos/???.txt
----
you probably forgot to call `make clean_generated` as stated in the
<<building-extensions>> chapter.
[[ruby-env]]
== Alternative Ruby environments
The default `ruby` packages on Linux distro may be out of date.
Through the default `ruby` package, Ubuntu 18.04 provides ruby 2.5, and
Ubuntu 16.10 provides ruby 2.3.
Those system packages seem to be sufficient to build this repo.
But there are better options; either https://rvm.io[rvm] or
https://github.com/rbenv/rbenv[rbenv] is recommended to install an updated
version of Ruby environment.
[NOTE]
.Note
====
* If you are new to Ruby, you should *completely remove* (through the
package manager, e.g. `sudo apt purge *packagename*`) all existing
Ruby and asciidoctor infrastructure on your machine before trying to use
rvm or rbenv for the first time.
`dpkg -l | egrep 'asciidoctor|ruby|rbenv|rvm'` will give you a list of
candidate package names to remove.
** If you already have a favorite Ruby package manager, ignore this
advice, and just install the required OS packages and gems.
* In addition, `rvm` and `rbenv` are *mutually incompatible*.
They both rely on inserting shims and `$PATH` modifications in your bash
shell.
If you already have one of these installed and are familiar with it,
it's probably best to stay with that one.
One of the editors, who is new to Ruby, found `rbenv` far more
comprehensible than `rvm`.
The other editor likes `rvm` better.
** Neither `rvm` nor `rbenv` work, out of the box, when invoked from
non-Bash shells like `tcsh`.
This can be hacked up by setting the right environment variables and
`PATH` additions based on a bash environment.
* Most of the tools on Bash for Windows are quite happy with Windows line
endings (`CR LF`), but bash scripts expect Unix line endings (`LF`).
The file `.gitattributes` at the top of the vulkan tree forces such
scripts to be checked out with the proper line endings on non-Linux
platforms.
If you add new scripts whose names don't end in `.sh`, they should be
included in `.gitattributes` as well.
====
[[depends-ubuntu-rbenv]]
===== Ubuntu/Windows 10 Using Rbenv
Rbenv is a lighter-weight Ruby environment manager with less functionality
than rvm.
Its primary task is to manage different Ruby versions, while rvm has
additional functionality such as managing "`gemsets`" that is irrelevant to
our needs.
A complete installation script for the toolchain on Ubuntu for Windows,
developed on an essentially out-of-the-box environment, follows.
If you try this, don't try to execute the entire thing at once.
Do each step separately in case of errors we didn't encounter.
----
# Install packages needed by `ruby_build` and by toolchain components.
# See https://github.com/rbenv/ruby-build/wiki and
# https://github.com/asciidoctor/asciidoctor-mathematical#dependencies
sudo apt-get install autoconf bison build-essential libssl-dev \
libyaml-dev libreadline6-dev zlib1g-dev libncurses5-dev \
libffi-dev libgdbm3 libgdbm-dev cmake libxml2 \
libxml2-dev flex pkg-config libglib2.0-dev \
libcairo-dev libpango1.0-dev libgdk-pixbuf2.0-dev \
libpangocairo-1.0
# Install rbenv from https://github.com/rbenv/rbenv
git clone https://github.com/rbenv/rbenv.git ~/.rbenv
# Set path to shim layers in .bashrc
echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> .bashrc
~/.rbenv/bin/rbenv init
# Set .rbenv environment variables in .bashrc
echo 'eval "$(rbenv init -)"' >> .bashrc
# Restart your shell (e.g. open a new terminal window). Note that
# you do not need to use the `-l` option, since the modifications
# were made to .bashrc rather than .bash_profile. If successful,
# `type rbenv` should print 'rbenv is a function' followed by code.
# Install `ruby_build` plugin from https://github.com/rbenv/ruby-build
git clone https://github.com/rbenv/ruby-build.git ~/.rbenv/plugins/ruby-build
# Install Ruby 2.3.3
# This takes in excess of 20 min. to build!
# https://github.com/rbenv/ruby-build/issues/1054#issuecomment-276934761
# suggests:
# "You can speed up Ruby installs by avoiding generating ri/RDoc
# documentation for them:
# RUBY_CONFIGURE_OPTS=--disable-install-doc rbenv install 2.3.3
# We have not tried this.
rbenv install 2.3.3
# Configure rbenv globally to always use Ruby 2.3.3.
echo "2.3.3" > ~/.rbenv/version
# Finally, install toolchain components.
# asciidoctor-mathematical also takes in excess of 20 min. to build!
# The same RUBY_CONFIGURE_OPTS advice above may apply here as well.
gem install asciidoctor coderay json-schema
gem install --pre asciidoctor-pdf
MATHEMATICAL_SKIP_STRDUP=1 gem install asciidoctor-mathematical
----
[[depends-ubuntu-rvm]]
===== Ubuntu/Windows 10 Using RVM
Here are (sparser) instructions for using rvm to setup version 2.3.x:
----
gpg --keyserver hkp://keys.gnupg.net --recv-keys 409B6B1796C275462A1703113804BB82D39DC0E3
\curl -sSL https://get.rvm.io | bash -s stable --ruby
source ~/.rvm/scripts/rvm
rvm install ruby-2.3
rvm use ruby-2.3
----
NOTE: Windows 10 Bash will need to be launched with the "-l" option
appended, so that it runs a login shell; otherwise RVM won't function
correctly on future launches.
[[history]] [[history]]
== Revision History == Revision History
* 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 * 2018-03-13 - Rename to BUILD.adoc and update for new directory
structure. structure.
* 2018-03-05 - Update README for Vulkan 1.1 release. * 2018-03-05 - Update README for Vulkan 1.1 release.