Merge topic 'FindGDAL-improvements' into release-3.20

55e493928b FindGDAL: add release note
f4b53fadda FindGDAL: support finding additional GDAL library names
1b2774450d FindGDAL: add support for skipping gdal-config
1621cb3eb1 FindGDAL: add documentation to cache variables
3caaff4c08 FindGDAL: conditionally set the output variables
3f6a4f2062 FindGDAL: mark cache variables as advanced
02e906305d FindGDAL: use execute_process instead of exec_program
140344da14 FindGDAL: fix some indentation

Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !5799

Help/release/3.20.rst

@@ -188,6 +188,12 @@ Modules
   toolkits when ``nvcc`` is a symbolic link,
   for example due to a ``ccache`` or ``colornvcc`` wrapper script.
 
+* The :module:`FindGDAL` module has been improved to document and mark as
+  advanced its cache variables. There is a new ``FindGDAL_SKIP_GDAL_CONFIG``
+  variable which may be used to skip over the ``gdal-config``-based search.
+  Users may also set ``GDAL_ADDITIONAL_LIBRARY_VERSIONS`` to add additional
+  versions to the library name search strategy.
+
 * The :module:`FindIntl` module now provides an imported target.
 
 * The :module:`FindOpenSSL` module learned to support a version range.

Modules/FindGDAL.cmake

@@ -45,6 +45,15 @@ Hints
 
 Set ``GDAL_DIR`` or ``GDAL_ROOT`` in the environment to specify the
 GDAL installation prefix.
+
+The following variables may be set to modify the search strategy:
+
+``FindGDAL_SKIP_GDAL_CONFIG``
+  If set, ``gdal-config`` will not be used. This can be useful if there are
+  GDAL libraries built with autotools (which provide the tool) and CMake (which
+  do not) in the same environment.
+``GDAL_ADDITIONAL_LIBRARY_VERSIONS``
+  Extra versions of library names to search for.
 #]=======================================================================]
 
 # $GDALDIR is an environment variable that would
@@ -68,12 +77,14 @@ find_path(GDAL_INCLUDE_DIR gdal.h
     ENV GDAL_DIR
     ENV GDAL_ROOT
   PATH_SUFFIXES
-     include/gdal
-     include/GDAL
-     include
+    include/gdal
+    include/GDAL
+    include
+  DOC "Path to the GDAL include directory"
 )
+mark_as_advanced(GDAL_INCLUDE_DIR)
 
-if(UNIX)
+if(UNIX AND NOT FindGDAL_SKIP_GDAL_CONFIG)
     # Use gdal-config to obtain the library version (this should hopefully
     # allow us to -lgdal1.x.y where x.y are correct version)
     # For some reason, libgdal development packages do not contain
@@ -83,10 +94,12 @@ if(UNIX)
           ENV GDAL_DIR
           ENV GDAL_ROOT
         PATH_SUFFIXES bin
+        DOC "Path to the gdal-config tool"
     )
+    mark_as_advanced(GDAL_CONFIG)
 
     if(GDAL_CONFIG)
-        exec_program(${GDAL_CONFIG} ARGS --libs OUTPUT_VARIABLE GDAL_CONFIG_LIBS)
+        execute_process(COMMAND ${GDAL_CONFIG} --libs OUTPUT_VARIABLE GDAL_CONFIG_LIBS)
 
         if(GDAL_CONFIG_LIBS)
             # treat the output as a command line and split it up
@@ -134,14 +147,30 @@ if(UNIX)
     endif()
 endif()
 
+# GDAL name its library when built with CMake as `gdal${major}${minor}`.
+set(_gdal_versions
+    ${GDAL_ADDITIONAL_LIBRARY_VERSIONS} 3.0 2.4 2.3 2.2 2.1 2.0 1.11 1.10 1.9 1.8 1.7 1.6 1.5 1.4 1.3 1.2)
+
+set(_gdal_libnames)
+foreach (_gdal_version IN LISTS _gdal_versions)
+    string(REPLACE "." "" _gdal_version "${_gdal_version}")
+    list(APPEND _gdal_libnames "gdal${_gdal_version}" "GDAL${_gdal_version}")
+endforeach ()
+unset(_gdal_version)
+unset(_gdal_versions)
+
 find_library(GDAL_LIBRARY
-  NAMES ${_gdal_lib} gdal gdal_i gdal1.5.0 gdal1.4.0 gdal1.3.2 GDAL
+  NAMES ${_gdal_lib} ${_gdal_libnames} gdal gdal_i gdal1.5.0 gdal1.4.0 gdal1.3.2 GDAL
   HINTS
      ENV GDAL_DIR
      ENV GDAL_ROOT
      ${_gdal_libpath}
   PATH_SUFFIXES lib
+  DOC "Path to the GDAL library"
 )
+mark_as_advanced(GDAL_LIBRARY)
+unset(_gdal_libnames)
+unset(_gdal_lib)
 
 if (EXISTS "${GDAL_INCLUDE_DIR}/gdal_version.h")
     file(STRINGS "${GDAL_INCLUDE_DIR}/gdal_version.h" _gdal_version
@@ -157,12 +186,14 @@ FIND_PACKAGE_HANDLE_STANDARD_ARGS(GDAL
     VERSION_VAR GDAL_VERSION
     REQUIRED_VARS GDAL_LIBRARY GDAL_INCLUDE_DIR)
 
-if (GDAL_FOUND AND NOT TARGET GDAL::GDAL)
-    add_library(GDAL::GDAL UNKNOWN IMPORTED)
-    set_target_properties(GDAL::GDAL PROPERTIES
-        IMPORTED_LOCATION "${GDAL_LIBRARY}"
-        INTERFACE_INCLUDE_DIRECTORIES "${GDAL_INCLUDE_DIR}")
-endif ()
+if (GDAL_FOUND)
+    set(GDAL_LIBRARIES ${GDAL_LIBRARY})
+    set(GDAL_INCLUDE_DIRS ${GDAL_INCLUDE_DIR})
 
-set(GDAL_LIBRARIES ${GDAL_LIBRARY})
-set(GDAL_INCLUDE_DIRS ${GDAL_INCLUDE_DIR})
+    if (NOT TARGET GDAL::GDAL)
+        add_library(GDAL::GDAL UNKNOWN IMPORTED)
+        set_target_properties(GDAL::GDAL PROPERTIES
+            IMPORTED_LOCATION "${GDAL_LIBRARY}"
+            INTERFACE_INCLUDE_DIRECTORIES "${GDAL_INCLUDE_DIR}")
+    endif ()
+endif ()