From 0179aaffdc2f908dd762810982736d1ed44de76f Mon Sep 17 00:00:00 2001 From: Ben Ashbaugh Date: Wed, 12 Apr 2023 08:17:01 -0700 Subject: [PATCH 1/2] add README, update required Mako version --- scripts/README.md | 38 ++++++++++++++++++++++++++++++++++++++ scripts/requirements.txt | 2 +- 2 files changed, 39 insertions(+), 1 deletion(-) create mode 100644 scripts/README.md diff --git a/scripts/README.md b/scripts/README.md new file mode 100644 index 00000000..52a9784c --- /dev/null +++ b/scripts/README.md @@ -0,0 +1,38 @@ +# OpenCL Header Code Generation + +## Introduction + +In 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. +Currently, header generation is only enabled for the OpenCL headers for extensions, and the OpenCL headers for core APIs are still authored manually. + +## Dependencies + +The OpenCL headers are generated using Python [Mako Templates](https://www.makotemplates.org/). + +In most cases, after installing Python for your platform, Mako may be installed using: + +```sh +$ pip install Mako +``` + +## Making Changes + +Most changes only require modifications to the Mako templates. +Small changes modifying syntax or layout are simple and straightforward. +Occasionally, 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. + +The Python script should only need to be modified if additional information needs to be propagated from the XML file into the Mako template itself. + +## Generating Headers + +The script to generate headers requires the `cl.xml` machine readable grammar. +The 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). + +The easiest way to generate new headers is by using the `headers_generate` target. +For example, from a directory used to build the headers, simply execute: + +```sh +$ cmake --build . --target headers_generate +``` + +The `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`. diff --git a/scripts/requirements.txt b/scripts/requirements.txt index 003d342f..650c29a4 100644 --- a/scripts/requirements.txt +++ b/scripts/requirements.txt @@ -1 +1 @@ -Mako==1.1.0 +Mako>=1.2.2 From 32e45b89e53f9b0d353ab2150b42416dda3d0caa Mon Sep 17 00:00:00 2001 From: Ben Ashbaugh Date: Thu, 13 Apr 2023 07:37:52 -0700 Subject: [PATCH 2/2] minor grammar fix Co-authored-by: Ewan Crawford --- scripts/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/scripts/README.md b/scripts/README.md index 52a9784c..6597642e 100644 --- a/scripts/README.md +++ b/scripts/README.md @@ -2,7 +2,7 @@ ## Introduction -In 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. +In 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. Currently, header generation is only enabled for the OpenCL headers for extensions, and the OpenCL headers for core APIs are still authored manually. ## Dependencies