README.md
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