Merge topic 'patch-FindOpenMP' into release-4.2

e5aa17333d FindOpenMP: Set the version result variable and update docs

Acked-by: Kitware Robot <[email protected]>
Merge-request: !11304

Modules/FindOpenMP.cmake

@@ -9,7 +9,7 @@ Finds Open Multi-Processing (OpenMP) support in a compiler:
 
 .. code-block:: cmake
 
-  find_package(OpenMP [<version>] [COMPONENTS <components>...] [...])
+  find_package(OpenMP [<version>] [COMPONENTS <langs>...] [...])
 
 If the compiler supports OpenMP, the flags required to compile with OpenMP
 support are returned in variables for the different languages.  The variables
@@ -26,7 +26,7 @@ syntax:
 
 .. code-block:: cmake
 
-  find_package(OpenMP [COMPONENTS <components>...])
+  find_package(OpenMP [COMPONENTS <langs>...])
 
 Each of these components controls the various languages to search OpenMP
 support for.  The following components are exposed:
@@ -46,7 +46,8 @@ support for.  The following components are exposed:
   The ``CUDA`` language component is supported when using a CUDA compiler
   that supports OpenMP on the host.
 
-If no components are specified, module checks for all of them automatically.
+If no components are specified, module checks for all of them automatically,
+depending on the enabled languages in the project.
 
 Imported Targets
 ^^^^^^^^^^^^^^^^
@@ -85,6 +86,8 @@ This module defines the following variables:
   true if OpenMP settings for all enabled languages were detected.
 
 ``OpenMP_VERSION``
+  .. versionadded:: 4.2
+
   Minimal version of the OpenMP standard detected among the requested
   languages, or all enabled languages if no components were specified.
 
@@ -92,10 +95,44 @@ This module will set the following variables per language in the
 project, where ``<lang>`` is one of C, CXX, CUDA, or Fortran:
 
 ``OpenMP_<lang>_FOUND``
-  Variable indicating if OpenMP support for ``<lang>`` was detected.
+  .. versionadded:: 3.9
+
+  Boolean indicating whether the (requested version of) OpenMP support for
+  ``<lang>`` was detected.
+
+``OpenMP_<lang>_VERSION``
+  .. versionadded:: 3.9
+
+  OpenMP version implemented by the ``<lang>`` compiler, if available.
+
+``OpenMP_<lang>_VERSION_MAJOR``
+  .. versionadded:: 3.9
+
+  Major version of OpenMP implemented by the ``<lang>`` compiler, if
+  available.
+
+``OpenMP_<lang>_VERSION_MINOR``
+  .. versionadded:: 3.9
+
+  Minor version of OpenMP implemented by the ``<lang>`` compiler, if
+  available.
+
+``OpenMP_<lang>_SPEC_DATE``
+  .. versionadded:: 3.7
+
+  Date of the OpenMP specification implemented by the ``<lang>`` compiler,
+  if available.
+
+  The specification date is formatted as given in the OpenMP standard:
+  ``yyyymm`` where ``yyyy`` and ``mm`` represents the year and month of the
+  OpenMP specification implemented by the ``<lang>`` compiler.
+
 ``OpenMP_<lang>_FLAGS``
   OpenMP compiler flags for ``<lang>``, separated by spaces.
+
 ``OpenMP_<lang>_INCLUDE_DIRS``
+  .. versionadded:: 3.16
+
   Directories that must be added to the header search path for ``<lang>``
   when using OpenMP.
 
@@ -103,46 +140,45 @@ For linking with OpenMP code written in ``<lang>``, the following
 variables are provided:
 
 ``OpenMP_<lang>_LIB_NAMES``
-  :ref:`semicolon-separated list <CMake Language Lists>` of libraries for
-  OpenMP programs for ``<lang>``.
+  .. versionadded:: 3.9
+
+  A :ref:`semicolon-separated list <CMake Language Lists>` of OpenMP
+  programs libraries for ``<lang>``.
+
 ``OpenMP_<libname>_LIBRARY``
+  .. versionadded:: 3.9
+
   Location of the individual libraries needed for OpenMP support in
