/ BUILD.adoc
BUILD.adoc
1 = Vulkan^(R)^ Specification Build Instructions and Notes 2 :toc2: 3 :toclevels: 2 4 5 ifdef::env-github[] 6 :note-caption: :information_source: 7 endif::[] 8 9 [[intro]] 10 == Introduction 11 12 This README describes how to build the Vulkan API specification, 13 reference pages, and\or other related targets. 14 15 It documents how to set up your build environment, build steps and 16 targets, and contains some troubleshooting advice. 17 18 [[building]] 19 == Building The Spec 20 21 First, clone the Khronos Github repository containing the Vulkan 22 specification to your local Linux, Windows, or Mac PC. 23 The repository is located at https://github.com/KhronosGroup/Vulkan-Docs/. 24 25 Next, install all the necessary build tools (see <<depends,Software 26 Dependencies>> below). 27 28 Finally, go to the root directory of your local repository clone, and do 29 30 $ make html 31 32 which builds an HTML5 specification output. 33 34 $ make all 35 36 builds the spec targets `html`, `pdf`, `styleguide`, `registry`, 37 `manhtmlpages`, and `allchecks` 38 39 [NOTE] 40 .Note 41 ==== 42 * `make all` takes a long time to run, and generates outputs that are 43 irrelevant for most users. 44 Usually `make html` is used to update the HTML target, which is all 45 that's needed for quick review of changes made. 46 * The default `make` options build a Vulkan 1.1 specification with no 47 optional extensions. 48 * The `validusage` target is not built as part of `make all`, due to it 49 needing to be built with all extensions enabled. 50 Building this target will fail otherwise. 51 ==== 52 53 These targets generate a variety of output documents in the directory 54 specified by the Makefile variable `$(OUTDIR)` (by default, `out/`). 55 The checked-in file `out/index.html` links to all these 56 targets, or they can individually be found as follows: 57 58 Vulkan^(R)^ Specification:: 59 * `html` -- Single-file HTML5 in `$(OUTDIR)/html/vkspec.html`, and KaTeX 60 dependency in $(OUTDIR)/katex 61 * `chunked` -- Chunked HTML5 in `$(OUTDIR)/html/chap?.html` 62 * `pdf` -- PDF in `$(OUTDIR)/pdf/vkspec.pdf` 63 "`styleguide`" (Vulkan^(R)^ Documentation and Extensions: Procedures and Conventions):: 64 * `styleguide` -- Single-file HTML5 in `$(OUTDIR)/styleguide.html` 65 XML Registry schema document:: 66 * `registry` -- Single-file HTML5 in `$(OUTDIR)/registry.html` 67 <<building-diff,Diff spec>>:: 68 * `diff_html` -- Single-file HTML5 in `$(OUTDIR)/html/diff.html` 69 <<refpages,Reference pages>>:: 70 * `manhtmlpages` -- File-per-entry-point HTML in `$(OUTDIR)/man/html/*` 71 <<validation-scripts,Validator output>>:: 72 * None at present. The `allchecks` target writes to standard output unless 73 the underlying script is given additional options. 74 Valid usage database:: 75 * `validusage` - json database of all valid usage statements in the 76 specification. Must be built with `./makeAllExts` (for now). 77 Output in `$(OUTDIR)/validation/validusage.json`. 78 A validated schema for the output of this is stored in 79 `$(CURDIR)/config/vu-to-json/vu_schema.json` 80 81 Once you have the basic build working, an appropriate parallelization option 82 to make, such as 83 84 ---- 85 make -j 8 86 ---- 87 88 may significantly speed up the reference page builds. 89 90 If you encounter problems refer to the <<troubleshooting>> section. 91 92 [[building-versions]] 93 === Building Specifications For Different API Versions 94 95 The `Makefile` defaults to building a Vulkan 1.1 specification. 96 This is controlled by Asciidoctor attributes passed in the Makefile variable 97 `$(VERSIONS)` 98 To instead build a Vulkan 1.0 specification, pass 99 100 ---- 101 VERSIONS="VK_VERSION_1_0" 102 ---- 103 104 on the `make` command line. 105 106 107 [[building-extensions]] 108 === Building With Extensions Included 109 110 Extensions are defined in the same source as the core Specification, but 111 are only conditionally included in the output. 112 http://asciidoctor.org/docs/user-manual/#attributes[Asciidoctor attributes] 113 of the same name as the extension are used to define whether the extension 114 is included or not -- defining such an attribute will cause the output to 115 include the text for that extension. 116 117 When building the specification, the extensions included are those specified 118 as a space-separated list of extension names (e.g. `VK_KHR_surface`) in the 119 Makefile variable `$(EXTENSIONS)`, usually set on the make command line. 120 When changing the list of extensions, it is critical to remove all generated 121 files using the `clean_generated` Makefile target, as the contents of 122 generated files depends on `$(EXTENSIONS)`. 123 There are several helper scripts which clean these files and then build one 124 or more specified targets for specified extensions: 125 126 * `makeExt` -- generate outputs with one or more extensions enabled. 127 Usage is `makeExt extension-names target(s)`, where `extension-names` is 128 a space-separated list of extension names, such as 129 `VK_EXT_debug_report`. 130 If more than one extension is specified, `extension-names` must be 131 quoted on the command line. 132 * `makeKHR` -- generate outputs with all Khronos (`VK_KHR_*`) extensions 133 enabled. 134 Usage is `makeKHR target(s)`. 135 * `makeAllExts` -- generate outputs with all Vulkan extensions enabled. 136 Usage is `makeAllExts target(s)`. 137 138 The `target(s)` passed to these scripts are arbitrary `make` options, and 139 can be used to set Makefile variables and options, as well as specify actual 140 build targets; you can, for example, do: 141 142 ---- 143 $ ./makeAllExts -j 8 VERSIONS="VK_VERSION_1_0" html 144 ---- 145 146 The Makefile variable `$(APITITLE)` defines an additional string which is 147 appended to the specification title. 148 When building with extensions enabled, this should be set to something like 149 `(with extension VK_extension_name)`. 150 The `makeExt`, `makeKHR`, and `makeAllExts` scripts already do this. 151 152 153 [[building-diff]] 154 ==== Building A Highlighted Extension Diff 155 156 The `diff_html` target in the makefile can be used to generate a version of 157 the specification which highlights changes made to the specification by the 158 inclusion of a particular set of extensions. 159 160 Extensions in the Makefile variable `$(EXTENSIONS)` define the base 161 extensions to be enabled by the specification, and these will not be 162 highlighted in the output. 163 Extensions in the Makefile variable `$(DIFFEXTENSIONS)` define the set of 164 extensions whose changes to the text will be highlighted when they are 165 enabled. 166 Any extensions in both variables will be treated as if they were only 167 included in `$(DIFFEXTENSIONS)`. 168 `$(DIFFEXTENSIONS)` can be set when using the `make*` scripts described 169 above. 170 171 In the resulting HTML document, content that has been added by one of the 172 extensions will be highlighted with a lime background, and content that was 173 removed will be highlighted with a pink background. 174 Each section has an anchor of `#differenceN`, with an arrow (=>) at the end 175 of each section which links to the next difference section. 176 The first diff section is `#difference1`. 177 178 [NOTE] 179 .Note 180 ==== 181 This output is not without errors. 182 It may instead result in visible `+++[.added]##content##+++` and 183 `+++[.removed]##content##+++`, and so also highlights not being rendered. 184 But such visible markup still correctly encapsulates the modified content. 185 ==== 186 187 [[building-test]] 188 === Alternate and Test Builds 189 190 If you are just testing Asciidoctor formatting, macros, stylesheets, etc., 191 you may want to edit `vkspec.txt` to just include your test code. 192 The asciidoctor HTML build is very fast, even for the whole Specification, 193 but PDF builds take several minutes. 194 195 196 === Images Used In The Specification 197 198 All images used in the specification are in the `images/` directory in the 199 SVG format, and were created with Inkscape. 200 We recommend using Inkscape to modify or create new images, as we've had 201 problems using SVG files created by some other tools; especially in the PDF 202 builds. 203 204 [[validation-scripts]] 205 === Validation Scripts 206 207 The `allchecks` Makefile target runs a Python script that looks for markup 208 errors, missing interfaces, macro misuse, and inconsistencies in the 209 specification text. 210 This script is necessarily heuristic, since it's dealing with lots of 211 hand-written material, but it identifies many problems and can suggest 212 solutions. 213 This script is also run as part of the CI tests in the internal Khronos 214 gitlab repository. 215 216 217 [[macros]] 218 == Our Asciidoctor Macros 219 220 We use a bunch of custom macros in the reference pages and API spec 221 Asciidoctor sources. 222 The validator scripts rely on these macros as part of their sanity checks, 223 and you should use the macros whenever referring to an API command, struct, 224 token, or enum name, so the documents are semantically tagged and more 225 easily verifiable. 226 227 The supported macros are defined in the `config/spec-macros/extension.rb` 228 asciidoctor extension script. 229 230 The tags used are described in the 231 link:https://www.khronos.org/registry/vulkan/specs/1.1/styleguide.html[style 232 guide] (generated from `styleguide.txt`). 233 234 We (may) eventually tool up the spec and ref pages to the point that 235 anywhere there's a type or token referred to, clicking on (or perhaps 236 hovering over) it in the HTML view will take reader to the definition of 237 that type/token. 238 That will take some more plumbing work to tag the stuff in the autogenerated 239 include files, and do something sensible in the spec (e.g. resolve links to 240 internal references). 241 242 Most of these macros deeply need more intuitive names. 243 244 245 [[refpages]] 246 == Reference Pages 247 248 The reference pages are extracted from the API Specification source, which 249 has been tagged to help identify boundaries of language talking about 250 different commands, structures, enumerants, and other types. 251 A set of Python scripts extract and lightly massage the relevant tagged 252 language into corresponding ref page. 253 Pages without corresponding content in the API spec are generated 254 automatically, when possible (e.g. for `Vk*FlagBits` pages). 255 256 If for some reason you want to regenerate the ref page sources from scratch 257 yourself, you can do so by 258 259 ---- 260 rm man/apispec.txt 261 make apispec.txt 262 ---- 263 264 The `genRef.py` script will generate many warnings, but most are just 265 reminders that some pages are automatically generated. 266 If everything is working correctly, all the `man/*.txt` files will be 267 regenerated, but their contents will not change. 268 269 If you add new API features to the Specification in a branch, make sure that 270 the commands have the required tagging and that ref pages are generated for 271 them, and build properly. 272 273 274 [[styles]] 275 == Our stylesheets 276 277 We use an HTML stylesheet `config/khronos.css` derived from the 278 http://asciidoctor.org/docs/produce-custom-themes-using-asciidoctor-stylesheet-factory/[Asciidoctor 279 stylesheet factory] "`colony`" theme, with the default Arial font family 280 replaced by the sans-serif https://en.wikipedia.org/wiki/Noto_fonts[Noto 281 font family]. 282 283 284 === Marking Normative Language 285 286 // editing-note: Chapter should probably be merged with styleguide to reduce size 287 288 Normative language is marked as *bold*, and also with the [purple]#purple# 289 role for HTML output. 290 It can be used to mark entire paragraphs or spans of words. 291 In addition, the normative terminology macros, such as `must:` and `may:` 292 and `cannot:`, always use this role. 293 294 The formatting of normative language depends on the stylesheet. 295 Currently it just comes out in purple. 296 We may add a way to disable this formatting at build time. 297 298 299 [[equations]] 300 == Imbedding Equations 301 302 // editing-note: Chapter should probably be merged with styleguide to reduce size 303 304 Where possible, equations should be written using straight asciidoc markup 305 with the _eq_ role. 306 This covers many common equations and is faster than the alternatives. 307 A variety of mathematical symbols are defined using attributes in the 308 included `config/attribs.txt`. 309 These symbols are defined using attribute names the same as the comparable 310 LaTeX macro names, where possible. 311 312 For more complex equations, such as multi-case statements, matrices, and 313 complex fractions, equations should be written using the `latexmath:` inline 314 and block macros. 315 The contents of the `latexmath:` blocks should be LaTeX math notation. 316 LaTeX math markup delimiters are now inserted by the asciidoctor toolchain. 317 318 LaTeX math is passed through unmodified to all HTML output forms, which is 319 subsequently rendered with the KaTeX engine when the HTML is loaded. 320 A local copy of the KaTeX release is kept in `katex/` and 321 copied to the HTML output directory during spec generation. 322 Math is processed into SVGs via asciidoctor-mathematical for PDF output. 323 324 The following caveats apply: 325 326 * The special characters `<` , `>` , and `&` can currently be used only in 327 +++[latexmath]+++ block macros, not in +++latexmath:[]+++ inline macros. 328 Instead use `\lt`, `\leq`, `\gt`, and `\geq` for `<`, `<=`, `>`, and 329 `>=` respectively. 330 `&` is an alignment construct for multiline equations, and should only 331 appear in block macros anyway. 332 * AMSmath environments (e.g. `pass:[\begin{equation*}]`, 333 `pass:[{align*}]`, etc.) cannot be used in KaTeX at present, and have 334 been replaced with constructs supported by KaTeX such as 335 `pass:[{aligned}]`. 336 * Arbitrary LaTeX constructs cannot be used. 337 KaTeX and asciidoctor-mathematical are only equation renderers, not full 338 LaTeX engines. 339 Imbedding LaTeX like `\Large` or `pass:[\hbox{\tt\small VK\_FOO}]` may 340 not work in any of the backends, and should be avoided. 341 342 See the 343 link:https://www.khronos.org/registry/vulkan/specs/1.1/styleguide.html#writing-latexmath["`style guide`"] 344 (Vulkan Documentation and Extensions) document for more details of supported 345 LaTeX math constructs. 346 347 348 [[anchors]] 349 == Asciidoc Anchors And Xrefs 350 351 // editing-note: Chapter should probably be merged with styleguide to reduce size 352 353 In the API spec, sections can have anchors (labels) applied with the 354 following syntax. 355 In general the anchor should immediately precede the chapter or section 356 title and should use the form `pass:[[[chapter-section-label]]]`. 357 For example, 358 359 For example, in chapter `synchronization.txt`: 360 361 ---- 362 [[synchronization-primitives]] 363 Synchronization Primitives 364 ---- 365 366 Cross-references to those anchors can then be generated with, for example, 367 368 ---- 369 See the <<synchronization-primitives>> section for discussion of fences, 370 semaphores, and events. 371 ---- 372 373 You can also add anchors on arbitrary paragraphs, using a similar naming 374 scheme. 375 376 Anything whose definition comes from one of the autogenerated API include 377 files (`.txt` files in the directories `basetypes`, `enums`, `flags`, 378 `funcpointers`, `handles`, `protos`, and `structs`) has a corresponding 379 anchor whose name is the name of the function, struct, etc. 380 being defined. 381 Therefore you can say something like: 382 383 ---- 384 Fences are used with the +++<<vkQueueSubmit>>+++ command... 385 ---- 386 387 // editing-note: why would I though. There are xlink: macros for that. 388 389 390 [[depends]] 391 == Software Dependencies 392 393 This section describes the software components used by the Vulkan spec 394 toolchain. 395 396 Before building the Vulkan spec, you must install the following tools. 397 Minimum versions known to be working are shown. Later versions will probably 398 work at least as well. 399 400 * GNU make (`make` version: 4.0.8-1; older versions probably OK) 401 * Python 3 (`python`, version: 3.4.2) 402 * Ruby (`ruby`, version: 2.5.3) 403 ** The Ruby development package (`ruby-dev`) may also be required in some 404 environments. 405 * Git command-line client (`git`, version: 2.1.4). 406 The build can progress without a git client, but branch/commit 407 information will be omitted from the build. 408 Any version supporting the following operations should work: 409 ** `git symbolic-ref --short HEAD` 410 ** `git log -1 --format="%H"` 411 * Ghostscript (`ghostscript`, version: 9.10). 412 This is for the PDF build, and it can still progress without it. 413 Ghostscript is used to optimize the size of the PDF, so it will be order 414 of magnitude smaller if it is included. 415 * The following dependencies are required only if building the 416 `chunked` target (chunked HTML output). 417 ** Node (`nodejs`, version: 8.11.1) 418 *** Node Package Manager (`npm`, version: 5.8.0), for installing Lunr 419 ** Lunr (`lunr`, version: 2.3.6), installed with npm. 420 One of the lunr files, `lunr.js`, is also incorporated into this 421 repository under `config/chunkindex/lunr.js`, so it will always be 422 available at spec load time. It is possible that there will be 423 incompatibilities between the installed version of lunr used to build 424 the index, and the copy of `lunr.js` included with the repository. If 425 so, update the repository copy of the file from your lunr distribution, 426 or install the specific lunr version 2.3.6 corresponding to the 427 repository copy. 428 *** Ensure that the installed `lunr` package is found by `node` at 429 runtime. This may require setting the environment variable NODE_PATH 430 to the path where `lunr` is installed. This path will probably be 431 `/usr/lib/node_modules`, if you install `nodejs` and `npm` from 432 deb.nodesource.com . 433 434 The following Ruby Gems and platform package dependencies must also be 435 installed. 436 This process is described in more detail for individual platforms and 437 environment managers below. 438 Please read the remainder of this document (other than platform-specific 439 parts you don't use) completely before trying to install. 440 441 * Asciidoctor (`asciidoctor`, version: 1.5.8) 442 * Coderay (`coderay`, version 1.1.2) 443 * JSON Schema (`json-schema`, version 2.8.1) 444 * Asciidoctor Diagram (`asciidoctor-diagram`, version: 1.5.11) 445 * Asciidoctor PDF (`asciidoctor-pdf`, version: 1.5.0.alpha16) 446 * Asciidoctor Mathematical (`asciidoctor-mathematical`, version 0.2.2) 447 * https://github.com/asciidoctor/asciidoctor-mathematical#dependencies[Dependencies 448 for `asciidoctor-mathematical`] (There are a lot of these!) 449 * KaTeX distribution (version 0.7.0 from https://github.com/Khan/KaTeX. 450 This is cached under `katex/`, and need not be installed from github. 451 * If generating the chunked HTML target: 452 ** `asciidoctor-chunker` installed according to 453 https://github.com/wshito/asciidoctor-chunker[the chunker README]. 454 ** `Roswell` (version 18.10.10.95 from 455 https://github.com/roswell/roswell/releases) 456 457 .Note 458 [NOTE] 459 ==== 460 Older versions of these packages may work, but are not recommended. 461 In particular, the latest versions of `asciidoctor-pdf` and 462 `asciidoctor-mathematical` often solve problems we've encountered in older 463 versions. 464 ==== 465 466 Only the `asciidoctor` and `coderay` gems are needed for the HTML `make` 467 targets. 468 Rest is needed for the PDF builds. 469 470 `json-schema` is only required in order to validate the output of the valid 471 usage extraction scripts to a JSON file. 472 If not installed, validation will be skipped when the JSON is built. 473 474 [NOTE] 475 .Note 476 ==== 477 While it's easier to install just the toolchain components for HTML builds, 478 people submitting MRs with substantial changes to the Specification are 479 responsible for verifying that their branches build *both* `html` and `pdf` 480 targets. 481 ==== 482 483 Platform-specific toolchain instructions follow: 484 485 * Microsoft Windows 486 ** <<depends-ubuntu,Ubuntu / Windows 10>> 487 ** <<depends-mingw,MinGW>> (PDF builds not tested) 488 ** <<depends-cygwin,Cygwin>> 489 * <<depends-osx,Mac OS X>> 490 * <<depends-linux,Linux (Debian, Ubuntu, etc.)>> 491 492 493 [[depends-windows]] 494 === Windows (General) 495 496 Most of the dependencies on Linux packages are light enough that it's 497 possible to build the spec natively in Windows, but it means bypassing the 498 makefile and calling functions directly. 499 Considering how easy it is to get an Unix subsystem or VM on Windows, this 500 is not recommended. 501 It is unlikely a direct path will become supported in the future. 502 503 Three options for Windows users are described below: Ubuntu / Windows 10 504 (best, as long as you're running Windows 10), MinGW, and Cygwin. 505 506 507 [[depends-ubuntu]] 508 ==== Ubuntu / Windows 10 509 510 At the time of writing Ubuntu Subsystem is provided in 18.04 LTS and 511 16.04 LTS versions. 512 These versions are perfectly suitable for building this repo. 513 514 You can install Ubuntu Subsystem as described in the official documentation: 515 https://docs.microsoft.com/en-us/windows/wsl/install-win10 516 517 The distro image is not kept up-to-date, so it is recommended to run: 518 519 ---- 520 sudo apt update 521 sudo apt full-upgrade 522 ---- 523 524 Rest is identical to <<depends-linux,Linux instructions>>. 525 526 527 [[depends-mingw]] 528 ==== MinGW 529 530 MinGW can be obtained here: http://www.mingw.org/ 531 532 Once the installer has run its initial setup, following the 533 http://www.mingw.org/wiki/Getting_Started[instructions on the website], you 534 should install the `mingw-developer-tools`, `mingw-base` and `msys-base` 535 packages. 536 The `msys-base` package allows you to use a bash terminal from windows with 537 whatever is normally in your path on Windows, as well as the unix tools 538 installed by MinGW. 539 540 In the native Windows environment, you should also install the following 541 native packages: 542 543 * Python 3.x (https://www.python.org/downloads/) 544 * Ruby 2.x (https://rubyinstaller.org/) 545 * Git command-line client (https://git-scm.com/download) 546 547 Once this is setup, and the necessary <<depends-gems,Ruby Gems>> are 548 installed, launch the `msys` bash shell, and navigate to the spec Makefile. 549 From there, you'll need to set `PYTHON=` to the location of your python 550 executable for version 3.x before your make command - but otherwise 551 everything other than pdf builds should just work. 552 553 NOTE: Building the PDF spec via this path has not yet been tested but *may* 554 be possible - liblasem is the main issue and it looks like there is now a 555 mingw32 build of it available. 556 557 558 [[depends-cygwin]] 559 ==== Cygwin 560 561 When installing Cygwin, you should install the following packages via 562 `setup`: 563 564 ---- 565 // "curl" is only used to download fonts, can be done in another way 566 autoconf 567 bison 568 cmake 569 curl 570 flex 571 gcc-core 572 gcc-g++ 573 ghostscript 574 git 575 libbz2-devel 576 libcairo-devel 577 libcairo2 578 libffi-devel 579 libgdk_pixbuf2.0-devel 580 libiconv 581 libiconv-devel 582 liblasem0.4-devel 583 libpango1.0-devel 584 libpango1.0_0 585 libxml2 586 libxml2-devel 587 make 588 python3 589 ruby 590 ruby-devel 591 ---- 592 593 NOTE: Native versions of some of these packages are usable, but care should 594 be taken for incompatibilities with various parts of cygwin - e.g. paths. 595 Ruby in particular is unable to resolve Windows paths correctly via the 596 native version. 597 Python and Git for Windows can be used, though for Python you'll need to set 598 the path to it via the PYTHON environment variable, before calling make. 599 600 When it comes to installing the mathematical ruby gem, there are two things 601 that will require tweaking to get it working. 602 Firstly, instead of: 603 604 ---- 605 MATHEMATICAL_SKIP_STRDUP=1 gem install asciidoctor-mathematical 606 ---- 607 608 You should use 609 610 ---- 611 MATHEMATICAL_USE_SYSTEM_LASEM=1 gem install asciidoctor-mathematical 612 ---- 613 614 The latter causes it to use the lasem package already installed, rather than 615 trying to build a fresh one. 616 617 Recent versions of some gems break the installation process and/or pdf build 618 on some systems. If the above doesn't work, try: 619 620 ---- 621 MATHEMATICAL_USE_SYSTEM_LASEM=1 gem install mathematical -v 1.6.7 622 gem install ruby-enum -v 0.7.0 623 gem install asciidoctor-mathematical 624 ---- 625 626 The mathematical gem also looks for "liblasem" rather than "liblasem0.4" as 627 installed by the lasem0.4-devel package, so it is necessary to add a symlink 628 to your /lib directory using: 629 630 ---- 631 ln -s /lib/liblasem-0.4.dll.a /lib/liblasem.dll.a 632 ---- 633 634 <<Ruby Gems>> are not installed to a location that is in your path normally. 635 Gems are installed to `~/bin/` - you should add this to your path before 636 calling make: 637 638 export PATH=~/bin:$PATH 639 640 Finally, you'll need to manually install fonts for lasem via the following 641 commands: 642 643 ---- 644 mkdir /usr/share/fonts/truetype cd /usr/share/fonts/truetype 645 curl -LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/cmex10.ttf \ 646 -LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/cmmi10.ttf \ 647 -LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/cmr10.ttf \ 648 -LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/cmsy10.ttf \ 649 -LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/esint10.ttf \ 650 -LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/eufm10.ttf \ 651 -LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/msam10.ttf \ 652 -LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/msbm10.ttf 653 ---- 654 655 [[depends-linux]] 656 === Linux (Debian, Ubuntu, etc.) 657 658 System dependencies can be installed via apt: 659 660 ---- 661 sudo apt install build-essential python3 git cmake bison flex \ 662 libffi-dev libxml2-dev libgdk-pixbuf2.0-dev libcairo2-dev \ 663 libpango1.0-dev fonts-lyx ghostscript libreadline-dev 664 ---- 665 666 [NOTE] 667 .Note 668 ==== 669 On Ubuntu versions prior to 18.04 LTS, you will probably need to use the 670 `ttf-lyx` package instead of `fonts-lyx`. 671 ==== 672 673 These instructions are for the Ubuntu installation and are generally 674 applicable to native Linux environments that use Debian packages, although 675 the exact list of packages to install may differ. 676 Other distributions using different package managers, such as RPM (Fedora) 677 and Yum (SuSE) will have different requirements. 678 679 Ruby can also be installed as a system package: 680 681 ---- 682 sudo apt install ruby ruby-dev 683 ---- 684 685 Ruby packages are often well out of date, so using <<ruby-env,alternative 686 ruby environments>> such as `rbenv` or `rvm` might be preferable. 687 688 Once the Ruby environment is set up, install the required 689 <<depends-gems,Ruby Gems>>. 690 691 If you will need to generate the chunked HTML target, install the 692 <<depends-chunker, Asciidoctor-chunker>> dependencies as described below. 693 694 695 [[depends-osx]] 696 === Mac OS X 697 698 Mac OS X should work in the same way as for Ubuntu by using the Homebrew 699 package manager, with the exception that you can simply install the ruby 700 package via `brew` rather than using a ruby-specific version manager. 701 702 You'll likely also need to install additional fonts for the PDF build via 703 mathematical, which you can do with: 704 705 ---- 706 cd ~/Library/Fonts 707 curl -LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/cmex10.ttf \ 708 -LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/cmmi10.ttf \ 709 -LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/cmr10.ttf \ 710 -LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/cmsy10.ttf \ 711 -LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/esint10.ttf \ 712 -LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/eufm10.ttf \ 713 -LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/msam10.ttf \ 714 -LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/msbm10.ttf 715 ---- 716 717 Then install the required <<depends-gems,Ruby Gems>>. 718 719 720 [[depends-gems]] 721 === Ruby Gems 722 723 The following ruby gems can be installed directly via the `gem install` 724 command, once the platform is set up: 725 726 ---- 727 gem install --no-rdoc --no-ri asciidoctor coderay json-schema asciidoctor-mathematical asciidoctor-diagram 728 gem install --no-rdoc --no-ri --pre asciidoctor-pdf 729 ---- 730 731 Depending on Ruby environment `gem` may require `sudo`. 732 733 It may significantly speed up installation if you skip documentation build 734 by passing `--no-rdoc --no-ri` arguments. 735 736 It may be beneficial to use updated packages via: 737 738 ---- 739 gem update --no-rdoc --no-ri 740 gem clean 741 ---- 742 743 744 [[depends-chunker]] 745 === Asciidoctor-chunker and Index Generation 746 747 To generate the `chunked` HTML target, you must install 748 https://github.com/wshito/asciidoctor-chunker[`asciidoctor-chunker`] and 749 the underlying https://github.com/roswell/roswell/releases[`Roswell`] 750 compiler and related dependencies. These projects do not seem to support 751 standard software repositories and packaging (e.g. RPM, .deb, etc.), so 752 you will need to follow the 753 https://github.com/wshito/asciidoctor-chunker[How to Install] directions 754 for asciidoctor-chunker. 755 756 Note that both Roswell and asciidoctor-chunker are installed outside the 757 scope of the Vulkan Specification repository (in system directories, and 758 in your home directory, respectively). 759 760 You must also install these Javascript dependencies to generate the 761 index, partly as system packages, and partly with npm. Note that npm is not 762 packaged for Debian 9, thus it's installed from deb.nodesource.com following 763 https://linuxize.com/post/how-to-install-node-js-on-debian-9/ 764 765 ---- 766 curl -sL https://deb.nodesource.com/setup_8.x | sudo bash - 767 # nodejs also installs npm 768 sudo apt install nodejs 769 sudo npm install -g lunr@2.3.6 770 setenv NODE_PATH /usr/lib/node_modules 771 ---- 772 773 [[troubleshooting]] 774 == Troubleshooting 775 776 This section goes over known problems and solutions for toolchain 777 installation or for build. 778 779 If you get arbitrary build errors it can't hurt to first try resolve it by 780 cleaning the tree: 781 782 ---- 783 make clean 784 git clean -dxf 785 ---- 786 787 788 === STEM SVG Errors 789 790 If you happen to have `_` or other Asciidoctor formating characters in your 791 path, then PDF build using `asciidoctor-mathematical` may fail with: 792 793 ---- 794 asciidoctor: WARNING: image to embed not found or not readable: whatever/<em>stuff/Vulkan-Docs/out/equations_temp/stem-d3355033150173c1d397e342237db405.svg 795 ---- 796 797 See https://github.com/asciidoctor/asciidoctor-mathematical/issues/43. 798 799 You simply need to have the repository cloned in a simpler path. 800 801 802 === Ghostscript Errors 803 804 Ghostscript optimization of the PDF may produce: 805 806 ---- 807 **** Error reading a content stream. The page may be incomplete. 808 Output may be incorrect. 809 **** Error: File did not complete the page properly and may be damaged. 810 Output may be incorrect. 811 ---- 812 813 Usually, it is just a problem with the Asciidoc sources (e.g. silent failure 814 to render content that does not fit in the page; such as SVG equations where 815 there is no line break opportunity). 816 817 818 === Ruby Gem Versioning Errors 819 820 Sometimes, when updating ruby gem packages incompatibilities arise. 821 It is resoleved by identifying the offending packages and downgrading them: 822 823 ---- 824 $ gem uninstall package_name 825 $ gem install package_name --version good_version_number 826 ---- 827 828 If you already have the gem dependencies previously installed, if there are 829 new versions, then updating to them instead might help: 830 831 ---- 832 $ gem update --no-rdoc --no-ri 833 ---- 834 835 *ruby-enum* 836 837 We have seen this PDF build error: 838 ---- 839 Failed to load AsciiDoc document - wrong constant name default (NameError) 840 ---- 841 842 It should not be occurring with updated packages. 843 Make sure you are using `ruby-enum 0.7.1` or later, and `mathematical 1.6.8` 844 or later. 845 If you are forced to use earlier versions, see 846 https://github.com/gjtorikian/mathematical/issues/69 for a report of a 847 related versioning problem. 848 849 *prawn* 850 851 Make sure you are using prawn 2.2.1 or later, and prawn-templates 0.0.5 or 852 later. Incompatibilities between `asciidoctor-pdf` and earlier versions of 853 these gems affects the PDF build. See 854 https://github.com/KhronosGroup/Vulkan-Docs/issues/476 855 856 857 === asciidoctor-mathematical gem native extension errors 858 859 Installing `mathematical` gem builds `lasem` and `mtex2MML` native binaries. 860 The <<depends,Dependencies>> we list should be sufficient for the install to 861 build those native extensions successfully. 862 863 If you encounter problems, it is possible to use those binaries from 864 preinstalled locations. 865 See https://github.com/gjtorikian/mathematical#troubleshooting. 866 867 868 === Asciidoctor include errors 869 870 If you get errors like: 871 872 ---- 873 asciidoctor: ERROR: chapters/???.txt: line 189: include file not found: ???/Vulkan-Docs/api/protos/???.txt 874 ---- 875 876 you probably forgot to call `make clean_generated` as stated in the 877 <<building-extensions>> chapter. 878 879 === Asciidoctor-chunker memory exhaustion 880 881 If you get errors like: 882 883 ---- 884 ASCIIDOCTOR-CHUNKER: Processing Chap 17 .... 885 Heap exhausted during garbage collection: 224 bytes available, 288 requested. 886 ... 887 GC control variables: 888 *GC-INHIBIT* = true 889 *GC-PENDING* = true 890 *STOP-FOR-GC-PENDING* = false 891 fatal error encountered in SBCL pid 31086(tid 0x7f4816866700): 892 Heap exhausted, game over. 893 ---- 894 895 try specifying a larger dynamic space size, something bigger than 2000: 896 897 ---- 898 $ ROSWELLOPTS="dynamic-space-size=2500" ./makeAllExts html chunked 899 ---- 900 901 [[ruby-env]] 902 == Alternative Ruby environments 903 904 The default `ruby` packages on Linux distro may be out of date. 905 Through the default `ruby` package, Ubuntu 18.04 provides ruby 2.5, and 906 Ubuntu 16.10 provides ruby 2.3. 907 Those system packages seem to be sufficient to build this repo. 908 909 But there are better options; either https://rvm.io[rvm] or 910 https://github.com/rbenv/rbenv[rbenv] is recommended to install an updated 911 version of Ruby environment. 912 913 [NOTE] 914 .Note 915 ==== 916 * If you are new to Ruby, you should *completely remove* (through the 917 package manager, e.g. `sudo apt purge *packagename*`) all existing 918 Ruby and asciidoctor infrastructure on your machine before trying to use 919 rvm or rbenv for the first time. 920 `dpkg -l | egrep 'asciidoctor|ruby|rbenv|rvm'` will give you a list of 921 candidate package names to remove. 922 ** If you already have a favorite Ruby package manager, ignore this 923 advice, and just install the required OS packages and gems. 924 * In addition, `rvm` and `rbenv` are *mutually incompatible*. 925 They both rely on inserting shims and `$PATH` modifications in your bash 926 shell. 927 If you already have one of these installed and are familiar with it, 928 it's probably best to stay with that one. 929 One of the editors, who is new to Ruby, found `rbenv` far more 930 comprehensible than `rvm`. 931 The other editor likes `rvm` better. 932 ** Neither `rvm` nor `rbenv` work, out of the box, when invoked from 933 non-Bash shells like `tcsh`. 934 This can be hacked up by setting the right environment variables and 935 `PATH` additions based on a bash environment. 936 * Most of the tools on Bash for Windows are quite happy with Windows line 937 endings (`CR LF`), but bash scripts expect Unix line endings (`LF`). 938 The file `.gitattributes` at the top of the vulkan tree forces such 939 scripts to be checked out with the proper line endings on non-Linux 940 platforms. 941 If you add new scripts whose names don't end in `.sh`, they should be 942 included in `.gitattributes` as well. 943 ==== 944 945 946 [[depends-ubuntu-rbenv]] 947 ===== Ubuntu/Windows 10 Using Rbenv 948 949 Rbenv is a lighter-weight Ruby environment manager with less functionality 950 than rvm. 951 Its primary task is to manage different Ruby versions, while rvm has 952 additional functionality such as managing "`gemsets`" that is irrelevant to 953 our needs. 954 955 A complete installation script for the toolchain on Ubuntu for Windows, 956 developed on an essentially out-of-the-box environment, follows. 957 If you try this, don't try to execute the entire thing at once. 958 Do each step separately in case of errors we didn't encounter. 959 960 ---- 961 # Install packages needed by `ruby_build` and by toolchain components. 962 # See https://github.com/rbenv/ruby-build/wiki and 963 # https://github.com/asciidoctor/asciidoctor-mathematical#dependencies 964 965 sudo apt-get install autoconf bison build-essential libssl-dev \ 966 libyaml-dev libreadline6-dev zlib1g-dev libncurses5-dev \ 967 libffi-dev libgdbm3 libgdbm-dev cmake libxml2 \ 968 libxml2-dev flex pkg-config libglib2.0-dev \ 969 libcairo-dev libpango1.0-dev libgdk-pixbuf2.0-dev \ 970 libpangocairo-1.0 libreadline-dev 971 972 # Install rbenv from https://github.com/rbenv/rbenv 973 git clone https://github.com/rbenv/rbenv.git ~/.rbenv 974 975 # Set path to shim layers in .bashrc 976 echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> .bashrc 977 978 ~/.rbenv/bin/rbenv init 979 980 # Set .rbenv environment variables in .bashrc 981 echo 'eval "$(rbenv init -)"' >> .bashrc 982 983 # Restart your shell (e.g. open a new terminal window). Note that 984 # you do not need to use the `-l` option, since the modifications 985 # were made to .bashrc rather than .bash_profile. If successful, 986 # `type rbenv` should print 'rbenv is a function' followed by code. 987 988 # Install `ruby_build` plugin from https://github.com/rbenv/ruby-build 989 990 git clone https://github.com/rbenv/ruby-build.git ~/.rbenv/plugins/ruby-build 991 992 # Install Ruby 2.5.3 (current as of this writing; earlier may work) 993 # Setting RUBY_CONFIGURE_OPTS dramatically cuts the install time, see 994 # https://github.com/rbenv/ruby-build/issues/1054#issuecomment-276934761 995 RUBY_CONFIGURE_OPTS=--disable-install-doc 996 export RUBY_CONFIGURE_OPTS 997 rbenv install 2.5.3 998 999 # Configure rbenv globally to always use Ruby 2.5.3. 1000 echo "2.5.3" > ~/.rbenv/version 1001 1002 # Finally, install toolchain components. 1003 # asciidoctor-mathematical also takes in excess of 20 min. to build! 1004 # The same RUBY_CONFIGURE_OPTS advice above may apply here as well. 1005 1006 gem install --no-rdoc --no-ri asciidoctor coderay json-schema asciidoctor-mathematical asciidoctor-diagram 1007 gem install --no-rdoc --no-ri --pre asciidoctor-pdf 1008 ---- 1009 1010 1011 [[depends-ubuntu-rvm]] 1012 ===== Ubuntu/Windows 10 Using RVM 1013 1014 Here are (sparser) instructions for using rvm to setup version 2.3.x: 1015 1016 ---- 1017 gpg --keyserver hkp://keys.gnupg.net --recv-keys 409B6B1796C275462A1703113804BB82D39DC0E3 1018 \curl -sSL https://get.rvm.io | bash -s stable --ruby 1019 source ~/.rvm/scripts/rvm 1020 rvm install ruby-2.3 1021 rvm use ruby-2.3 1022 ---- 1023 1024 NOTE: Windows 10 Bash will need to be launched with the "-l" option 1025 appended, so that it runs a login shell; otherwise RVM won't function 1026 correctly on future launches. 1027 1028 1029 [[history]] 1030 == Revision History 1031 1032 * 2018-12-04 - Update Rbenv and ruby gem installation instructions and 1033 package dependencies for Linux and Ubuntu/Windows 10. 1034 * 2018-10-25 - Update Troubleshooting, and Windows and Linux build. Plus 1035 random editing. 1036 * 2018-03-13 - Rename to BUILD.adoc and update for new directory 1037 structure. 1038 * 2018-03-05 - Update README for Vulkan 1.1 release. 1039 * 2017-03-20 - Add description of prawn versioning problem and how to fix 1040 it. 1041 * 2017-03-06 - Add description of ruby-enum versioning problem and how to 1042 fix it. 1043 * 2017-02-13 - Move some comments here from ../../../README.md. Tweak 1044 asciidoctor markup to more clearly delineate shell command blocks. 1045 * 2017-02-10 - Add more Ruby installation guidelines and reflow the 1046 document in accordance with the style guide. 1047 * 2017-01-31 - Add rbenv instructions and update the README elsewhere. 1048 * 2017-01-16 - Modified dependencies for Asciidoctor 1049 * 2017-01-06 - Replace MathJax with KaTeX. 1050 * 2016-08-25 - Update for the single-branch model. 1051 * 2016-07-10 - Update for current state of spec and ref page generation. 1052 * 2015-11-11 - Add new can: etc. 1053 macros and DBLATEXPREFIX variable. 1054 * 2015-09-21 - Convert document to asciidoc and rename to README.md in the 1055 hope the gitlab browser will render it in some fashion. 1056 * 2015-09-21 - Add descriptions of LaTeX and MathJax math support for all 1057 output formats. 1058 * 2015-09-02 - Added Cygwin package info. 1059 * 2015-09-02 - Initial version documenting macros, required toolchain 1060 components and versions, etc.