{"id":27940495,"url":"https://github.com/khronosgroup/sycl-docs","last_synced_at":"2025-05-07T10:17:12.667Z","repository":{"id":35519086,"uuid":"186454029","full_name":"KhronosGroup/SYCL-Docs","owner":"KhronosGroup","description":"SYCL Open Source Specification","archived":false,"fork":false,"pushed_at":"2025-05-06T15:40:25.000Z","size":7343,"stargazers_count":134,"open_issues_count":169,"forks_count":70,"subscribers_count":28,"default_branch":"main","last_synced_at":"2025-05-06T16:43:51.306Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","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.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","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":"2019-05-13T16:07:19.000Z","updated_at":"2025-04-24T15:22:46.000Z","dependencies_parsed_at":"2023-10-13T05:58:59.025Z","dependency_job_id":"e685ff38-173d-41f2-8194-7f63896164d1","html_url":"https://github.com/KhronosGroup/SYCL-Docs","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KhronosGroup%2FSYCL-Docs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KhronosGroup%2FSYCL-Docs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KhronosGroup%2FSYCL-Docs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KhronosGroup%2FSYCL-Docs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/KhronosGroup","download_url":"https://codeload.github.com/KhronosGroup/SYCL-Docs/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252856565,"owners_count":21814858,"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:10.225Z","updated_at":"2025-05-07T10:17:12.341Z","avatar_url":"https://github.com/KhronosGroup.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"![SYCL Logo](adoc/logos/SYCL_RGB_June16-inkscape-1500.png)\n\n\u003c!-- to update to newer CI when going public ![Build Status](https://api.travis-ci.com/KhronosGroup/SYCL-Docs.svg?branch=master) --\u003e\n\u003c!-- 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) --\u003e\n[![SPEC 2020-10](https://img.shields.io/badge/SPEC-2020--10-orange.svg?logo=adobe-acrobat-reader)](https://www.khronos.org/registry/SYCL/specs/sycl-2020/pdf/sycl-2020.pdf)\n[![SPEC 2020-10](https://img.shields.io/badge/SPEC-2020--10-orange.svg?logo=HTML5)](https://www.khronos.org/registry/SYCL/specs/sycl-2020/html/sycl-2020.html)\n[![SPEC latest](https://img.shields.io/badge/SPEC-latest-red.svg?logo=adobe-acrobat-reader)](https://github.com/KhronosGroup/SYCL-Docs/actions?query=branch%3ASYCL-2020%2Fmaster+is%3Asuccess)\n[![Join the Slack group](https://img.shields.io/badge/chat-on%20slack-blue.svg?logo=slack)](https://khr.io/slack)\n\n# SYCL Open Source Specification\n\nThis repository contains the source markup used to generate the\nformal SYCL specifications found on\n[https://www.khronos.org/sycl/](https://www.khronos.org/sycl/).\n\nIf you are proposing a merge or pull request to the specification, this\nREADME describes how the specification HTML and PDF targets can be built.\nProposed changes must successfully build these targets before being\nconsidered for inclusion by the SYCL Working Group.\n\n\n## Building the SYCL specification\n\n\n### Building using Github CI\n\nWhen using our github repository, pushing to a branch will trigger the\nGithub Actions CI script under `../.github/workflows/CI.yml` to build HTML\nand PDF versions of the spec. To see the outputs, click on the `Actions` tab\nin the top navigation bar, or go to\nhttps://github.com/KhronosGroup/SYCL-Docs/actions . Your commit should show\nup on the list of commits below. Click through to the Actions summary for\nthat commit.\n\nOn success, a green checkmark will appear by the commit name on this page.\nOutput artifacts can be downloaded as a zipfile from the `Artifacts` section\nnear the bottom of the page.\n\nOn failure, a red `x` will appear by the commit name. Click through to the\n`build` job and it should auto-scroll to the CI log showing where the build\nfailed. Fix it and push a new commit to try again.\n\nNote that to read the HTML specification correctly with all the\nmathematical symbols, you need also to have the `katex` directory\nalong the `html` one. This might not be the case if your downloading\nframework lazily unzips just what you read.\n\nIf you are proposing a pull request from your own clone of our repository,\nyou may need to enable Github Actions for your clone.\n\n\n### Building Using The Khronos Docker Image\n\nBuilding the specification on your own machine requires a large set of\ntools. Rather than installing these tools yourself, if you can run Docker on\na Linux compatible host (probably including Windows WSL2 with a Ubuntu or\nDebian OS, and possibly including MacOS X), you can use the same\npre-configured Docker image used by the CI builds.\n\nIf you are on Debian/Ubuntu Linux, install Docker with:\n\n```bash\nsudo apt update\nsudo apt install docker.io\n```\n\nThe Docker image used to build the specifications can then be downloaded or\nupdated to the latest version via\n\n```bash\ndocker pull khronosgroup/docker-images:asciidoctor-spec\n```\n\nThe Dockerfile specifying this image can be found at\nhttps://github.com/KhronosGroup/DockerContainers if you need to build a\nmodified or layered image. However, if something is missing or out of date\nin the image, please file an issue on the `DockerContainers` repository\nbefore trying to build your own image. We will try to keep the image updated\nas needed.\n\nTo build the specification using the image, use the `Makefile` inside the\n`adoc` directory:\n\n```bash\ncd adoc\nmake clean docker-html docker-pdf\n```\n\nOutputs will be located in $(OUTDIR) (by default, `out/` in the `adoc`\ndirectory).\n\nThere are some variables defined in the `Makefile` you can set to change the\nbehavior, such as to verbosely display the build process:\n\n```bash\nmake QUIET= clean docker-html docker-pdf\n```\n\nIf you need to invoke Docker without using `make` on the host, look at the\nactions in the `docker-%` target in `adoc/Makefile` and replicate them on\nyour system.\n\n\n### Building On Your Native Machine\n\nIf you don't want to, or can't use Docker (or a compatible replacement - it\nis possible that the Red Hat `podman` tool can run our Docker container, for\nexample, though we do not support this), then you will need to install all\nthe same tools in your own environment.\n\nWe cannot provide instructions to do this on every possible build\nenvironment. However, if you are using Debian/Ubuntu Linux, either native or\nvia WSL2, you should be able to install the required tools by looking at the\nDockerfile at\n\nhttps://github.com/KhronosGroup/DockerContainers/blob/master/asciidoctor-spec.Dockerfile\n\nNote that the Khronos Docker image layers on the official Ruby 3.1 Docker\nimage, so you must install Ruby first.\n\nIf you have installed an older version of the tools and the Khronos image is\nupdated, there may be minor changes in the Makefile and markup required by\nthe new versions. For example, updating from asciidoctor-pdf 1.6.1 to 2.2.0\nrequired changing the `pdf-stylesdir` attribute in the asciidoctor build to\n`pdf-themesdir`. Eventually, these changes may make using the older tools\nimpractical. If this happens, update your tools to match the latest Docker\nimage, and rebase your working branch on current `main` branch.\n\n\n### Building Using GitLab CI\n\nFinally, if you are a Khronos member working in our internal Gitlab server,\nGitlab CI builds the image just like Github CI. Go to the\n`...sycl/Specification` repository page on the gitlab server, click through\nto CI/CD-Jobs (the rocket-ship icon on the left menu bar or\n`...sycl/Specification/-/jobs`). If your job succeeded, click on the\n`Download` icon for the latest CI job in the appropriate branch to download\nthe zip file of build artifacts, or click on `Passed` to see build details.\n\nThe Gitlab CI script is functionally equivalent to the Github CI script, but\nis located under `.gitlab-ci.yml`, using a different YAML scheme.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkhronosgroup%2Fsycl-docs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkhronosgroup%2Fsycl-docs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkhronosgroup%2Fsycl-docs/lists"}