= OpenCL^(TM)^ Specification Build Instructions and Notes :toc2: :toclevels: 1
master to main.[[intro]] == Introduction
This repository contains the source and tool chain used to generate the formal OpenCL API, OpenCL C, OpenCL Extensions, OpenCL SPIR-V Environment, OpenCL C++ Specifications, as well as the OpenCL Reference Pages and documentation for the C++ for OpenCL kernel language.
This file describes the repository structure, tools, and build instructions needed.
[[source]] == Source Code
The OpenCL specifications are maintained by members of the Khronos Group's OpenCL Working Group, in the https://github.com/KhronosGroup/OpenCL-Docs[OpenCL-Docs Github repository]. The documents are all in https://asciidoctor.org/[Asciidoctor] format.
Contributions via pull requests on Github are welcome. Pull requests must be
provided under the same <<license, Creative Commons license>> as the
specification source.
You'll be prompted with a one-time "click-through" Contributor's License
Agreement (CLA) dialog as part of submitting your pull request or other
contribution to GitHub.
We intend to maintain a linear history on the GitHub main branch.
[[repo]] == Repository Structure
|====
| File | Description
| README.adoc | This file
| Makefile | GNU Makefile used to build HTML and PDF spec targets
| config/ | Support files for asciidoctor build, HTML CSS / Javascript, etc.
| katex/ | KaTeX math renderer for HTML outputs
| OpenCL_API.txt | Main source file for the OpenCL API Specification
| api/ | Individual sections of the API Specification
| OpenCL_C.txt | Main source file for the OpenCL C Specification
| c/ | Individual sections of the C Specification
| OpenCL_Cxx.txt | Main source file for the OpenCL C++ Specification
| cxx/ | Individual sections of the C++ Specification
| OpenCL_Env.txt | Main source file for the OpenCL SPIR-V Environment Specification
| env/ | Individual sections of the Environment Specification
| OpenCL_Ext.txt | Main source file for the OpenCL Extensions Specification
| ext/ | Individual sections of the Extensions Specification
| CXX_for_OpenCL.txt | Main source file for the C++ for OpenCL Documentation
| cxx4opencl/ | Individual sections of the C++ for OpenCL Documentation
| images/ | Shared images, used by all specs
| man/ | Static reference page sources
|====
[[building]] == Building The Specifications and Reference Pages
If you have installed all <<depends,required toolchain components>>, you should be able to build both HTML and PDF outputs for all specifications by:
$ makeOther Makefile targets are available for building the different outputs for each Specification:
| ==== | Target | Builds | html | HTML outputs for all specifications | PDF outputs for all specifications | |
|---|---|---|---|---|---|---|
| api | HTML and PDF outputs for API Specification | |||||
| apihtml | HTML outputs for API Specification | |||||
| apipdf | PDF outputs for API Specification | |||||
| c | HTML and PDF outputs for C Specification | |||||
| chtml | HTML outputs for C Specification | |||||
| cpdf | PDF outputs for C Specification | |||||
| cxx | HTML and PDF outputs for C++ Specification | |||||
| cxxhtml | HTML outputs for C++ Specification | |||||
| cxxpdf | PDF outputs for C++ Specification | |||||
| env | HTML and PDF outputs for SPIR-V Environment Specification | |||||
| envhtml | HTML outputs for Environment Specification | |||||
| envpdf | PDF outputs for Environment Specification | |||||
| ext | HTML and PDF outputs for Extensions Specification | |||||
| exthtml | HTML outputs for Extensions Specification | |||||
| extpdf | PDF outputs for Extensions Specification | |||||
| cxx4opencl | HTML and PDF outputs for C++ for OpenCL Documentation | |||||
| cxx4openclhtml | HTML outputs for C++ for OpenCL Documentation | |||||
| cxx4openclpdf | PDF outputs for C++ for OpenCL Documentation | |||||
| manhtmlpages | HTML outputs for Reference Pages | |||||
| ==== |
The specification targets are generated in out/html/ for HTML targets,
and out/pdf/ for PDF targets.
The reference page target is generated in out/man/html/.
If a different output directory is desired, set the Makefile variable
OUTDIR on the command line. For example,
will create /tmp/html/OpenCL_API.html.
These targets generate a variety of output documents in the directory
specified by the Makefile variable $(OUTDIR) (by default, out).
Once you have the basic build working, an appropriate parallelization option to make, such as
may significantly speed up building multiple specs. The asciidoctor HTML build is very fast, even for the whole Specification, but PDF builds may take several minutes.
[[building-extensions]] == Building With Extensions Included
Invoking 'make' with no extra arguments will build the OpenCL API and OpenCL
C Language specifications with only the core APIs and functionality
included.
To build versions of these specifications with extension language included,
you should use the makeSpec script.
makeSpec is a Python script accepting the following arguments:
core, khr, or all, building
specifications with only core, core + all khr extensions and core + all
extensions, respectively.
At present, all is equivalent to khr as only khr extensions are
included in the specification source.xml/cl.xml.make, so must be valid Makefile
targets or make options such as -j.Any other options reported by makeSpec --help are not yet functional, and
should not be used.
For example, to build with all khr extensions, you could use
makeSpec is a wrapper which constructs options and invokes make
when building with extensions included, which only affects building the API
(including reference pages) and C language specifications.
makeSpec determines extension dependencies from the metadata in the
specified registry XML path.
[[refpage-install]] == Reference Page Installation
Most of the reference pages are extracted from the OpenCL API and OpenCL
C Specifications, although some are static.
While anyone can generate reference page sets for themselves, Khronos
publishes them via the main branch of the
https://www.khronos.org/registry/OpenCL/sdk/3.0/docs/man/[OpenCL Registry].
When the OpenCL Specification Editor is updating the published reference pages, it is easiest to have local repository clones of this repository (OpenCL-Docs) as well as OpenCL-Registry. Update the pages in the local registry clone via
This creates the HTML output pages under sdk/3.0/docs/man/html, and copies
the KaTeX package to sdk/3.0/docs/katex.
To publish, commit those changes to the registry repository and push it to
github.
[[styles]] == Our stylesheets
We use a modified version of the Asciidoctor 'colony' theme. This theme is
maintained internally to Khronos and the resulting CSS is under
config/khronos.css.
[[equations]] == Imbedding Equations
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 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:
< , > , and & can currently be used only in
+++[latexmath]+++ block macros, not in +++latexmath:[]+++ inline macros.
Instead use \lt, \leq, \gt, and \geq for <, <=, >, and
>= respectively.
& is an alignment construct for multiline equations, and should only
appear in block macros anyway.See the "Vulkan Documentation and Extensions" document in the
https://www.khronos.org/registry/vulkan/specs/1.0/styleguide.html[Khronos
Vulkan Registry] for more details of supported LaTeX math constructs in our
toolchain.
[[anchors]] == Asciidoc Anchors And Xrefs
In asciidoctor, 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]]+++'.
Cross-references to those anchors can then be generated with, for example,
You can also add anchors on arbitrary paragraphs, using a similar naming scheme.
[[depends]] == Software Dependencies
This section describes the software components used by the OpenCL spec toolchain. The specified versions are known to work. Later compatible versions will probably work as well.
Before building the OpenCL specs, you must install the following tools:
git symbolic-ref --short HEAD
git log -1 --format="%H"The following Ruby Gems and platform package dependencies must also be installed. This process 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.
katex/, and need not be
installed from github.Only the asciidoctor, coderay, and rouge gems are needed if you don't
intend to build PDF versions of the spec and supporting documents.
html and pdf
targets.Platform-specific toolchain instructions follow:
[[depends-windows]] === Windows (General)
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.
[[depends-ubuntu]] ==== Ubuntu / Windows 10
When using the "Ubuntu Subsystem" for Windows 10, most dependencies can be
installed via apt-get:
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 https://rvm.io[rvm] or https://github.com/rbenv/rbenv[rbenv] is recommended to install a more recent version.
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.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 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..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.
ruby_build and by toolchain components.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
git clone https://github.com/rbenv/rbenv.git ~/.rbenv
echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> .bashrc
~/.rbenv/bin/rbenv init
echo 'eval "$(rbenv init -)"' >> .bashrc
-l option, since the modificationstype rbenv should print 'rbenv is a function' followed by code.ruby_build plugin from https://github.com/rbenv/ruby-buildgit clone https://github.com/rbenv/ruby-build.git ~/.rbenv/plugins/ruby-build
rbenv install 2.3.3
echo "2.3.3" > ~/.rbenv/version
[[depends-ubuntu-rvm]] ===== Ubuntu/Windows 10 Using RVM
Here are (sparser) instructions for using rvm to setup version 2.3.x:
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]] ==== MinGW
MinGW can be obtained here: http://www.mingw.org/
Once the installer has run its initial setup, following the
http://www.mingw.org/wiki/Getting_Started[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:
Once this is setup, and the necessary <<depends-gems,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.
[[depends-cygwin]] ==== Cygwin
When installing Cygwin, you should install the following packages via
setup:
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:
You should use
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:
<> 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:$PATHFinally, you'll need to manually install fonts for lasem via the following commands:
[[depends-osx]] === Mac OS X
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:
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]] === Ruby Gems
The following ruby gems can be installed directly via the gem install
command, once the platform is set up:
gem install asciidoctor -v 2.0.16 gem install coderay -v 1.1.1 gem install hexapdf -v 0.27.0 gen install rouge -v 3.19.0 gem install ttfunk -v 1.5.1
[[license]] == License
The specification Asciidoctor source files are licensed under the Creative Commons Attribution 4.0 International License; see https://creativecommons.org/licenses/by/4.0/
Additional source files used to build the specification are under a mixture of Apache 2.0 and MIT licenses. See the LICENSE file for details.
The official Specification HTML and PDF output documents are posted in the https://www.khronos.org/registry/OpenCL[OpenCL Registry]. These Specifications are placed under the proprietary Khronos specification copyright and license.
OpenCL and the OpenCL logo are trademarks of Apple Inc. used by permission by Khronos.
[[history]] == Revision History
makeSpec instructions.