-  ``<lang>``.
+  ``<lang>``.  The ``<libname>`` names are stored in the
+  ``OpenMP_<lang>_LIB_NAMES`` list.
+
 ``OpenMP_<lang>_LIBRARIES``
+  .. versionadded:: 3.9
+
   A list of libraries needed to link with OpenMP code written in ``<lang>``.
 
 Specifically for Fortran, the module sets the following variables:
 
 ``OpenMP_Fortran_HAVE_OMPLIB_HEADER``
-  Boolean indicating if OpenMP is accessible through ``omp_lib.h``.
-``OpenMP_Fortran_HAVE_OMPLIB_MODULE``
-  Boolean indicating if OpenMP is accessible through the ``omp_lib`` Fortran
-  module.
-
-The module will also try to provide the OpenMP version variables:
+  .. versionadded:: 3.9
 
-``OpenMP_<lang>_SPEC_DATE``
-  .. versionadded:: 3.7
+  Boolean indicating whether OpenMP is accessible through the ``omp_lib.h``
+  Fortran header.
 
-  Date of the OpenMP specification implemented by the ``<lang>`` compiler.
-``OpenMP_<lang>_VERSION_MAJOR``
-  Major version of OpenMP implemented by the ``<lang>`` compiler.
-``OpenMP_<lang>_VERSION_MINOR``
-  Minor version of OpenMP implemented by the ``<lang>`` compiler.
-``OpenMP_<lang>_VERSION``
-  OpenMP version implemented by the ``<lang>`` compiler.
+``OpenMP_Fortran_HAVE_OMPLIB_MODULE``
+  .. versionadded:: 3.9
 
-The specification date is formatted as given in the OpenMP standard:
-``yyyymm`` where ``yyyy`` and ``mm`` represents the year and month of
-the OpenMP specification implemented by the ``<lang>`` compiler.
+  Boolean indicating whether OpenMP is accessible through the ``omp_lib``
+  Fortran module.
 
 For some compilers, it may be necessary to add a header search path to find
 the relevant OpenMP headers.  This location may be language-specific.  Where
 this is needed, the module may attempt to find the location, but it can be
 provided directly by setting the ``OpenMP_<lang>_INCLUDE_DIR`` cache variable.
-Note that this variable is an _input_ control to the module.  Project code
-should use the ``OpenMP_<lang>_INCLUDE_DIRS`` _output_ variable if it needs
-to know what include directories are needed.
+Note that this variable is an *input* control to the module.  Project code
+should use the ``OpenMP_<lang>_INCLUDE_DIRS`` *output* variable if it needs
+to know what include directories are needed, or preferably the
+``OpenMP::OpenMP_<lang>`` imported target.
 
 Examples
 ^^^^^^^^
@@ -668,7 +704,7 @@ else()
   set(OpenMP_FINDLIST ${OpenMP_FIND_COMPONENTS})
 endif()
 
-unset(_OpenMP_MIN_VERSION)
+unset(OpenMP_VERSION)
 
 include(FindPackageHandleStandardArgs)
 
@@ -703,8 +739,8 @@ foreach(LANG IN LISTS OpenMP_FINDLIST)
 
     if(OpenMP_${LANG}_FOUND)
       if(DEFINED OpenMP_${LANG}_VERSION)
-        if(NOT _OpenMP_MIN_VERSION OR _OpenMP_MIN_VERSION VERSION_GREATER OpenMP_${LANG}_VERSION)
-          set(_OpenMP_MIN_VERSION OpenMP_${LANG}_VERSION)
+        if(NOT OpenMP_VERSION OR OpenMP_VERSION VERSION_GREATER OpenMP_${LANG}_VERSION)
+          set(OpenMP_VERSION "${OpenMP_${LANG}_VERSION}")
         endif()
       endif()
       set(OpenMP_${LANG}_LIBRARIES "")
@@ -751,7 +787,7 @@ endforeach()
 
 find_package_handle_standard_args(OpenMP
     REQUIRED_VARS ${_OpenMP_REQ_VARS}
-    VERSION_VAR ${_OpenMP_MIN_VERSION}
+    VERSION_VAR OpenMP_VERSION
     HANDLE_COMPONENTS)
 
 if(CMAKE_Fortran_COMPILER_LOADED AND OpenMP_Fortran_FOUND)