FindOpenCL: Add OpenCL_VERSION

- This deprecates the OPENCL_VERSION_STRING result variable.
- Documentation adjusted.
- Support for OpenCL 3.0 was added in CMake 3.24.
- Added CL_TARGET_OPENCL_VERSION compile definition to test so that
  program compiles without warnings.
- Additionally, on Apple systems compiler can't find <Headers/cl.h>
  unless direct path would be passed as a header. Instead, <OpenCL/cl.h>
  is used for version check conditionally.

Issue: #27088

Help/release/dev/find-modules.rst

@@ -60,6 +60,9 @@ Find Modules
   ``Lua_VERSION`` instead of the now deprecated ``LUA_VERSION_STRING`` result
   variable.
 
+* The :module:`FindOpenCL` module now provides an ``OpenCL_VERSION`` result
+  variable.  The ``OpenCL_VERSION_STRING`` result variable is deprecated.
+
 * The :module:`FindOpenSceneGraph` module now provides an
   ``OpenSceneGraph_VERSION`` result variable.  The ``OPENSCENEGRAPH_VERSION``
   result variable is deprecated.

Modules/FindOpenCL.cmake

@@ -13,19 +13,25 @@ Finds Open Computing Language (OpenCL):
 
   find_package(OpenCL [<version>] [...])
 
+OpenCL is a framework for writing programs that execute across heterogeneous
+platforms, such as CPUs, GPUs, and other accelerators.
+
+.. versionadded:: 3.24
+  Detection of OpenCL 3.0.
+
 .. versionadded:: 3.10
   Detection of OpenCL 2.1 and 2.2.
 
 Imported Targets
 ^^^^^^^^^^^^^^^^
 
-.. versionadded:: 3.7
-
-This module provides the following :ref:`Imported Targets`, if OpenCL has been
-found:
+This module provides the following :ref:`Imported Targets`:
 
 ``OpenCL::OpenCL``
-  Target providing OpenCL usage requirements.
+  .. versionadded:: 3.7
+
+  Target encapsulating the OpenCL usage requirements, available if OpenCL
+  has been found.
 
 Result Variables
 ^^^^^^^^^^^^^^^^
@@ -33,18 +39,26 @@ Result Variables
 This module defines the following variables:
 
 ``OpenCL_FOUND``
-  True if OpenCL was found.
-``OpenCL_INCLUDE_DIRS``
-  Include directories needed to use OpenCL.
-``OpenCL_LIBRARIES``
-  Libraries needed to link to OpenCL.
-``OpenCL_VERSION_STRING``
-  Highest supported OpenCL version (e.g., ``1.2``).
+  Boolean indicating whether (the requested version of) OpenCL was found.
+
+``OpenCL_VERSION``
+  .. versionadded:: 4.2
+
+  Highest supported OpenCL version found in form of ``<major>.<minor>``
+  (e.g., ``1.2``).
+
 ``OpenCL_VERSION_MAJOR``
   The major version of the OpenCL implementation.
+
 ``OpenCL_VERSION_MINOR``
   The minor version of the OpenCL implementation.
 
+``OpenCL_INCLUDE_DIRS``
+  Include directories needed to use OpenCL.
+
+``OpenCL_LIBRARIES``
+  Libraries needed to link to OpenCL.
+
 Cache Variables
 ^^^^^^^^^^^^^^^
 
@@ -52,9 +66,21 @@ The following cache variables may also be set:
 
 ``OpenCL_INCLUDE_DIR``
   The OpenCL include directory.
+
 ``OpenCL_LIBRARY``
   The path to the OpenCL library.
 
+Deprecated Variables
+^^^^^^^^^^^^^^^^^^^^
+
+The following variables are provided for backward compatibility:
+
+``OpenCL_VERSION_STRING``
+  .. deprecated:: 4.2
+    Use ``OpenCL_VERSION``, which has the same value.
+
+  Highest supported OpenCL version found in form of ``<major>.<minor>``.
+
 Examples
 ^^^^^^^^
 
@@ -66,21 +92,28 @@ Finding OpenCL and linking it to a project target:
   target_link_libraries(project_target PRIVATE OpenCL::OpenCL)
 #]=======================================================================]
 
+cmake_policy(PUSH)
+cmake_policy(SET CMP0140 NEW)
+
 set(_OPENCL_x86 "(x86)")
 
 function(_FIND_OPENCL_VERSION)
+  include(CheckIncludeFiles)
   include(CheckSymbolExists)
   include(CMakePushCheckState)
-  set(CMAKE_REQUIRED_QUIET ${OpenCL_FIND_QUIETLY})
 
   cmake_push_check_state()
