guard provisional extensions with an opt-in define

[bashbaug]

fixes #247

Wraps provisional extensions in an opt-in define so applications that do not use provisional extensions do not get broken by non-backwards compatible changes.

Notes:

• The define gets added automatically during header generation based on the provisional="true" line in the XML file.
• The define is currently an opt-in named CL_PROVISIONAL_EXTENSIONS, but it's trivial to change this if desired.
• Because it is an opt-in define, the current implementation does break backwards compatiblity, and applications using provisional extensions will need to add the opt-in define.
• We should consider how much additional testing we want to add (in this repo and in others) with this change. For example, do we want to run some of the header tests with and without provisional extensions?

[kpet]

Generally looks good to me. I agree this should be an opt-in.

One minor comment on the name, I think we probably want a verb in there. A couple of ideas that come to mind:

• CL_ENABLE_PROVISIONAL_EXTENSIONS
• CL_USE_PROVISIONAL_EXTENSIONS

[bashbaug]

Vulkan uses VK_ENABLE_BETA_EXTENSIONS, so I have a slight preference for "enable".

How closely do we want to align? Should we use CL_ENABLE_BETA_EXTENSIONS, or do we prefer "provisional"?

[kpet]

"Beta" is maybe more intuitive for people not familiar with our terminology but all our documents and processes use "provisional". I think I'd personally favour consistency and use "provisional". If we were to use "beta", we would need to define somewhere that "beta" means "provisional" :).

[bashbaug]

I changed the name of the define to CL_ENABLE_PROVISIONAL_EXTENSIONS, as discussed above.

I also added some some amount of testing with the define set. Currently, I have only added this for OpenCL 3.0 builds, to avoid doubling the number of test configurations. My thinking is: most provisional extensions will be written against OpenCL 3.0, and OpenCL 3.0 will have all OpenCL features enabled so it'd be most likely to expose issues. It's easy to change this, though, if other testing is desired.

[EwanC]

Change looks good, we should update the root README.md with how to opt-in

[EwanC]

Could we extend the tests themselves to obverse the effects of the macro, for example something like this intests/test_ext_headers.c

int provisional_macro(void) {

#ifdef CL_ENABLE_PROVISIONAL_EXTENSIONS
   printf("%s is available\n", CL_KHR_COMMAND_BUFFER_EXTENSION_NAME);

#else

#ifdef CL_KHR_COMMAND_BUFFER_EXTENSION_NAME
   assert(false && "cl_khr_command_buffer macros should not be defined"); 
   return 1;
#endif // CL_KHR_COMMAND_BUFFER_EXTENSION_NAME
    
#endif // CL_ENABLE_PROVISIONAL_EXTENSIONS

return 0;
}