CMake: Introduce QT_DEBUG_FIND_PACKAGE for troubleshooting

When a Qt component or dependency is not found, we will now show a
message that the user can reconfigure the project with
-DQT_DEBUG_FIND_PACKAGE=ON.

If the option is enabled, various variables that find_package uses to
find packages (like CMAKE_PREFIX_PATH, CMAKE_FIND_ROOT_PATH) will be
recorded before each find_package / find_dependency call that is
executed in any of the Qt package files.

If any find_package call fails (a package has its _FOUND variable set
to 0), the values of all those recorded variables will be shown.

This is useful to troubleshoot issues, especially when
cross-compiling, without having to manually modify the various
Config files.

Pick-to: 6.4
Task-number: QTBUG-104998
Change-Id: I3654960597911bd704fbe3c419bcae347ab739a9
Reviewed-by: Alexey Edelev <alexey.edelev@qt.io>

cmake/QtConfig.cmake.in

@@ -151,7 +151,7 @@ include(CMakeFindDependencyMacro)
 if(EXISTS "${CMAKE_CURRENT_LIST_DIR}/@INSTALL_CMAKE_NAMESPACE@Dependencies.cmake")
     include("${CMAKE_CURRENT_LIST_DIR}/@INSTALL_CMAKE_NAMESPACE@Dependencies.cmake")
 
-    _qt_internal_suggest_dependency_debugging(
+    _qt_internal_suggest_dependency_debugging(@INSTALL_CMAKE_NAMESPACE@
         __qt_@INSTALL_CMAKE_NAMESPACE@_pkg ${CMAKE_FIND_PACKAGE_NAME}_NOT_FOUND_MESSAGE)
 
     if(NOT @INSTALL_CMAKE_NAMESPACE@_FOUND)
@@ -191,6 +191,8 @@ foreach(module ${@INSTALL_CMAKE_NAMESPACE@_FIND_COMPONENTS})
             ${_qt_additional_host_packages_root_paths})
     endif()
 
