1# OpenCL<sup>TM</sup> API C++ bindings 2 3Doxgen documentation for the bindings is available here: 4 5 http://khronosgroup.github.io/OpenCL-CLHPP/ 6 7Components: 8 9 * `include/CL/opencl.hpp`: 10 The latest, maintained, version of the C++ bindings. It should work with all 11 versions of OpenCL (including 1.x). This is what most users will want. 12 13 * `include/CL/cl2.hpp`: 14 Includes `opencl.hpp` and emits a warning, for backwards compability. 15 16 * `docs`: 17 Doxygen file used to generate HTML documentation for `opencl.hpp`. 18 19 * `examples`: 20 A simple example application using the very basic features of the bindings. 21 22 * `tests`: 23 A (very small, incomplete) set of regression tests. Building the tests 24 requires Python, Ruby, and CMock. For the last one we use 25 [CMock top-of-tree from Github](https://github.com/ThrowTheSwitch/CMock), 26 as the latest (at the time this was written) released CMock version, 27 v2.5.3, has some issues. 28 29 * `CMakeLists.txt`: 30 Build system for the examples and tests and logic for the bindings 31 installation. 32 33## Build Instructions 34 35> While the C++ Headers can be built and installed in isolation, it is part of the [OpenCL SDK](https://github.com/KhronosGroup/OpenCL-SDK). If looking for streamlined build experience and a complete development package, refer to the SDK build instructions instead of the following guide. 36 37### Dependencies 38 39The C++ Headers require: 40 41- the [OpenCL Headers](https://github.com/KhronosGroup/OpenCL-Headers/). 42 - It is recommended to install the headers via CMake, however a convenience shorthand is provided. Providing `OPENCL_CLHPP_HEADERS_DIR` to CMake, one may specify the location of OpenCL Headers. By default, the C++ Headers will look for OpenCL Headers under `${OPENCL_DIST_DIR}/include`. 43- the [OpenCL-ICD-Loader](https://github.com/KhronosGroup/OpenCL-ICD-Loader/) when building the examples 44 - It is recommended to install the ICD loader via CMake, however a convenience shorthand is provided. Providing `OPENCL_CLHPP_LOADER_DIR` to CMake, one may specify the location of the OpenCL ICD loader. By default, the C++ headers will look for OpenCL ICD loader under `${OPENCL_DIST_DIR}/lib`. 45- The C++ Headers uses CMake for its build system. 46If CMake is not provided by your build system or OS package manager, please consult the [CMake website](https://cmake.org). 47- The unit tests require [CMock](https://github.com/ThrowTheSwitch/CMock). To get this external dependency, use `--recursive` when cloning 48the repository, or run `git submodule update --init --recursive`. 49- Generating the mock input requires [Ruby](https://www.ruby-lang.org/en/). 50- Generating the docs requires Doxygen. When it is available, you can generate HTML documentation by building the `docs` target. 51 52### Example Build 53 541. Clone this repo, the OpenCL ICD Loader and the OpenCL Headers: 55 56 git clone --recursive https://github.com/KhronosGroup/OpenCL-CLHPP 57 git clone https://github.com/KhronosGroup/OpenCL-ICD-Loader 58 git clone https://github.com/KhronosGroup/OpenCL-Headers 59 601. Install OpenCL Headers CMake package 61 62 cmake -D CMAKE_INSTALL_PREFIX=./OpenCL-Headers/install -S ./OpenCL-Headers -B ./OpenCL-Headers/build 63 cmake --build ./OpenCL-Headers/build --target install 64 651. Build and install OpenCL ICD Loader CMake package. _(Note that `CMAKE_PREFIX_PATH` need to be an absolute path. Update as needed.)_ 66 67 cmake -D CMAKE_PREFIX_PATH=/absolute/path/to/OpenCL-Headers/install -D CMAKE_INSTALL_PREFIX=./OpenCL-ICD-Loader/install -S ./OpenCL-ICD-Loader -B ./OpenCL-ICD-Loader/build 68 cmake --build ./OpenCL-ICD-Loader/build --target install 69 701. Build and install OpenCL C++ Headers CMake package. 71 72 cmake -D CMAKE_PREFIX_PATH="/absolute/path/to/OpenCL-Headers/install;/absolute/path/to/OpenCL-ICD-Loader/install" -D CMAKE_INSTALL_PREFIX=./OpenCL-CLHPP/install -S ./OpenCL-CLHPP -B ./OpenCL-CLHPP/build 73 cmake --build ./OpenCL-CLHPP/build --target install 74 75### Example Use 76 77Example CMake invocation 78 79```bash 80cmake -D CMAKE_PREFIX_PATH="/chosen/install/prefix/of/headers;/chosen/install/prefix/of/loader;/chosen/install/prefix/of/cppheaders" /path/to/opencl/app 81``` 82 83and sample `CMakeLists.txt` 84 85```cmake 86cmake_minimum_required(VERSION 3.0) 87cmake_policy(VERSION 3.0...3.18.4) 88project(proj) 89add_executable(app main.cpp) 90find_package(OpenCLHeaders REQUIRED) 91find_package(OpenCLICDLoader REQUIRED) 92find_package(OpenCLHeadersCpp REQUIRED) 93target_link_libraries(app PRIVATE OpenCL::Headers OpenCL::OpenCL OpenCL::HeadersCpp) 94``` 95