FindPkgConfig: return the module found by pkg_search_module

When running `pkg_search_module`, it may be useful to get the matching
module name in order to run `pkg_get_variable`.

`pkg_search_module` now defines `<prefix>_MODULE_NAME` which contains
the first matching module name.

Fixes: #19648

Help/release/dev/FindPkgConfig-module-name.rst

@@ -0,0 +1,6 @@
+FindPkgConfig-module-name
+-------------------------
+
+* The :module:`FindPkgConfig` module :command:`pkg_search_module` macro
+  now defines a ``<prefix>_MODULE_NAME`` result variable containing the
+  first matching module name.

Modules/FindPkgConfig.cmake

@@ -363,6 +363,7 @@ macro(_pkg_check_modules_internal _is_required _is_silent _no_cmake_path _no_cma
   _pkgconfig_unset(${_prefix}_PREFIX)
   _pkgconfig_unset(${_prefix}_INCLUDEDIR)
   _pkgconfig_unset(${_prefix}_LIBDIR)
+  _pkgconfig_unset(${_prefix}_MODULE_NAME)
   _pkgconfig_unset(${_prefix}_LIBS)
   _pkgconfig_unset(${_prefix}_LIBS_L)
   _pkgconfig_unset(${_prefix}_LIBS_PATHS)
@@ -480,6 +481,7 @@ macro(_pkg_check_modules_internal _is_required _is_silent _no_cmake_path _no_cma
         foreach (variable IN ITEMS PREFIX INCLUDEDIR LIBDIR)
           _pkgconfig_set("${_pkg_check_prefix}_${variable}" "${${_pkg_check_prefix}_${variable}}")
         endforeach ()
+          _pkgconfig_set("${_pkg_check_prefix}_MODULE_NAME" "${_pkg_check_modules_pkg}")
 
         if (NOT ${_is_silent})
           message(STATUS "  Found ${_pkg_check_modules_pkg}, version ${_pkgconfig_VERSION}")
@@ -664,6 +666,10 @@ endmacro()
                       [IMPORTED_TARGET [GLOBAL]]
                       <moduleSpec> [<moduleSpec>...])
 
+  If a module is found, the ``<prefix>_MODULE_NAME`` variable will contain the
+  name of the matching module. This variable can be used if you need to run
+  :command:`pkg_get_variable`.
+
   Example:
 
   .. code-block:: cmake
@@ -688,6 +694,7 @@ macro(pkg_search_module _prefix _module0)
 
       if (${_prefix}_FOUND)
         set(_pkg_modules_found 1)
+        break()
       endif()
     endforeach()
 

Tests/RunCMake/FindPkgConfig/FindPkgConfig_GET_MATCHING_MODULE_NAME.cmake

@@ -0,0 +1,28 @@
+# Prepare environment to reuse bletch.pc
+file(TO_NATIVE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/pc-bletch/lib/pkgconfig" PC_PATH)
+if(UNIX)
+  string(REPLACE "\\ " " " PC_PATH "${PC_PATH}")
+endif()
+set(ENV{PKG_CONFIG_PATH} "${PC_PATH}")
+
+find_package(PkgConfig REQUIRED)
+pkg_search_module(FOO REQUIRED foo bletch bar)
+
+if(NOT FOO_MODULE_NAME STREQUAL "bletch")
+  message(FATAL_ERROR "Wrong value for FOO_MODULE_NAME. Expected: bletch, got: ${FOO_MODULE_NAME}")
+endif()
+
+pkg_get_variable(FOO_JACKPOT ${FOO_MODULE_NAME} jackpot)
+
+if(NOT FOO_JACKPOT STREQUAL "bletch-lives")
+  message(FATAL_ERROR "Wrong value for FOO_JACKPOT. Expected: bletch-lives, got: ${FOO_JACKPOT}")
+endif()
+
+unset(FOO_MODULE_NAME)
+
+# verify variable get's also set on subsequent run
+pkg_search_module(FOO REQUIRED foo bletch bar)
+
+if(NOT FOO_MODULE_NAME STREQUAL "bletch")
+  message(FATAL_ERROR "Wrong value for FOO_MODULE_NAME on second run. Expected: bletch, got: ${FOO_MODULE_NAME}")
+endif()

Tests/RunCMake/FindPkgConfig/RunCMakeTest.cmake

@@ -19,4 +19,5 @@ if (PKG_CONFIG_FOUND)
   run_cmake(FindPkgConfig_cache_variables)
   run_cmake(FindPkgConfig_IMPORTED_TARGET)
   run_cmake(FindPkgConfig_VERSION_OPERATORS)
+  run_cmake(FindPkgConfig_GET_MATCHING_MODULE_NAME)
 endif ()