KhronosGroup / KhronosGroup/OpenCL-Docs
Clarify interaction between extension pragma and #ifdef
- Dominant language
- Python
- Stars
- 420
- Forks
- 131
- Avg merge
- 5d 13h
- Merged PRs (30d)
- 11
Description
Splitting this issue off from the discussion here: https://github.com/KhronosGroup/OpenCL-Docs/pull/355#issuecomment-738299222
The extension documentation currently states:
> Every extension which affects the OpenCL language semantics, syntax or adds built-in functions to the language must create a preprocessor #define that matches the extension name string. This #define would be available in the language if and only if the extension is supported on a given implementation.
[[introduction](https://github.com/KhronosGroup/OpenCL-Docs/blob/master/ext/introduction.asciidoc)]
It's not immediately clear from this text that extension pragmas don't affect `#define`s. From #355:
> I think the intent is that preprocessor macros communicate to the OpenCL-C kernel what extensions are available, and kernels use pragmas to indicate which extensions they want to use. What might not be immediately obvious to a developer is that the preprocessor runs before pragmas are evaluated, so a pragma ... disable doesn't undef the extension macro.
E.g.:
```c
#pragma OPENCL EXTENSION cl_khr_fp64 : disable
#ifdef cl_khr_fp64
// Code here is actually compiled
#endif
```
Contributor guide
Research direction
Read ext/introduction.asciidoc and the linked discussion in pull request 355, especially the cited explanation of preprocessing and pragma evaluation. Clarify in the extension documentation that extension pragmas do not change the corresponding preprocessor macro, including the shown #ifdef case, and verify that the wording matches the intended behavior.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- c
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 1/5
- Estimated time
- 1-3 hours
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100