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.

The OpenCL specifications are maintained by members of the Khronos Group’s OpenCL Working Group, in the OpenCL-Docs Github repository. The documents are all in Asciidoctor format.

Contributions via pull requests on Github are welcome. Pull requests must be provided under the same 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.

If you have installed all required toolchain components, you should be able to build both HTML and PDF outputs for all specifications by:

Other Makefile targets are available for building the different outputs for each Specification:

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.

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 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.

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.

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:

• The special characters < , > , 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.

• 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 “Vulkan Documentation and Extensions” document in the Khronos Vulkan Registry for more details of supported LaTeX math constructs in our toolchain.

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.

This section describes the software components used by the OpenCL spec toolchain.

Before building the OpenCL specs, 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.

• ttf Fonts. These are needed the PDF build for latexmath rendering. See Font Dependencies for asciidoctor-mathematical.

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.

• Asciidoctor (asciidoctor, version: 2.0.16)

• Coderay (coderay, version: 1.1.1)

• rouge (rouge, version 3.19.0)

• ttfunk (ttfunk, version: 1.5.1)

• Asciidoctor PDF (asciidoctor-pdf, version: 1.5.0)

• Asciidoctor Mathematical (asciidoctor-mathematical, version 0.3.5)

• 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 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.

Platform-specific toolchain instructions follow:

• Microsoft Windows

  • Ubuntu / Windows 10. The Windows 10 Ubuntu subsystem is recommended over MinGW and Cygwin for Windows builds, if possible, due to speed, similarity to the Linux toolchain, and the required packages being more likely to be up-to-date.

  • MinGW (PDF builds not tested)

  • Cygwin

• Mac OS X

• Linux (Debian, Ubuntu, etc.)

Windows (General)

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 fonts-lyx gtk-doc-tools ghostscript

# 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 -v 2.0.16
gem install coderay -v 1.1.1
gem install rouge -v 3.19.0
gem install ttfunk -v 1.5.1
gem install asciidoctor-pdf -v 1.5.0
gem install asciidoctor-mathematical -v 0.3.5

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

// "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

gem install asciidoctor-mathematical

MATHEMATICAL_USE_SYSTEM_LASEM=1 gem install asciidoctor-mathematical

ln -s /lib/liblasem-0.4.dll.a /lib/liblasem.dll.a

export PATH=~/bin:$PATH

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

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

Linux (Debian, Ubuntu, etc.)

Ruby Gems

gem install asciidoctor -v 2.0.16
gem install coderay -v 1.1.1
gen install rouge -v 3.19.0
gem install ttfunk -v 1.5.1

# Required only for pdf builds
gem install asciidoctor-pdf -v 1.5.0
gem install asciidoctor-mathematical -v 0.3.5

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 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.

• 2020-03-13 - Updated package versions to match Travis build.

• 2019-06-20 - Add directions for publishing OpenCL 2.2 reference pages, generated from the spec sources in this repository, in the OpenCL-Registry repository.

• 2018-02-15 - Retarget document from Vulkan repository for OpenCL asciidoctor spec builds.