+    _qt_internal_save_find_package_context_for_debugging(@INSTALL_CMAKE_NAMESPACE@${module})
+
     find_package(@INSTALL_CMAKE_NAMESPACE@${module}
         ${@INSTALL_CMAKE_NAMESPACE@_FIND_VERSION}
         ${_@INSTALL_CMAKE_NAMESPACE@_FIND_PARTS_QUIET}
@@ -242,7 +244,8 @@ foreach(module ${@INSTALL_CMAKE_NAMESPACE@_FIND_COMPONENTS})
             set(_Qt_NOTFOUND_MESSAGE
                 "${_Qt_NOTFOUND_MESSAGE}Failed to find required Qt component \"${module}\". ${_qt_component_not_found_msg}")
             set(_qt_full_component_name "@INSTALL_CMAKE_NAMESPACE@${module}")
-            _qt_internal_suggest_dependency_debugging(_qt_full_component_name _Qt_NOTFOUND_MESSAGE)
+            _qt_internal_suggest_dependency_debugging(${_qt_full_component_name}
+                _qt_full_component_name _Qt_NOTFOUND_MESSAGE)
             unset(_qt_full_component_name)
             break()
         elseif(NOT @INSTALL_CMAKE_NAMESPACE@_FIND_QUIETLY)

cmake/QtModuleConfig.cmake.in

@@ -14,7 +14,7 @@ get_filename_component(_import_prefix "${_import_prefix}" REALPATH)
 # Find required dependencies, if any.
 if(EXISTS "${CMAKE_CURRENT_LIST_DIR}/@INSTALL_CMAKE_NAMESPACE@@target@Dependencies.cmake")
     include("${CMAKE_CURRENT_LIST_DIR}/@INSTALL_CMAKE_NAMESPACE@@target@Dependencies.cmake")
-    _qt_internal_suggest_dependency_debugging(
+    _qt_internal_suggest_dependency_debugging(@target@
         __qt_@target@_pkg ${CMAKE_FIND_PACKAGE_NAME}_NOT_FOUND_MESSAGE)
 endif()
 

cmake/QtPublicDependencyHelpers.cmake

@@ -22,6 +22,8 @@ macro(_qt_internal_find_third_party_dependencies target target_dep_list)
                  OPTIONAL_COMPONENTS ${__qt_${target}_optional_components})
         endif()
 
+        _qt_internal_save_find_package_context_for_debugging(${target})
+
         if(__qt_${target}_is_optional)
             if(${CMAKE_FIND_PACKAGE_NAME}_FIND_QUIETLY)
                 list(APPEND __qt_${target}_find_package_args QUIET)
@@ -54,6 +56,9 @@ macro(_qt_internal_find_tool_dependencies target target_dep_list)
         if(${CMAKE_FIND_PACKAGE_NAME}_FIND_QUIETLY)
             list(APPEND __qt_${target}_find_package_args QUIET)
         endif()
+
+        _qt_internal_save_find_package_context_for_debugging(${target})
+
         find_package(${__qt_${target}_pkg}
             ${__qt_${target}_version}
             ${__qt_${target}_find_package_args}
@@ -93,6 +98,9 @@ macro(_qt_internal_find_qt_dependencies target target_dep_list find_dependency_p
             if(__qt_${target}_pkg MATCHES "(.*)Private$")
                 set(__qt_${target}_pkg_names "${CMAKE_MATCH_1};${__qt_${target}_pkg}")
             endif()
+
+            _qt_internal_save_find_package_context_for_debugging(${target})
+
             find_dependency(${__qt_${target}_pkg} ${__qt_${target}_version}
                 NAMES
                     ${__qt_${target}_pkg_names}
@@ -117,14 +125,19 @@ endmacro()
 
 # If a dependency package was not found, provide some hints in the error message on how to debug
 # the issue.
+#
 # pkg_name_var should be the variable name that contains the package that was not found.
 # e.g. __qt_Core_pkg
+#
 # message_out_var should contain the variable name of the  original "not found" message, and it
 # will have the hints appended to it as a string. e.g. ${CMAKE_FIND_PACKAGE_NAME}_NOT_FOUND_MESSAGE
 #
+# infix is used as a unique prefix to retrieve the find_package paths context for the last package
+# that was not found, for debugging purposes.
+#
 # The function should not be called in Dependencies.cmake files directly, because find_dependency
 # returns out of the included file.
-macro(_qt_internal_suggest_dependency_debugging pkg_name_var message_out_var)
+macro(_qt_internal_suggest_dependency_debugging infix pkg_name_var message_out_var)
     if(${pkg_name_var}
         AND NOT ${CMAKE_FIND_PACKAGE_NAME}_FOUND
         AND ${message_out_var})
@@ -137,5 +150,44 @@ details why the package was not found.")
                 "\nConfiguring with -DCMAKE_FIND_DEBUG_MODE=TRUE might reveal \
 details why the package was not found.")
         endif()
+
+        if(NOT QT_DEBUG_FIND_PACKAGE)
+            string(APPEND ${message_out_var}
+                "\nConfiguring with -DQT_DEBUG_FIND_PACKAGE=ON will print the values of some of \
+the path variables that find_package uses to try and find the package.")
+        else()
+            string(APPEND ${message_out_var}
+                "\n find_package search path values and other context for the last package that was not found:"
+                "\n  CMAKE_MODULE_PATH: ${_qt_${infix}_CMAKE_MODULE_PATH}"
+                "\n  CMAKE_PREFIX_PATH: ${_qt_${infix}_CMAKE_PREFIX_PATH}"
+                "\n  \$ENV{CMAKE_PREFIX_PATH}: $ENV{CMAKE_PREFIX_PATH}"
+                "\n  CMAKE_FIND_ROOT_PATH: ${_qt_${infix}_CMAKE_FIND_ROOT_PATH}"
+                "\n  _qt_additional_packages_prefix_paths: ${_qt_${infix}_qt_additional_packages_prefix_paths}"
+                "\n  _qt_additional_host_packages_prefix_paths: ${_qt_${infix}_qt_additional_host_packages_prefix_paths}"
+                "\n  _qt_cmake_dir: ${_qt_${infix}_qt_cmake_dir}"
+                "\n  QT_HOST_PATH: ${QT_HOST_PATH}"
+                "\n  Qt6HostInfo_DIR: ${Qt6HostInfo_DIR}"
+                "\n  Qt6_DIR: ${Qt6_DIR}"
+                "\n  CMAKE_TOOLCHAIN_FILE: ${CMAKE_TOOLCHAIN_FILE}"
+                "\n  CMAKE_FIND_ROOT_PATH_MODE_PACKAGE: ${CMAKE_FIND_ROOT_PATH_MODE_PACKAGE}"
+                "\n  CMAKE_SYSROOT: ${CMAKE_SYSROOT}"
+                "\n  \$ENV{PATH}: $ENV{PATH}"
+            )
+        endif()
+    endif()
+endmacro()
+
+# Save find_package search paths context just before a find_package call, to be shown with a
+# package not found message.
+macro(_qt_internal_save_find_package_context_for_debugging infix)
+    if(QT_DEBUG_FIND_PACKAGE)
+        set(_qt_${infix}_CMAKE_MODULE_PATH "${CMAKE_MODULE_PATH}")
+        set(_qt_${infix}_CMAKE_PREFIX_PATH "${CMAKE_PREFIX_PATH}")
+        set(_qt_${infix}_CMAKE_FIND_ROOT_PATH "${CMAKE_FIND_ROOT_PATH}")
+        set(_qt_${infix}_qt_additional_packages_prefix_paths
+            "${_qt_additional_packages_prefix_paths}")
+        set(_qt_${infix}_qt_additional_host_packages_prefix_paths
+            "${_qt_additional_host_packages_prefix_paths}")
+        set(_qt_${infix}_qt_cmake_dir "${_qt_cmake_dir}")
     endif()
 endmacro()