README.md
1# OpenCL Header Code Generation
2
3## Introduction
4
5In order to ease maintenance and enable faster development in the OpenCL headers, the OpenCL headers for extensions are generated from the OpenCL XML machine readable grammar.
6Currently, header generation is only enabled for the OpenCL headers for extensions, and the OpenCL headers for core APIs are still authored manually.
7
8## Dependencies
9
10The OpenCL headers are generated using Python [Mako Templates](https://www.makotemplates.org/).
11
12In most cases, after installing Python for your platform, Mako may be installed using:
13
14```sh
15$ pip install Mako
16```
17
18## Making Changes
19
20Most changes only require modifications to the Mako templates.
21Small changes modifying syntax or layout are simple and straightforward.
22Occasionally, more complicated changes will be required, say when a new API is added that is unlike any previous API or when a new extension header file is needed, but this should be rare.
23
24The Python script should only need to be modified if additional information needs to be propagated from the XML file into the Mako template itself.
25
26## Generating Headers
27
28The script to generate headers requires the `cl.xml` machine readable grammar.
29The latest version of `cl.xml` may be found in the Khronos OpenCL-Docs repo [here](https://github.com/KhronosGroup/OpenCL-Docs/blob/main/xml/cl.xml).
30
31The easiest way to generate new headers is by using the `headers_generate` target.
32For example, from a directory used to build the headers, simply execute:
33
34```sh
35$ cmake --build . --target headers_generate
36```
37
38The `cl.xml` file used to generate headers with the header generation target may be provided by setting the CMake variable `OPENCL_HEADERS_XML_PATH` to the full path to `cl.xml`.
39