{"id":27940508,"url":"https://github.com/khronosgroup/opencl-docs","last_synced_at":"2025-05-16T04:00:19.866Z","repository":{"id":37451236,"uuid":"91331376","full_name":"KhronosGroup/OpenCL-Docs","owner":"KhronosGroup","description":"OpenCL API, OpenCL C, Extensions, SPIR-V Environment Specs, Ref page, and C++ for OpenCL doc sources.","archived":false,"fork":false,"pushed_at":"2025-05-06T17:08:26.000Z","size":8504,"stargazers_count":374,"open_issues_count":289,"forks_count":120,"subscribers_count":51,"default_branch":"main","last_synced_at":"2025-05-07T10:17:27.293Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/KhronosGroup.png","metadata":{"files":{"readme":"README.adoc","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2017-05-15T11:44:22.000Z","updated_at":"2025-05-06T17:08:29.000Z","dependencies_parsed_at":"2023-02-19T11:45:56.173Z","dependency_job_id":"ce9b7ecd-1f85-45d4-8a85-61986670a8ad","html_url":"https://github.com/KhronosGroup/OpenCL-Docs","commit_stats":null,"previous_names":[],"tags_count":25,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KhronosGroup%2FOpenCL-Docs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KhronosGroup%2FOpenCL-Docs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KhronosGroup%2FOpenCL-Docs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KhronosGroup%2FOpenCL-Docs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/KhronosGroup","download_url":"https://codeload.github.com/KhronosGroup/OpenCL-Docs/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254464890,"owners_count":22075570,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-05-07T10:17:25.432Z","updated_at":"2025-05-16T04:00:19.628Z","avatar_url":"https://github.com/KhronosGroup.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"= OpenCL^(TM)^ Specification Build Instructions and Notes\n:toc2:\n:toclevels: 1\n\n[NOTE]\n.Note\n====\nThe most useful parts of this document are the \u003c\u003cintro, Introduction\u003e\u003e,\n\u003c\u003cbuilding, Building The Spec\u003e\u003e, and notes on installing \u003c\u003cdepends, Software\nDependencies\u003e\u003e.\n====\n\n[NOTE]\n.Note\n====\nThe default branch of this repository has changed from `master` to `main`.\n====\n\n[[intro]]\n== Introduction\n\nThis repository contains the source and tool chain used to generate the\nformal OpenCL API, OpenCL C, OpenCL Extensions, OpenCL SPIR-V Environment,\nOpenCL C++ Specifications, as well as the OpenCL Reference Pages\nand documentation for the C++ for OpenCL kernel language.\n\nThis file describes the repository structure, tools, and build instructions\nneeded.\n\n\n[[source]]\n== Source Code\n\nThe OpenCL specifications are maintained by members of the Khronos Group's\nOpenCL Working Group, in the\nhttps://github.com/KhronosGroup/OpenCL-Docs[OpenCL-Docs Github repository].\nThe documents are all in https://asciidoctor.org/[Asciidoctor] format.\n\nContributions via pull requests on Github are welcome. Pull requests must be\nprovided under the same \u003c\u003clicense, Creative Commons license\u003e\u003e as the\nspecification source.\nYou'll be prompted with a one-time \"`click-through`\" Contributor's License\nAgreement (CLA) dialog as part of submitting your pull request or other\ncontribution to GitHub.\n\nWe intend to maintain a linear history on the GitHub `main` branch.\n\n\n[[repo]]\n== Repository Structure\n\n|====\n| *File*                | *Description*\n| `README.adoc`         | This file\n| `Makefile`            | GNU Makefile used to build HTML and PDF spec targets\n| `config/`             | Support files for asciidoctor build, HTML CSS / Javascript, etc.\n| `katex/`              | KaTeX math renderer for HTML outputs\n| `OpenCL_API.txt`      | Main source file for the OpenCL API Specification\n| `api/`                | Individual sections of the API Specification\n| `OpenCL_C.txt`        | Main source file for the OpenCL C Specification\n| `c/`                  | Individual sections of the C Specification\n| `OpenCL_Cxx.txt`      | Main source file for the OpenCL C++ Specification\n| `cxx/`                | Individual sections of the C++ Specification\n| `OpenCL_Env.txt`      | Main source file for the OpenCL SPIR-V Environment Specification\n| `env/`                | Individual sections of the Environment Specification\n| `OpenCL_Ext.txt`      | Main source file for the OpenCL Extensions Specification\n| `ext/`                | Individual sections of the Extensions Specification\n| `CXX_for_OpenCL.txt`  | Main source file for the C++ for OpenCL Documentation\n| `cxx4opencl/`         | Individual sections of the C++ for OpenCL Documentation\n| `images/`             | Shared images, used by all specs\n| `man/`                | Static reference page sources\n|====\n\n\n[[building]]\n== Building The Specifications and Reference Pages\n\nIf you have installed all \u003c\u003cdepends,required toolchain components\u003e\u003e, you\nshould be able to build both HTML and PDF outputs for all specifications by:\n\n    $ make\n\nOther Makefile targets are available for building the different outputs\nfor each Specification:\n\n|====\n| *Target*       | *Builds*\n| html           | HTML outputs for all specifications\n| pdf            | PDF outputs for all specifications\n|                |\n| api            | HTML and PDF outputs for API Specification\n| apihtml        | HTML outputs for API Specification\n| apipdf         | PDF outputs for API Specification\n|                |\n| c              | HTML and PDF outputs for C Specification\n| chtml          | HTML outputs for C Specification\n| cpdf           | PDF outputs for C Specification\n|                |\n| cxx            | HTML and PDF outputs for C++ Specification\n| cxxhtml        | HTML outputs for C++ Specification\n| cxxpdf         | PDF outputs for C++ Specification\n|                |\n| env            | HTML and PDF outputs for SPIR-V Environment Specification\n| envhtml        | HTML outputs for Environment Specification\n| envpdf         | PDF outputs for Environment Specification\n|                |\n| ext            | HTML and PDF outputs for Extensions Specification\n| exthtml        | HTML outputs for Extensions Specification\n| extpdf         | PDF outputs for Extensions Specification\n|                |\n| cxx4opencl     | HTML and PDF outputs for C++ for OpenCL Documentation\n| cxx4openclhtml | HTML outputs for C++ for OpenCL Documentation\n| cxx4openclpdf  | PDF outputs for C++ for OpenCL Documentation\n|                |\n| manhtmlpages   | HTML outputs for Reference Pages\n|====\n\nThe specification targets are generated in `out/html/` for HTML targets,\nand `out/pdf/` for PDF targets.\nThe reference page target is generated in `out/man/html/`.\nIf a different output directory is desired, set the Makefile variable\nOUTDIR on the command line. For example,\n\n----\nmake OUTDIR=/tmp apihtml\n----\n\nwill create `/tmp/html/OpenCL_API.html`.\n\nThese targets generate a variety of output documents in the directory\nspecified by the Makefile variable `$(OUTDIR)` (by default, `out`).\n\nOnce you have the basic build working, an appropriate parallelization option\nto make, such as\n\n----\nmake -j 6\n----\n\nmay significantly speed up building multiple specs. The asciidoctor HTML\nbuild is very fast, even for the whole Specification, but PDF builds may\ntake several minutes.\n\n\n[[building-extensions]]\n== Building With Extensions Included\n\nInvoking 'make' with no extra arguments will build the OpenCL API and OpenCL\nC Language specifications with only the core APIs and functionality\nincluded.\nTo build versions of these specifications with extension language included,\nyou should use the `makeSpec` script.\n`makeSpec` is a Python script accepting the following arguments:\n\n  * -spec _variant_ - _variant_ is `core`, `khr`, or `all`, building\n    specifications with only core, core + all khr extensions and core + all\n    extensions, respectively.\n    At present, `all` is equivalent to `khr` as only `khr` extensions are\n    included in the specification source.\n  * -ext _name_ - add the specified extension _name_ and its dependencies to\n    the build.\n  * -clean - clean generated files before building.\n  * -registry _path_ - use specified API XML instead of the default\n    `xml/cl.xml`.\n  * -v - verbose, print actions before executing them.\n  * -n - dry-run, print actions instead of executing them.\n  * Unrecognized options are passed on to `make`, so must be valid Makefile\n    targets or `make` options such as `-j`.\n\nAny other options reported by `makeSpec --help` are not yet functional, and\nshould not be used.\n\nFor example, to build with all `khr` extensions, you could use\n\n[source,sh]\n----\n$ makeSpec -clean -spec khr -j html refpages\n----\n\n`makeSpec` is a wrapper which constructs options and invokes `make`\nwhen building with extensions included, which only affects building the API\n(including reference pages) and C language specifications.\n`makeSpec` determines extension dependencies from the metadata in the\nspecified registry XML path.\n\n\n[[refpage-install]]\n== Reference Page Installation\n\nMost of the reference pages are extracted from the OpenCL API and OpenCL\nC Specifications, although some are static.\nWhile anyone can generate reference page sets for themselves, Khronos\npublishes them via the `main` branch of the\nhttps://www.khronos.org/registry/OpenCL/sdk/3.0/docs/man/[OpenCL Registry].\n\nWhen the OpenCL Specification Editor is updating the published reference\npages, it is easiest to have local repository clones of this repository\n(OpenCL-Docs) as well as OpenCL-Registry. Update the pages in the local\nregistry clone via\n\n----\nmake -j 6 OUTDIR=path-to-registry-repo/sdk/3.0/docs manhtmlpages\n----\n\nThis creates the HTML output pages under `sdk/3.0/docs/man/html`, and copies\nthe KaTeX package to `sdk/3.0/docs/katex`.\nTo publish, commit those changes to the registry repository and push it to\ngithub.\n\n\n[[styles]]\n== Our stylesheets\n\nWe use a modified version of the Asciidoctor 'colony' theme. This theme is\nmaintained internally to Khronos and the resulting CSS is under\n`config/khronos.css`.\n\n\n[[equations]]\n== Imbedding Equations\n\nWhere possible, equations should be written using straight asciidoc markup\nusing the _eq_ role.\nThis covers many common equations and is faster than the alternatives.\n\nFor more complex equations, such as multi-case statements, matrices, and\ncomplex fractions, equations should be written using the latexmath: inline\nand block macros.\nThe contents of the latexmath: blocks should be LaTeX math notation.\nLaTeX math markup delimiters are now inserted by the asciidoctor toolchain.\n\nLaTeX math is passed through unmodified to all HTML output forms, which is\nsubsequently rendered with the KaTeX engine when the html is loaded.\nA local copy of the KaTeX release is kept in `katex/` and copied to the HTML\noutput directory during spec generation.\nMath is processed into SVGs via `asciidoctor-mathematical` for PDF output.\n\nThe following caveats apply:\n\n  * The special characters `\u003c` , `\u003e` , and `\u0026` can currently be used only in\n    +++[latexmath]+++ block macros, not in +++latexmath:[]+++ inline macros.\n    Instead use `\\lt`, `\\leq`, `\\gt`, and `\\geq` for `\u003c`, `\u003c=`, `\u003e`, and\n    `\u003e=` respectively.\n    `\u0026` is an alignment construct for multiline equations, and should only\n    appear in block macros anyway.\n  * AMSmath environments (e.g. pass:[\\begin{equation*}], pass:[{align*}],\n    etc.) cannot be used in KaTeX at present, and have been replaced with\n    constructs supported by KaTeX such as pass:[{aligned}].\n  * Arbitrary LaTeX constructs cannot be used.\n    KaTeX and asciidoctor-mathematical are only equation renderers, not full\n    LaTeX engines.\n    Imbedding LaTeX like \\Large or pass:[\\hbox{\\tt\\small VK\\_FOO}] may not\n    work in any of the backends, and should be avoided.\n\nSee the \"`Vulkan Documentation and Extensions`\" document in the\nhttps://www.khronos.org/registry/vulkan/specs/1.0/styleguide.html[Khronos\nVulkan Registry] for more details of supported LaTeX math constructs in our\ntoolchain.\n\n\n[[anchors]]\n== Asciidoc Anchors And Xrefs\n\nIn asciidoctor, sections can have anchors (labels) applied with the\nfollowing syntax:\n\n----\n[[spirv-il]]\n== SPIR-V Intermediate language\n----\n\nIn general the anchor should immediately precede the chapter or section\ntitle and should use the form '+++[[chapter-section-label]]+++'.\n\nCross-references to those anchors can then be generated with, for example,\n\n----\nSee the \u003c\u003cspirv-il\u003e\u003e section for discussion of the SPIR-V intermediate\nlanguage.\n----\n\nYou can also add anchors on arbitrary paragraphs, using a similar naming\nscheme.\n\n\n[[depends]]\n== Software Dependencies\n\nThis section describes the software components used by the OpenCL spec\ntoolchain.\nThe specified versions are known to work.\nLater compatible versions will probably work as well.\n\nBefore building the OpenCL specs, you must install the following tools:\n\n  * GNU make (make version: 4.0.8-1; older versions probably OK)\n  * Python 3 (python, version: 3.4.2)\n  * Ruby (ruby, version: 2.3.3)\n  ** The Ruby development package (ruby-dev) may also be required in some\n     environments.\n  * Git command-line client (git, version: 2.1.4).\n    The build can progress without a git client, but branch/commit\n    information will be omitted from the build.\n    Any version supporting the following operations should work:\n  ** `git symbolic-ref --short HEAD`\n  ** `git log -1 --format=\"%H\"`\n  * ttf Fonts.\n    These are needed the PDF build for latexmath rendering.\n    See https://github.com/asciidoctor/asciidoctor-mathematical/blob/master/README.md#dependencies[Font Dependencies for asciidoctor-mathematical].\n\nThe following Ruby Gems and platform package dependencies must also be\ninstalled.\nThis process is described in more detail for individual platforms and\nenvironment managers below.\nPlease read the remainder of this document (other than platform-specific\nparts you don't use) completely before trying to install.\n\n  * Asciidoctor (asciidoctor, version: 2.0.16)\n  * Coderay (coderay, version: 1.1.1)\n  * hexapdf (version: 0.27.0)\n  * rouge (rouge, version 3.19.0)\n  * ttfunk (ttfunk, version: 1.5.1)\n  * Asciidoctor PDF (asciidoctor-pdf, version: 1.5.0)\n  * Asciidoctor Mathematical (asciidoctor-mathematical, version 0.3.5)\n  * https://github.com/asciidoctor/asciidoctor-mathematical#dependencies[Dependencies\n    for asciidoctor-mathematical] (There are a lot of these!)\n  * KaTeX distribution (version 0.7.0 from https://github.com/Khan/KaTeX .\n    This is cached under `katex/`, and need not be\n    installed from github.\n\nOnly the `asciidoctor`, `coderay`, and `rouge` gems are needed if you don't\nintend to build PDF versions of the spec and supporting documents.\n\n[NOTE]\n.Note\n====\nWhile it's easier to install just the toolchain components for HTML builds,\npeople submitting MRs with substantial changes to the Specifications are\nresponsible for verifying that their branches build *both* `html` and `pdf`\ntargets.\n====\n\nPlatform-specific toolchain instructions follow:\n\n  * \u003c\u003cdepends-windows, Microsoft Windows\u003e\u003e\n  ** \u003c\u003cdepends-ubuntu, Ubuntu / Windows 10\u003e\u003e. The Windows 10 Ubuntu\n     subsystem is recommended over MinGW and Cygwin for Windows builds, if\n     possible, due to speed, similarity to the Linux toolchain, and the\n     required packages being more likely to be up-to-date.\n  ** \u003c\u003cdepends-mingw,MinGW\u003e\u003e (PDF builds not tested)\n  ** \u003c\u003cdepends-cygwin, Cygwin\u003e\u003e\n  * \u003c\u003cdepends-osx,Mac OS X\u003e\u003e\n  * \u003c\u003cdepends-linux,Linux (Debian, Ubuntu, etc.)\u003e\u003e\n\n\n[[depends-windows]]\n=== Windows (General)\n\nMost of the dependencies on Linux packages are light enough that it's\npossible to build the spec natively in Windows, but it means bypassing the\nmakefile and calling functions directly.\nThis might be solved in future.\nFor now, there are three options for Windows users: Ubuntu / Windows 10,\nMinGW, or Cygwin.\n\n\n[[depends-ubuntu]]\n==== Ubuntu / Windows 10\n\nWhen using the \"`Ubuntu Subsystem`\" for Windows 10, most dependencies can be\ninstalled via apt-get:\n\n----\nsudo apt-get -qq -y install build-essential python3 git cmake bison flex \\\n    libffi-dev libgmp-dev libxml2-dev libgdk-pixbuf2.0-dev libcairo2-dev \\\n    libpango1.0-dev fonts-lyx gtk-doc-tools ghostscript\n----\n\nThe default ruby packages on Ubuntu are fairly out of date.\nUbuntu only provides `ruby` and `ruby2.0` - the latter is multiple revisions\nbehind the current stable branch, and would require wrangling to get the\nmakefile working with it.\n\nLuckily, there are better options; either https://rvm.io[rvm] or\nhttps://github.com/rbenv/rbenv[rbenv] is recommended to install a more\nrecent version.\n\n[NOTE]\n.Note\n====\n  * If you are new to Ruby, you should *completely remove* (through the\n    package manager, e.g. `sudo apt-get remove *packagename*`) all existing\n    Ruby and asciidoctor infrastructure on your machine before trying to use\n    rvm or rbenv for the first time.\n    `dpkg -l | egrep 'asciidoctor|ruby|rbenv|rvm'` will give you a list of\n    candidate package names to remove.\n  ** If you already have a favorite Ruby package manager, ignore this\n     advice, and just install the required OS packages and gems.\n  * In addition, `rvm` and `rbenv` are *mutually incompatible*.\n    They both rely on inserting shims and `$PATH` modifications in your bash\n    shell.\n    If you already have one of these installed and are familiar with it,\n    it's best to stay with that one.\n    One of the editors, who is new to Ruby, found `rbenv` far more\n    comprehensible than `rvm`.\n    The other editor likes `rvm` better.\n  ** Neither `rvm` nor `rbenv` work, out of the box, when invoked from\n     non-Bash shells like tcsh.\n     This can be hacked up by setting the right environment variables and\n     PATH additions based on a bash environment.\n  * Most of the tools on Bash for Windows are quite happy with Windows line\n    endings (CR LF), but bash scripts expect Unix line endings (LF).\n    The file `.gitattributes` at the top of the vulkan tree in the 1.0\n    branch forces such scripts to be checked out with the proper line\n    endings on non-Linux platforms.\n    If you add new scripts whose names don't end in `.sh`, they should be\n    included in .gitattributes as well.\n====\n\n\n[[depends-ubuntu-rbenv]]\n===== Ubuntu/Windows 10 Using Rbenv\n\nRbenv is a lighter-weight Ruby environment manager with less functionality\nthan rvm.\nIts primary task is to manage different Ruby versions, while rvm has\nadditional functionality such as managing \"`gemsets`\" that is irrelevant to\nour needs.\n\nA complete installation script for the toolchain on Ubuntu for Windows,\ndeveloped on an essentially out-of-the-box environment, follows.\nIf you try this, don't try to execute the entire thing at once.\nDo each step separately in case of errors we didn't encounter.\n\n----\n# Install packages needed by `ruby_build` and by toolchain components.\n# See https://github.com/rbenv/ruby-build/wiki and\n# https://github.com/asciidoctor/asciidoctor-mathematical#dependencies\n\nsudo apt-get install autoconf bison build-essential libssl-dev \\\n    libyaml-dev libreadline6-dev zlib1g-dev libncurses5-dev \\\n    libffi-dev libgdbm3 libgdbm-dev cmake libgmp-dev libxml2 \\\n    libxml2-dev flex pkg-config libglib2.0-dev \\\n    libcairo-dev libpango1.0-dev libgdk-pixbuf2.0-dev \\\n    libpangocairo-1.0\n\n# Install rbenv from https://github.com/rbenv/rbenv\ngit clone https://github.com/rbenv/rbenv.git ~/.rbenv\n\n# Set path to shim layers in .bashrc\necho 'export PATH=\"$HOME/.rbenv/bin:$PATH\"' \u003e\u003e .bashrc\n\n~/.rbenv/bin/rbenv init\n\n# Set .rbenv environment variables in .bashrc\necho 'eval \"$(rbenv init -)\"' \u003e\u003e .bashrc\n\n# Restart your shell (e.g. open a new terminal window). Note that\n# you do not need to use the `-l` option, since the modifications\n# were made to .bashrc rather than .bash_profile. If successful,\n# `type rbenv` should print 'rbenv is a function' followed by code.\n\n# Install `ruby_build` plugin from https://github.com/rbenv/ruby-build\n\ngit clone https://github.com/rbenv/ruby-build.git\n~/.rbenv/plugins/ruby-build\n\n# Install Ruby 2.3.3\n# This takes in excess of 20 min. to build!\n# https://github.com/rbenv/ruby-build/issues/1054#issuecomment-276934761\n# suggests:\n# \"You can speed up Ruby installs by avoiding generating ri/RDoc\n# documentation for them:\n# RUBY_CONFIGURE_OPTS=--disable-install-doc rbenv install 2.3.3\n# We have not tried this.\n\nrbenv install 2.3.3\n\n# Configure rbenv globally to always use Ruby 2.3.3.\necho \"2.3.3\" \u003e ~/.rbenv/version\n\n# Finally, install toolchain components.\n# asciidoctor-mathematical also takes in excess of 20 min. to build!\n# The same RUBY_CONFIGURE_OPTS advice above may apply here as well.\n\ngem install asciidoctor -v 2.0.16\ngem install coderay -v 1.1.1\ngem install hexapdf -v 0.27.0\ngem install rouge -v 3.19.0\ngem install ttfunk -v 1.5.1\ngem install asciidoctor-pdf -v 1.5.0\ngem install asciidoctor-mathematical -v 0.3.5\n----\n\n\n[[depends-ubuntu-rvm]]\n===== Ubuntu/Windows 10 Using RVM\n\nHere are (sparser) instructions for using rvm to setup version 2.3.x:\n\n----\ngpg --keyserver hkp://keys.gnupg.net --recv-keys 409B6B1796C275462A1703113804BB82D39DC0E3\n\\curl -sSL https://get.rvm.io | bash -s stable --ruby\nsource ~/.rvm/scripts/rvm\nrvm install ruby-2.3\nrvm use ruby-2.3\n----\n\nNOTE: Windows 10 Bash will need to be launched with the \"-l\" option\nappended, so that it runs a login shell; otherwise RVM won't function\ncorrectly on future launches.\n\n\n[[depends-ubuntu-sys]]\n===== Ubuntu 16.04 using system Ruby\n\nThe Ubuntu 16.04.1 default Ruby install (version 2.3.1) seems to be\nup-to-date enough to run all the required gems, but also needs the\n`ruby-dev` package installed through the package manager.\n\nIn addition, the library\n`/var/lib/gems/2.3.0/gems/mathematical-1.6.7/ext/mathematical/lib/liblasem.so`\nhas to be copied or linked into a directory where the loader can find it.\nThis requirement appears to be due to a problem with the\nasciidoctor-mathematical build process.\n\n\n[[depends-mingw]]\n==== MinGW\n\nMinGW can be obtained here: http://www.mingw.org/\n\nOnce the installer has run its initial setup, following the\nhttp://www.mingw.org/wiki/Getting_Started[instructions on the website], you\nshould install the `mingw-developer-tools`, `mingw-base` and `msys-base`\npackages.\nThe `msys-base` package allows you to use a bash terminal from windows with\nwhatever is normally in your path on Windows, as well as the unix tools\ninstalled by MinGW.\n\nIn the native Windows environment, you should also install the following\nnative packages:\n\n  * Python 3.x (https://www.python.org/downloads/)\n  * Ruby 2.x (https://rubyinstaller.org/)\n  * Git command-line client (https://git-scm.com/download)\n\nOnce this is setup, and the necessary \u003c\u003cdepends-gems,Ruby Gems\u003e\u003e are\ninstalled, launch the `msys` bash shell, and navigate to the spec Makefile.\nFrom there, you'll need to set `PYTHON=` to the location of your python\nexecutable for version 3.x before your make command - but otherwise\neverything other than pdf builds should just work.\n\nNOTE: Building the PDF spec via this path has not yet been tested but *may*\nbe possible - liblasem is the main issue and it looks like there is now a\nmingw32 build of it available.\n\n\n[[depends-cygwin]]\n==== Cygwin\n\nWhen installing Cygwin, you should install the following packages via\n`setup`:\n\n----\n// \"curl\" is only used to download fonts, can be done in another way\nautoconf\nbison\ncmake\ncurl\nflex\ngcc-core\ngcc-g++\nghostscript\ngit\nlibbz2-devel\nlibcairo-devel\nlibcairo2\nlibffi-devel\nlibgdk_pixbuf2.0-devel\nlibgmp-devel\nlibiconv\nlibiconv-devel\nliblasem0.4-devel\nlibpango1.0-devel\nlibpango1.0_0\nlibxml2\nlibxml2-devel\nmake\npython3\nruby\nruby-devel\n----\n\nNOTE: Native versions of some of these packages are usable, but care should\nbe taken for incompatibilities with various parts of cygwin - e.g. paths.\nRuby in particular is unable to resolve Windows paths correctly via the\nnative version.\nPython and Git for Windows can be used, though for Python you'll need to set\nthe path to it via the PYTHON environment variable, before calling make.\n\nWhen it comes to installing the mathematical ruby gem, there are two things\nthat will require tweaking to get it working.\nFirstly, instead of:\n\n----\ngem install asciidoctor-mathematical\n----\n\nYou should use\n\n----\nMATHEMATICAL_USE_SYSTEM_LASEM=1 gem install asciidoctor-mathematical\n----\n\nThe latter causes it to use the lasem package already installed, rather than\ntrying to build a fresh one.\n\nThe mathematical gem also looks for \"liblasem\" rather than \"liblasem0.4\" as\ninstalled by the lasem0.4-devel package, so it is necessary to add a symlink\nto your /lib directory using:\n\n----\nln -s /lib/liblasem-0.4.dll.a /lib/liblasem.dll.a\n----\n\n\u003c\u003cRuby Gems\u003e\u003e are not installed to a location that is in your path normally.\nGems are installed to `~/bin/` - you should add this to your path before\ncalling make:\n\n    export PATH=~/bin:$PATH\n\nFinally, you'll need to manually install fonts for lasem via the following\ncommands:\n\n----\nmkdir /usr/share/fonts/truetype cd /usr/share/fonts/truetype\ncurl -LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/cmex10.ttf \\\n     -LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/cmmi10.ttf \\\n     -LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/cmr10.ttf \\\n     -LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/cmsy10.ttf \\\n     -LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/esint10.ttf \\\n     -LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/eufm10.ttf \\\n     -LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/msam10.ttf \\\n     -LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/msbm10.ttf\n----\n\n\n[[depends-osx]]\n=== Mac OS X\n\nMac OS X should work in the same way as for ubuntu by using the Homebrew\npackage manager, with the exception that you can simply install the ruby\npackage via `brew` rather than using a ruby-specific version manager.\n\nYou'll likely also need to install additional fonts for the PDF build via\nmathematical, which you can do with:\n\n----\ncd ~/Library/Fonts\ncurl -LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/cmex10.ttf \\\n     -LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/cmmi10.ttf \\\n     -LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/cmr10.ttf \\\n     -LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/cmsy10.ttf \\\n     -LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/esint10.ttf \\\n     -LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/eufm10.ttf \\\n     -LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/msam10.ttf \\\n     -LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/msbm10.ttf\n----\n\nThen install the required \u003c\u003cdepends-gems,Ruby Gems\u003e\u003e.\n\n\n[[depends-linux]]\n=== Linux (Debian, Ubuntu, etc.)\n\nThe instructions for the \u003c\u003cdepends-ubuntu,Ubuntu / Windows 10\u003e\u003e installation\nare generally applicable to native Linux environments using Debian packages,\nsuch as Debian and Ubuntu, although the exact list of packages to install\nmay differ.\n\nOther distributions using different package managers, such as RPM (Fedora)\nand Yum (SuSE) will have different requirements.\n\nUsing `rbenv` or `rvm` is neccessary, since the system Ruby packages are\noften well out of date.\n\nOnce the environment manager, Ruby, and `ruby_build` have been installed,\ninstall the required \u003c\u003cdepends-gems,Ruby Gems\u003e\u003e.\n\n\n[[depends-gems]]\n=== Ruby Gems\n\nThe following ruby gems can be installed directly via the `gem install`\ncommand, once the platform is set up:\n\n----\ngem install asciidoctor -v 2.0.16\ngem install coderay -v 1.1.1\ngem install hexapdf -v 0.27.0\ngen install rouge -v 3.19.0\ngem install ttfunk -v 1.5.1\n\n# Required only for pdf builds\ngem install asciidoctor-pdf -v 1.5.0\ngem install asciidoctor-mathematical -v 0.3.5\n----\n\n\n[[license]]\n== License\n\nThe specification Asciidoctor source files are licensed under the Creative\nCommons Attribution 4.0 International License; see\nhttps://creativecommons.org/licenses/by/4.0/\n\nAdditional source files used to build the specification are under a mixture of\nApache 2.0 and MIT licenses.  See the LICENSE file for details.\n\nThe official Specification HTML and PDF *output* documents are posted in the\nhttps://www.khronos.org/registry/OpenCL[OpenCL Registry]. These\nSpecifications are placed under the proprietary Khronos specification\ncopyright and license.\n\nOpenCL and the OpenCL logo are trademarks of Apple Inc. used by permission\nby Khronos.\n\n\n[[history]]\n== Revision History\n\n  * 2024-04-07 - Add `makeSpec` instructions.\n  * 2023-11-05 - Add hexapdf, remove ghostscript\n  * 2020-03-13 - Updated package versions to match Travis build.\n  * 2019-06-20 - Add directions for publishing OpenCL 2.2 reference pages,\n    generated from the spec sources in this repository, in the\n    OpenCL-Registry repository.\n  * 2018-02-15 - Retarget document from Vulkan repository for OpenCL\n    asciidoctor spec builds.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkhronosgroup%2Fopencl-docs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkhronosgroup%2Fopencl-docs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkhronosgroup%2Fopencl-docs/lists"}