-  foreach(VERSION "3_0" "2_2" "2_1" "2_0" "1_2" "1_1" "1_0")
-    set(CMAKE_REQUIRED_INCLUDES "${OpenCL_INCLUDE_DIR}")
 
-    if(EXISTS ${OpenCL_INCLUDE_DIR}/Headers/cl.h)
+  set(CMAKE_REQUIRED_QUIET ${OpenCL_FIND_QUIETLY})
+  set(CMAKE_REQUIRED_INCLUDES "${OpenCL_INCLUDE_DIR}")
+
+  check_include_files(OpenCL/cl.h OpenCL_HAVE_OPENCL_CL_H)
+
+  foreach(VERSION "3_0" "2_2" "2_1" "2_0" "1_2" "1_1" "1_0")
+    if(OpenCL_HAVE_OPENCL_CL_H)
       check_symbol_exists(
         CL_VERSION_${VERSION}
-        "Headers/cl.h"
+        "OpenCL/cl.h"
         OPENCL_VERSION_${VERSION})
     else()
       check_symbol_exists(
@@ -91,16 +124,25 @@ function(_FIND_OPENCL_VERSION)
 
     if(OPENCL_VERSION_${VERSION})
       string(REPLACE "_" "." VERSION "${VERSION}")
-      set(OpenCL_VERSION_STRING ${VERSION} PARENT_SCOPE)
+      set(OpenCL_VERSION ${VERSION})
+      set(OpenCL_VERSION_STRING "${OpenCL_VERSION}")
       string(REGEX MATCHALL "[0-9]+" version_components "${VERSION}")
       list(GET version_components 0 major_version)
       list(GET version_components 1 minor_version)
-      set(OpenCL_VERSION_MAJOR ${major_version} PARENT_SCOPE)
-      set(OpenCL_VERSION_MINOR ${minor_version} PARENT_SCOPE)
+      set(OpenCL_VERSION_MAJOR ${major_version})
+      set(OpenCL_VERSION_MINOR ${minor_version})
       break()
     endif()
   endforeach()
   cmake_pop_check_state()
+
+  return(
+    PROPAGATE
+      OpenCL_VERSION
+      OpenCL_VERSION_MAJOR
+      OpenCL_VERSION_MINOR
+      OpenCL_VERSION_STRING
+  )
 endfunction()
 
 find_path(OpenCL_INCLUDE_DIR
@@ -204,7 +246,8 @@ include(FindPackageHandleStandardArgs)
 find_package_handle_standard_args(
   OpenCL
   REQUIRED_VARS OpenCL_LIBRARY OpenCL_INCLUDE_DIR
-  VERSION_VAR OpenCL_VERSION_STRING)
+  VERSION_VAR OpenCL_VERSION
+)
 
 mark_as_advanced(
   OpenCL_INCLUDE_DIR
@@ -223,3 +266,5 @@ if(OpenCL_FOUND AND NOT TARGET OpenCL::OpenCL)
   set_target_properties(OpenCL::OpenCL PROPERTIES
     INTERFACE_INCLUDE_DIRECTORIES "${OpenCL_INCLUDE_DIRS}")
 endif()
+
+cmake_policy(POP)

Tests/CMakeOnly/AllFindModules/CMakeLists.txt

@@ -102,6 +102,7 @@ foreach(
     ICOTOOL
     JASPER
     LIBLZMA LIBXML2 LIBXSLT LTTNGUST
+    OpenCL
     PERL PKG_CONFIG PNG PostgreSQL
     SDL
     TIFF
@@ -123,7 +124,7 @@ foreach(
     HDF5 Hg
     Jasper JPEG
     LibArchive LibLZMA LIBLZMA LibXml2 LibXslt LTTngUST
-    OpenSceneGraph OPENSCENEGRAPH OpenSSL OPENSSL
+    OpenCL OpenSceneGraph OPENSCENEGRAPH OpenSSL OPENSSL
     Perl PerlLibs PkgConfig PNG PostgreSQL Protobuf
     Ruby RUBY
     SDL SWIG

Tests/FindOpenCL/Test/CMakeLists.txt

@@ -4,6 +4,10 @@ include(CTest)
 
 find_package(OpenCL REQUIRED)
 
+add_compile_definitions(
+  CL_TARGET_OPENCL_VERSION=${OpenCL_VERSION_MAJOR}${OpenCL_VERSION_MINOR}0
+)
+
 add_executable(test_tgt main.c)
 target_link_libraries(test_tgt OpenCL::OpenCL)
 add_test(NAME test_tgt COMMAND test_tgt)