|
Note
|
Note
This is based on the Vulkan README, and has not been fully updated for OpenVX-specific changes to the build process. The most useful parts are the Introduction, Building The Spec, and notes on installing Software Dependencies. |
This README describes important stuff for getting the OpenVX API specification and reference pages building properly.
Once you have all the right tools installed (see Software
Dependencies below), go to …path-to-git-repo/docs/specification .
$ make
or make the individual targets html and pdf.
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/1.0/index.html links to all these
targets, or they can individually be found as follows:
-
API spec:
-
html- Single-file HTML5 in$(OUTDIR)/html/vkspec.html -
pdf- PDF in$(OUTDIR)/pdf/vkspec.pdf
-
To insert a tag into specification use below text pattern. Don’t forget to add space before the tag.
This marks a tag without numeric ID. The config/spec-tags.py will help to add unique numeric IDs to tags.
`[*REQ*]`To automatically insert unique numeric IDs into new tags, use the following script:
% python config/spec-tags.py update OpenVX_Specification.adocFor further details, use % python config/spec-tags.py -help.
All the extensions (complete or otherwise) in the tree were converted to asciidoc markup and can be built. The source for the API specification is in 'OpenVX_Specification.txt' while each extension is in 'vx_extension_name.txt'. Build an extension by passing SPECBASE=vx_extension_name to make, e.g.
make SPECBASE=vx_khr_nn html
A helper script, makeAllSpecs, can be called as
makeAllSpecs html (or pdf, or both)
If you are just testing asciidoc formatting, macros, stylesheets, etc., you
may want to edit OpenVX_Specification.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.
There are some images in the images/ directory which are maintained in one
format but need to be converted to another format for corresponding types of
output.
Most are SVG converted to PDF, some are PPT converted to PDF converted to
SVG.
SVG are needed by all builds.
These files are not automatically converted by the Makefile.
Instead, all output forms required are checked into images/ .
On the rare occasions that someone changes a source document and needs to
regenerate the other forms:
cd images ; make
We use a modified version of the Asciidoctor 'colony' theme, altered to more closely resemble the Doxygen stylesheet.
Where possible, equations should be written using straight asciidoc markup using the eq role. This covers many common equations and is faster than the alternatives.
For more complex equations, such as multi-case statements, matrices, and complex fractions, equations should be written using the latexmath: inline and block macros. The contents of the latexmath: blocks should be LaTeX math notation. LaTeX math markup delimiters are now inserted by the asciidoctor toolchain.
LaTeX math is passed through unmodified to all HTML output forms, which is
subsequently rendered with the KaTeX engine when the html is loaded.
A local copy of the KaTeX release is kept in doc/specs/vulkan/katex and
copied to the HTML output directory during spec generation.
Math is processed into SVGs via asciidoctor-mathematical for PDF output.
The following caveats apply:
-
The special characters
<,>, and&can currently be used only in [latexmath] block macros, not in latexmath:[] inline macros. Instead use\lt,\leq,\gt, and\geqfor<,⇐,>, and>=respectively.&is an alignment construct for multiline equations, and should only appear in block macros anyway. -
AMSmath environments (e.g. \begin{equation*}, {align*}, etc.) cannot be used in KaTeX at present, and have been replaced with constructs supported by KaTeX such as {aligned}.
-
Arbitrary LaTeX constructs cannot be used. KaTeX and asciidoctor-mathematical are only equation renderers, not full LaTeX engines. Imbedding LaTeX like \Large or \hbox{\tt\small VK\_FOO} may not work in any of the backends, and should be avoided.
See the “OpenVX Documentation and Extensions” document for more details of supported LaTeX math constructs.
In the API spec, sections can have anchors (labels) applied with the following syntax. In general the anchor should immediately precede the chapter or section title and should use the form '[[chapter-section-label]]'. For example,
For example, from the Vulkan specification we have:
[[synchronization-primitives]] Synchronization Primitives
Cross-references to those anchors can then be generated with, for example,
See the <<synchronization-primitives>> section for discussion of fences, semaphores, and events.
You can also add anchors on arbitrary paragraphs, using a similar naming scheme.
Anything whose definition comes from one of the autogenerated API include
files (.txt files in the directories api/basetypes, api/enums,
api/flags, api/funcpointers, api/handles, api/protos, and
api/structs) has a corresponding anchor whose name is the name of the
function, struct, etc. being defined. Therefore you can say something like:
Fences are used with the +++<<vkQueueSubmit>>+++ command...
This section describes the software components used by the OpenVX spec toolchain.
Before building the OpenVX spec, you must install the following tools:
-
GNU make (make version: 4.0.8-1; older versions probably OK)
-
Python 3 (python, version: 3.4.2)
-
Ruby (ruby, version: 2.3.3)
-
The Ruby development package (ruby-dev) may also be required in some environments.
-
-
Git command-line client (git, version: 2.1.4). The build can progress without a git client, but branch/commit information will be omitted from the build. Any version supporting the following operations should work:
-
git symbolic-ref --short HEAD -
git log -1 --format="%H"
-
-
Ghostscript (ghostscript, version: 9.10). 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 smaller if it is included.
The following Ruby Gems and platform package dependencies must also be installed. Versions known to work are listed for each gem. Earlier versions can, and probably will, not work properly in some respects.
Installing gems and package dependencies is described in more detail for individual platforms and environment managers below. Please read the remainder of this document (other than platform-specific parts you don’t use) completely before trying to install.
-
Asciidoctor (asciidoctor, version: 1.5.8)
-
Coderay (coderay, version 1.1.1)
-
JSON Schema (json-schema, version 2.8.1)
-
Asciidoctor PDF (asciidoctor-pdf, version: 1.5.0.alpha16)
-
Asciidoctor Mathematical (asciidoctor-mathematical, version 0.2.2)
-
Dependencies for asciidoctor-mathematical (There are a lot of these!)
-
KaTeX distribution (version 0.7.0 from https://github.com/Khan/KaTeX . This is cached under
doc/specs/vulkan/katex/, and need not be installed from github. -
asciidoctor-diagram (https://asciidoctor.org/docs/asciidoctor-diagram/, version: 1.5.11)
Only the asciidoctor and coderay gems are needed if you don’t intend to
build PDF versions of the spec and supporting documents.
json-schema is only required in order to validate the output of the valid
usage extraction scripts to a JSON file.
If not installed, validation will be skipped when the JSON is built.
|
Note
|
Note
While it’s easier to install just the toolchain components for HTML builds,
people submitting MRs with substantial changes to the Specification are
responsible for verifying that their branches build both |
Platform-specific toolchain instructions follow:
-
Microsoft Windows
-
MinGW (PDF builds not tested)
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 makefile and calling functions directly. This might be solved in future. For now, there are three options for Windows users: Ubuntu / Windows 10, MinGW, or Cygwin.
When using the “Ubuntu Subsystem” for Windows 10, most dependencies can be installed via apt-get:
sudo apt-get -qq -y install build-essential python3 git cmake bison flex \
libffi-dev libgmp-dev libxml2-dev libgdk-pixbuf2.0-dev libcairo2-dev \
libpango1.0-dev ttf-lyx gtk-doc-tools ghostscript
The default ruby packages on Ubuntu are fairly out of date.
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 rvm or rbenv is recommended to install a more recent version.
|
Note
|
Note
|
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 libgmp-dev 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
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. |
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.
MinGW can be obtained here: http://www.mingw.org/
Once the installer has run its initial setup, following the
instructions on the website, you
should install the mingw-developer-tools, mingw-base and msys-base
packages.
The msys-base package allows you to use a bash terminal from windows with
whatever is normally in your path on Windows, as well as the unix tools
installed by MinGW.
In the native Windows environment, you should also install the following native packages:
-
Python 3.x (https://www.python.org/downloads/)
-
Ruby 2.x (https://rubyinstaller.org/)
-
Git command-line client (https://git-scm.com/download)
Once this is setup, and the necessary Ruby Gems are
installed, launch the msys bash shell, and navigate to the spec Makefile.
From there, you’ll need to set PYTHON= to the location of your python
executable for version 3.x before your make command - but otherwise
everything other than pdf builds should just work.
|
Note
|
Building the PDF spec via this path has not yet been tested but may be possible - liblasem is the main issue and it looks like there is now a mingw32 build of it available. |
When installing Cygwin, you should install the following packages via
setup:
// "curl" is only used to download fonts, can be done in another way autoconf bison cmake curl flex gcc-core gcc-g++ ghostscript git libbz2-devel libcairo-devel libcairo2 libffi-devel libgdk_pixbuf2.0-devel libgmp-devel libiconv libiconv-devel liblasem0.4-devel libpango1.0-devel libpango1.0_0 libxml2 libxml2-devel make python3 ruby ruby-devel
|
Note
|
Native versions of some of these packages are usable, but care should be taken for incompatibilities with various parts of cygwin - e.g. paths. Ruby in particular is unable to resolve Windows paths correctly via the native version. Python and Git for Windows can be used, though for Python you’ll need to set the path to it via the PYTHON environment variable, before calling make. |
When it comes to installing the mathematical ruby gem, there are two things that will require tweaking to get it working. Firstly, instead of:
MATHEMATICAL_SKIP_STRDUP=1 gem install asciidoctor-mathematical
You should use
MATHEMATICAL_USE_SYSTEM_LASEM=1 gem install asciidoctor-mathematical
The latter causes it to use the lasem package already installed, rather than trying to build a fresh one.
The mathematical gem also looks for "liblasem" rather than "liblasem0.4" as installed by the lasem0.4-devel package, so it is necessary to add a symlink to your /lib directory using:
ln -s /lib/liblasem-0.4.dll.a /lib/liblasem.dll.a
Ruby Gems are not installed to a location that is in your path normally.
Gems are installed to ~/bin/ - you should add this to your path before
calling make:
export PATH=~/bin:$PATH
Finally, you’ll need to manually install fonts for lasem via the following commands:
mkdir /usr/share/fonts/truetype cd /usr/share/fonts/truetype
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/cmmi10.ttf \
-LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/cmr10.ttf \
-LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/cmsy10.ttf \
-LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/esint10.ttf \
-LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/eufm10.ttf \
-LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/msam10.ttf \
-LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/msbm10.ttf
Mac OS X should work in the same way as for ubuntu by using the Homebrew
package manager, with the exception that you can simply install the ruby
package via brew rather than using a ruby-specific version manager.
You’ll likely also need to install additional fonts for the PDF build via mathematical, which you can do with:
cd ~/Library/Fonts
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/cmmi10.ttf \
-LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/cmr10.ttf \
-LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/cmsy10.ttf \
-LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/esint10.ttf \
-LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/eufm10.ttf \
-LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/msam10.ttf \
-LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/msbm10.ttf
Then install the required Ruby Gems.
The instructions for the 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 Ruby Gems.
The following ruby gems can be installed directly via the gem install
command, once the platform is set up:
gem install rake asciidoctor coderay json-schema # Required only for pdf builds MATHEMATICAL_SKIP_STRDUP=1 gem install asciidoctor-mathematical gem install --pre asciidoctor-pdf gem install --pre asciidoctor-diagram
To make sure you have the latest versions of installed gems, periodically execute
gem update