1# OpenCL Conformance Test Suite (CTS) 2 3This it the OpenCL CTS for all versions of the Khronos 4[OpenCL](https://www.khronos.org/opencl/) standard. 5 6## Building the CTS 7 8The CTS supports Linux, Windows, macOS, and Android platforms. In particular, 9GitHub Actions CI builds against Ubuntu 20.04, Windows-latest, and 10macos-latest. 11 12Compiling the CTS requires the following CMake configuration options to be set: 13 14* `CL_INCLUDE_DIR` Points to the unified 15 [OpenCL-Headers](https://github.com/KhronosGroup/OpenCL-Headers). 16* `CL_LIB_DIR` Directory containing the OpenCL library to build against. 17* `OPENCL_LIBRARIES` Name of the OpenCL library to link. 18 19It is advised that the [OpenCL ICD-Loader](https://github.com/KhronosGroup/OpenCL-ICD-Loader) 20is used as the OpenCL library to build against. Where `CL_LIB_DIR` points to a 21build of the ICD loader and `OPENCL_LIBRARIES` is "OpenCL". 22 23### Example Build 24 25Steps on a Linux platform to clone dependencies from GitHub sources, configure 26a build, and compile. 27 28```sh 29git clone https://github.com/KhronosGroup/OpenCL-CTS.git 30git clone https://github.com/KhronosGroup/OpenCL-Headers.git 31git clone https://github.com/KhronosGroup/OpenCL-ICD-Loader.git 32 33mkdir OpenCL-ICD-Loader/build 34cmake -S OpenCL-ICD-Loader -B OpenCL-ICD-Loader/build \ 35 -DOPENCL_ICD_LOADER_HEADERS_DIR=$PWD/OpenCL-Headers 36cmake --build ./OpenCL-ICD-Loader/build --config Release 37 38mkdir OpenCL-CTS/build 39cmake -S OpenCL-CTS -B OpenCL-CTS/build \ 40 -DCL_INCLUDE_DIR=$PWD/OpenCL-Headers \ 41 -DCL_LIB_DIR=$PWD/OpenCL-ICD-Loader/build \ 42 -DOPENCL_LIBRARIES=OpenCL 43cmake --build OpenCL-CTS/build --config Release 44``` 45 46## Running the CTS 47 48A build of the CTS contains multiple executables representing the directories in 49the `test_conformance` folder. Each of these executables contains sub-tests, and 50possibly smaller granularities of testing within the sub-tests. 51 52See the `--help` output on each executable for the list of sub-tests available, 53as well as other options for configuring execution. 54 55If the OpenCL library built against is the ICD Loader, and the vendor library to 56be tested is not registered in the 57[default ICD Loader location](https://github.com/KhronosGroup/OpenCL-ICD-Loader#registering-icds) 58then the [OCL_ICD_FILENAMES](https://github.com/KhronosGroup/OpenCL-ICD-Loader#table-of-debug-environment-variables) 59environment variable will need to be set for the ICD Loader to detect the OpenCL 60library to use at runtime. For example, to run the basic tests on a Linux 61platform: 62 63```sh 64OCL_ICD_FILENAMES=/path/to/vendor_lib.so ./test_basic 65``` 66 67### Offline Compilation 68 69Testing OpenCL drivers which do not have a runtime compiler can be done by using 70additional command line arguments provided by the test harness for tests which 71require compilation, these are: 72 73* `--compilation-mode` Selects if OpenCL-C source code should be compiled using 74 an external tool before being passed on to the OpenCL driver in that form for 75 testing. Online is the default mode, but also accepts the values `spir-v`, and 76 `binary`. 77 78* `--compilation-cache-mode` Controls how the compiled OpenCL-C source code 79 should be cached on disk. 80 81* `--compilation-cache-path` Accepts a path to a directory where the compiled 82 binary cache should be stored on disk. 83 84* `--compilation-program` Accepts a path to an executable (default: 85 cl_offline_compiler) invoked by the test harness to perform offline 86 compilation of OpenCL-C source code. This executable must match the 87 [interface description](test_common/harness/cl_offline_compiler-interface.txt). 88 89## Generating a Conformance Report 90 91The Khronos [Conformance Process Document](https://members.khronos.org/document/dl/911) 92details the steps required for a conformance submissions. 93In this repository [opencl_conformance_tests_full.csv](test_conformance/submission_details_template.txt) 94defines the full list of tests which must be run for conformance. The output log 95of which must be included alongside a filled in 96[submission details template](test_conformance/submission_details_template.txt). 97 98Utility script [run_conformance.py](test_conformance/run_conformance.py) can be 99used to help generating the submission log, although it is not required. 100 101Git [tags](https://github.com/KhronosGroup/OpenCL-CTS/tags) are used to define 102the version of the repository conformance submissions are made against. 103 104## Contributing 105 106Contributions are welcome to the project from Khronos members and non-members 107alike via GitHub Pull Requests (PR). Alternatively, if you've found a bug or have 108a questions please file an issue in the GitHub project. First time contributors 109will be required to sign the Khronos Contributor License Agreement (CLA) before 110their PR can be merged. 111 112PRs to the repository are required to be `clang-format` clean to pass CI. 113Developers can either use the `git-clang-format` tool locally to verify this 114before contributing, or update their PR based on the diff provided by a failing 115CI job. 116