1*3cc25752SFrank Piva# OpenCL Header Code Generation 2*3cc25752SFrank Piva 3*3cc25752SFrank Piva## Introduction 4*3cc25752SFrank Piva 5*3cc25752SFrank PivaIn 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. 6*3cc25752SFrank PivaCurrently, header generation is only enabled for the OpenCL headers for extensions, and the OpenCL headers for core APIs are still authored manually. 7*3cc25752SFrank Piva 8*3cc25752SFrank Piva## Dependencies 9*3cc25752SFrank Piva 10*3cc25752SFrank PivaThe OpenCL headers are generated using Python [Mako Templates](https://www.makotemplates.org/). 11*3cc25752SFrank Piva 12*3cc25752SFrank PivaIn most cases, after installing Python for your platform, Mako may be installed using: 13*3cc25752SFrank Piva 14*3cc25752SFrank Piva```sh 15*3cc25752SFrank Piva$ pip install Mako 16*3cc25752SFrank Piva``` 17*3cc25752SFrank Piva 18*3cc25752SFrank Piva## Making Changes 19*3cc25752SFrank Piva 20*3cc25752SFrank PivaMost changes only require modifications to the Mako templates. 21*3cc25752SFrank PivaSmall changes modifying syntax or layout are simple and straightforward. 22*3cc25752SFrank PivaOccasionally, 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*3cc25752SFrank Piva 24*3cc25752SFrank PivaThe 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*3cc25752SFrank Piva 26*3cc25752SFrank Piva## Generating Headers 27*3cc25752SFrank Piva 28*3cc25752SFrank PivaThe script to generate headers requires the `cl.xml` machine readable grammar. 29*3cc25752SFrank PivaThe 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*3cc25752SFrank Piva 31*3cc25752SFrank PivaThe easiest way to generate new headers is by using the `headers_generate` target. 32*3cc25752SFrank PivaFor example, from a directory used to build the headers, simply execute: 33*3cc25752SFrank Piva 34*3cc25752SFrank Piva```sh 35*3cc25752SFrank Piva$ cmake --build . --target headers_generate 36*3cc25752SFrank Piva``` 37*3cc25752SFrank Piva 38*3cc25752SFrank PivaThe `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