README.md
1# OpenCL<sup>TM</sup> API Headers
2
3This repository contains C language headers for the OpenCL API.
4
5The authoritative public repository for these headers is located at:
6
7https://github.com/KhronosGroup/OpenCL-Headers
8
9Issues, proposed fixes for issues, and other suggested changes should be
10created using Github.
11
12## Build instructions
13
14> While the OpenCL 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.
15
16### Dependencies
17
18- The OpenCL Headers CMake package support uses CMake for its build system.
19If CMake is not provided by your build system or OS package manager, please consult the [CMake website](https://cmake.org).
20
21### Example Build
22While the headers may just be copied as-is, this repository also contains a
23CMake script with an install rule to allow for packaging the headers.
24
25```bash
26cmake -S . -B build -DCMAKE_INSTALL_PREFIX=/chosen/install/prefix
27cmake --build build --target install
28```
29
30### Example Use
31
32Example CMake invocation
33
34```bash
35cmake -D CMAKE_PREFIX_PATH=/chosen/install/prefix /path/to/opencl/app
36```
37
38and sample `CMakeLists.txt`
39
40```cmake
41cmake_minimum_required(VERSION 3.0)
42cmake_policy(VERSION 3.0...3.18.4)
43project(proj)
44add_executable(app main.cpp)
45find_package(OpenCLHeaders REQUIRED)
46target_link_libraries(app PRIVATE OpenCL::Headers)
47```
48
49## Branch Structure
50
51The OpenCL API headers in this repository are Unified headers and are designed
52to work with all released OpenCL versions. This differs from previous OpenCL
53API headers, where version-specific API headers either existed in separate
54branches, or in separate folders in a branch.
55
56## Compiling for a Specific OpenCL Version
57
58By default, the OpenCL API headers in this repository are for the latest
59OpenCL version (currently OpenCL 3.0). To use these API headers to target
60a different OpenCL version, an application may `#define` the preprocessor
61value `CL_TARGET_OPENCL_VERSION` before including the OpenCL API headers.
62The `CL_TARGET_OPENCL_VERSION` is a three digit decimal value representing
63the OpenCL API version.
64
65For example, to enforce usage of no more than the OpenCL 1.2 APIs, you may
66include the OpenCL API headers as follows:
67
68```c
69#define CL_TARGET_OPENCL_VERSION 120
70#include <CL/opencl.h>
71```
72
73## Controlling Function Prototypes
74
75By default, the OpenCL API headers in this repository declare function
76prototypes for every known core OpenCL API and OpenCL extension API. If this is
77not desired, the declared function prototypes can be controlled by the following
78preprocessor defines:
79
80* `CL_NO_PROTOTYPES`: No function prototypes will be declared. This control
81 applies to core OpenCL APIs and OpenCL extension APIs.
82* `CL_NO_CORE_PROTOTYPES`: No function prototypes will be declared for core
83 OpenCL APIs.
84* `CL_NO_EXTENSION_PROTOTYPES`: No function prototypes will be declared for
85 OpenCL extension APIs. This control applies to all OpenCL extension APIs.
86* `CL_NO_ICD_DISPATCH_EXTENSION_PROTOTYPES`: No function prototypes will be
87 declared for OpenCL extension APIs that are in the ICD dispatch table for
88 historical reasons.
89* `CL_NO_NON_ICD_DISPATCH_EXTENSION_PROTOTYPES`: No function prototypes will be
90 declared for OpenCL extension APIs that are not in the ICD dispatch table.
91
92For example, to declare function prototypes for core OpenCL 3.0 APIs only, you
93may include the OpenCL API headers as follows:
94
95```c
96#define CL_TARGET_OPENCL_VERSION 300
97#define CL_NO_EXTENSION_PROTOTYPES
98#include <CL/opencl.h>
99```
100
101## Compatibility Notes
102
103OpenCL values backward compatibility and in most cases an application using an
104older version of the OpenCL API headers can seamlessly update to a newer version
105of the OpenCL API headers. In rare cases, though, the OpenCL API headers may
106break backward compatibility:
107
108* Very rarely, there may be bugs or other issues in the OpenCL API headers that
109 cannot be fixed without breaking compatibility.
110* The OpenCL API headers for provisional features or provisional extensions may
111 be changed in a way that breaks compatibility.
112
113Applications or libraries that require stable OpenCL API headers are encouraged
114to use tagged or released OpenCL API headers. We will do our best to document
115any breaking changes in the description of each release. The OpenCL API headers
116are tagged at least as often as each OpenCL specification release.
117
118## Directory Structure
119
120```
121README.md This file
122LICENSE Source license for the OpenCL API headers
123CL/ Unified OpenCL API headers tree
124```
125
126## License
127
128See [LICENSE](LICENSE).
129
130---
131
132OpenCL and the OpenCL logo are trademarks of Apple Inc. used by permission by Khronos.
133