Source of Khronos Group SYCL 2020 revision 2 specification

.gitattributes

@@ -0,0 +1 @@
+out/pdf/sycl-1.2.1.pdf filter=lfs diff=lfs merge=lfs -text

CODE_OF_CONDUCT.md

@@ -0,0 +1 @@
+A reminder that this issue tracker is managed by the Khronos Group. Interactions here should follow the Khronos Code of Conduct (https://www.khronos.org/developers/code-of-conduct), which prohibits aggressive or derogatory language. Please keep the discussion friendly and civil.

COPYRIGHT.txt

@@ -0,0 +1,35 @@
+Copyright (c) 2011-2021 The Khronos Group, Inc.
+
+This specification is protected by copyright laws and contains material proprietary
+to Khronos. Except as described by these terms, it or any components
+may not be reproduced, republished, distributed, transmitted, displayed, broadcast
+or otherwise exploited in any manner without the express prior written permission
+of Khronos.
+
+Khronos grants a conditional copyright license to use and reproduce the
+unmodified Specification for any purpose, without fee or royalty, EXCEPT no licenses
+to any patent, trademark or other intellectual property rights are granted under these
+terms. Parties desiring to implement the specification and make use of Khronos trademarks
+in relation to that implementation, and receive reciprocal patent license protection under
+the Khronos IP Policy must become Adopters and confirm the implementation as conformant under
+the process defined by Khronos for this specification; see https://www.khronos.org/adopters.
+
+Khronos makes no, and expressly disclaims any, representations or warranties,
+express or implied, regarding this specification, including, without limitation:
+merchantability, fitness for a particular purpose, non-infringement of any
+intellectual property, correctness, accuracy, completeness, timeliness, and
+reliability. Under no circumstances will Khronos, or any of its Promoters,
+Contributors or Members, or their respective partners, officers, directors,
+employees, agents or representatives be liable for any damages, whether direct,
+indirect, special or consequential damages for lost revenues, lost profits, or
+otherwise, arising from or in connection with these materials.
+
+Vulkan is a registered trademark and Khronos, OpenXR, SPIR, SPIR-V, SYCL, WebGL,
+WebCL, OpenVX, OpenVG, EGL, COLLADA, glTF, NNEF, OpenKODE, OpenKCAM, StreamInput,
+OpenWF, OpenSL ES, OpenMAX, OpenMAX AL, OpenMAX IL, OpenMAX DL, OpenML and DevU are
+trademarks of The Khronos Group, Inc. ASTC is a trademark of ARM Holdings PLC,
+OpenCL is a trademark of Apple Inc. and OpenGL and OpenML are registered trademarks
+and the OpenGL ES and OpenGL SC logos are trademarks of Hewlett Packard Enterprise
+all used under license by Khronos. All other product names, trademarks,
+and/or company names are used solely for identification and belong to their
+respective owners.

LICENSE.txt

@@ -0,0 +1,29 @@
+Copyright (c) 2011-2021 The Khronos Group, Inc.
+
+The files in, and generated output documents from this SYCL-Docs project are
+under a mix of copyright and license statements. Refer to the individual files
+for specific information. As a general guideline:
+
+- the AsciiDoctor sources for the SYCL Specifications and other documention
+  such are the SYCL code samples
+  are under the Creative Commons Attribution 4.0 International (CC BY 4.0)
+  license.  Details of the license are at:
+  https://creativecommons.org/licenses/by/4.0/
+
+- the source files for building the specification, such as Makefiles
+  and some scripts, the SYCL headers and the SYCL code samples are
+  under the Apache 2.0 license.  Details of the license are at:
+  https://www.apache.org/licenses/LICENSE-2.0.html
+
+Unless required by applicable law or agreed to in writing, material distributed
+under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+CONDITIONS OF ANY KIND, either express or implied. If all or a portion of this
+material is re-used, notice substantially similar to the following must be included:
+
+  This SYCL specification includes material developed at The Khronos Group
+  (http://www.khronos.org/). Khronos supplied such material on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, under
+  the terms of the Creative Commons Attribution 4.0 International (CC BY 4.0)
+  License (the "License"), available at https://creativecommons.org/licenses/by/4.0/.
+  All use of such material is governed by the term of the License. Khronos bears
+  no responsibility whatsoever for additions or modifications to its material.

README.md

@@ -0,0 +1,161 @@
+![SYCL Logo](adoc/logos/SYCL_RGB_June16-inkscape-1500.png)
+
+[//]: # "to update to newer CI when going public ![Build Status](https://api.travis-ci.com/KhronosGroup/SYCL-Docs.svg?branch=master)""
+[//]: # "to update to newer CI when going public [![SPEC master](https://img.shields.io/badge/SPEC-master-red.svg?logo=adobe-acrobat-reader)](https://khronosgroup.github.io/SYCL-Docs/sycl/sycl.pdf)"
+[![SPEC master](https://img.shields.io/badge/SPEC-master-red.svg?logo=adobe-acrobat-reader)](https://gitlab.khronos.org/sycl/Specification/-/jobs)
+[![SPEC 2020-1](https://img.shields.io/badge/SPEC-2020--1-orange.svg?logo=adobe-acrobat-reader)](https://www.khronos.org/registry/SYCL/specs/sycl-2020-provisional.pdf)
+[![Join the Slack group](https://img.shields.io/badge/chat-on%20slack-blue.svg?logo=slack)](https://khr.io/slack)
+
+# SYCL Open Source Specification
+
+This repository contains the source and tool chain used to generate
+the formal SYCL specifications found on [https://www.khronos.org/sycl/](https://www.khronos.org/sycl/).
+
+## Reading the latest version of the SYCL specification
+
+The GitLab CI pipeline builds the specification. This is accessible
+from this page, under the green check symbol, on the top right of the
+page or more generally from the rocket symbol on the left side.
+
+Then on the pipeline page, select the *Jobs* tab and click on the
+*download* icon on the bottom right.
+
+
+## Building the SYCL specification
+
+### Using GitLab CI
+
+The simplest way to build the specification is not to actually build
+it, but to rely on the Khronos continuous integration process which
+builds automatically a branch when it is changed on
+https://gitlab.khronos.org/sycl/Specification
+
+Look at CI/CD-Jobs (the rocket-ship icon on the left menu bar or
+https://gitlab.khronos.org/sycl/Specification/-/jobs), click on the
+`Download` icon for the latest CI job in the branch of interest or
+click on `Passed` to dive into more details. Once unzipping the
+compilation artifacts, look inside `adoc/out` directory to find the
+HTML and PDF version.
+
+Note that to read the HTML specification correctly with all the
+mathematical symbols, you need also to have the `katex` directory
+along the `html` one. This might not be the case if your downloading
+framework lazily unzips just what you read.
+
+You can use this CI infrastructure while developing: you can git-push
+or git-force-push your branch on the server and go to CI/CD-Jobs to
+look at the compiled version.
+
+All this works because of the existing `.gitlab-ci.yml` recipe.
+
+### Using pre-configured AsciiDoctor-capable Docker image
+
+Compiling the specification requires some specific AsciiDoctor related
+packages.
+
+To simplify the setup, Khronos provides a pre-configured Docker Linux
+Ubuntu image you can use on a Docker executor to compile the
+specification on various OS able to run Docker.
+
+Assuming you are on Debian/Ubuntu Linux, the first time you need to
+install Docker with for example:
+```bash
+sudo apt update
+sudo apt install docker.io
+```
+
+The base image used to build the specifications can be downloaded or
+updated to the latest version via
+```bash
+docker pull khronosgroup/docker-images:vulkan-docs-base
+```
+Or you can manually generate the image using the script provided in
+`https://github.com/KhronosGroup/DockerContainers`.
+
+
+To compile the specification you can rely on the `Makefile` inside the
+`adoc` directory, for example with:
+```bash
+cd adoc
+make clean docker-html docker-pdf
+```
+
+There are a few variables defined in the `Makefile` you can set to
+change the behavior, such as to display verbosely the compilation
+process:
+```bash
+make QUIET= clean docker-html docker-pdf
+```
+
+If you need to launch explicitly Docker without using `make` on the
+host, look at the `adoc/Makefile` and imitate on your system how
+Docker is launched.
+
+Since the Docker image is old, there is a new path using a script to
+upgrade the files inside the Docker image to be used as:
+```bash
+make DOCKER_COMMAND="make QUIET= --directory=/sycl/adoc clean html pdf" dock
+```
+
+### Using native computer
+
+If you are using a Debian/Ubuntu Linux distribution, you can look at
+how the previous process works and how the Docker image is done at
+https://github.com/KhronosGroup/DockerContainers and specifically
+https://github.com/KhronosGroup/DockerContainers/blob/master/Dockerfile.vulkan-docs-base
+which gives an idea of the packages to install and
+https://github.com/KhronosGroup/DockerContainers/blob/master/entrypoint.vulkan.sh
+
+*TODO*: find the minimal recipe.
+```bash
+sudo apt update
+sudo apt install bison \
+  build-essential \
+  cmake \
+  flex \
+  fonts-lyx \
+  g++ \
+  ghostscript \
+  git \
+  libcairo2-dev \
+  libffi-dev \
+  libgdk-pixbuf2.0-dev \
+  libpango1.0-dev \
+  libreadline-dev \
+  libxml2-dev \
+  nodejs \
+  node-escape-string-regexp \
+  node-he \
+  node-lunr \
+  poppler-utils \
+  python3 \
+  ruby-dev
+
+sudo apt clean
+
+sudo gem install asciidoctor \
+  asciidoctor-diagram \
+  asciidoctor-mathematical \
+  asciidoctor-pdf \
+  coderay \
+  json-schema \
+  i18n \
+  pygments.rb \
+  rouge \
+  text-hyphen
+```
+
+Then use for example:
+```bash
+make QUIET= clean html pdf
+```
+
+There is also some discussion back-ground in
+https://gitlab.khronos.org/sycl/Specification/-/merge_requests/484#note_270338
+
+
+### Windows recipe
+
+*TODO*: Investigate the Docker route
+https://docs.docker.com/docker-for-windows/install/ , WSL2, CygWin,
+VCPKG...

adoc/.gitignore

@@ -0,0 +1 @@
+.asciidoctor