Repository files navigation

This repository contains the source markup used to generate theformal SYCL specifications found onhttps://www.khronos.org/sycl/.

If you are proposing a merge or pull request to the specification, thisREADME describes how the specification HTML and PDF targets can be built.Proposed changes must successfully build these targets before beingconsidered for inclusion by the SYCL Working Group.

When using our github repository, pushing to a branch will trigger theGithub Actions CI script under../.github/workflows/CI.yml to build HTMLand PDF versions of the spec. To see the outputs, click on theActions tabin the top navigation bar, or go tohttps://github.com/KhronosGroup/SYCL-Docs/actions . Your commit should showup on the list of commits below. Click through to the Actions summary forthat commit.

On success, a green checkmark will appear by the commit name on this page.Output artifacts can be downloaded as a zipfile from theArtifacts sectionnear the bottom of the page.

On failure, a redx will appear by the commit name. Click through to thebuild job and it should auto-scroll to the CI log showing where the buildfailed. Fix it and push a new commit to try again.

Note that to read the HTML specification correctly with all themathematical symbols, you need also to have thekatex directoryalong thehtml one. This might not be the case if your downloadingframework lazily unzips just what you read.

If you are proposing a pull request from your own clone of our repository,you may need to enable Github Actions for your clone.

Building the specification on your own machine requires a large set oftools. Rather than installing these tools yourself, if you can run Docker ona Linux compatible host (probably including Windows WSL2 with a Ubuntu orDebian OS, and possibly including MacOS X), you can use the samepre-configured Docker image used by the CI builds.

If you are on Debian/Ubuntu Linux, install Docker with:

sudo apt updatesudo apt install docker.io

The Docker image used to build the specifications can then be downloaded orupdated to the latest version via

docker pull khronosgroup/docker-images:asciidoctor-spec

The Dockerfile specifying this image can be found athttps://github.com/KhronosGroup/DockerContainers if you need to build amodified or layered image. However, if something is missing or out of datein the image, please file an issue on theDockerContainers repositorybefore trying to build your own image. We will try to keep the image updatedas needed.

To build the specification using the image, use theMakefile inside theadoc directory:

cd adocmake clean docker-html docker-pdf

Outputs will be located in $(OUTDIR) (by default,out/ in theadocdirectory).

There are some variables defined in theMakefile you can set to change thebehavior, such as to verbosely display the build process:

make QUIET= clean docker-html docker-pdf

If you need to invoke Docker without usingmake on the host, look at theactions in thedocker-% target inadoc/Makefile and replicate them onyour system.

If you don't want to, or can't use Docker (or a compatible replacement - itis possible that the Red Hatpodman tool can run our Docker container, forexample, though we do not support this), then you will need to install allthe same tools in your own environment.

We cannot provide instructions to do this on every possible buildenvironment. However, if you are using Debian/Ubuntu Linux, either native orvia WSL2, you should be able to install the required tools by looking at theDockerfile at

https://github.com/KhronosGroup/DockerContainers/blob/master/asciidoctor-spec.Dockerfile

Note that the Khronos Docker image layers on the official Ruby 3.1 Dockerimage, so you must install Ruby first.

If you have installed an older version of the tools and the Khronos image isupdated, there may be minor changes in the Makefile and markup required bythe new versions. For example, updating from asciidoctor-pdf 1.6.1 to 2.2.0required changing thepdf-stylesdir attribute in the asciidoctor build topdf-themesdir. Eventually, these changes may make using the older toolsimpractical. If this happens, update your tools to match the latest Dockerimage, and rebase your working branch on currentmain branch.

Finally, if you are a Khronos member working in our internal Gitlab server,Gitlab CI builds the image just like Github CI. Go to the...sycl/Specification repository page on the gitlab server, click throughto CI/CD-Jobs (the rocket-ship icon on the left menu bar or...sycl/Specification/-/jobs). If your job succeeded, click on theDownload icon for the latest CI job in the appropriate branch to downloadthe zip file of build artifacts, or click onPassed to see build details.

The Gitlab CI script is functionally equivalent to the Github CI script, butis located under.gitlab-ci.yml, using a different YAML scheme.