CMake: Warn if cmake_minimum_required has an unsupported low version

Qt6Config.cmake calls cmake_minimum_required to ensure a recent enough
CMake version is used in projects.

That call does not set policies in the calling subdirectory scope,
because find_package introduces a new policy scope.

If a project using Qt has a 'cmake_minimum_required(VERSION 3.1)'
call and is configured with a recent CMake, many policies will
still be set to OLD.

One such policy is CMP0071 (Run AUTOMOC on GENERATED files). The
policy value is queried at generation time rather than at target
definition time, which means we can't influence the policy value
(e.g. inside the implementation of qt_add_executable for example)

The inability to influence the policy value for targets created by our
own CMake functions is unfortunate and can lead to issues (in the case
of the above policy to compilation / linker issues).

Record the version of the last cmake_minimum_required call before
the Qt packages are found and error out if the version is lower than
the minimum supported one.

A project can reduce the error into a warning by specifying a
-DQT_FORCE_MIN_CMAKE_VERSION_FOR_USING_QT_IN_CMAKE_MIN_REQUIRED=3.xyz
option when configuring the project.
If the option is used and build issues arise, no official support is
given.

All the CMake example projects shipped with Qt specify a minimum
version of 3.16 already (which is the minimum for shared Qt builds),
so it shouldn't be an issue to require that in other user projects as
well.

Implementation wise, we follow the existing pattern to record
what the minimum and computed versions for static and shared Qt
builds are at qtbase configure time.
These are then checked before the Qt6 or QtFoo packages are
find_package'd.

Amends 6518bcc167d47e1c27d082c21551b9a838b04e5d

Pick-to: 6.2
Task-number: QTBUG-95018
Task-number: QTBUG-95832
Change-Id: I1a1d06d82f566c92192a699045127943604c8353
Reviewed-by: Craig Scott <craig.scott@qt.io>
Reviewed-by: Qt CI Bot <qt_ci_bot@qt-project.org>

6 files changed, 114 insertions, 0 deletions

diff --git a/cmake/QtBaseGlobalTargets.cmake b/cmake/QtBaseGlobalTargets.cmake
index dd7ceecb35..1b7f8d8aa2 100644
--- a/cmake/QtBaseGlobalTargets.cmake
+++ b/cmake/QtBaseGlobalTargets.cmake
@@ -153,6 +153,13 @@ qt_internal_export_modern_cmake_config_targets_file(TARGETS ${__export_targets}
 qt_internal_get_supported_min_cmake_version_for_using_qt(supported_min_version_for_using_qt)
 qt_internal_get_computed_min_cmake_version_for_using_qt(computed_min_version_for_using_qt)
 
+# Save the minimum required CMake version to use Qt that should appear in a project's
+# cmake_minimum_required() call.
+qt_internal_get_supported_min_cmake_version_for_using_qt_in_cmake_min_required(
+    supported_min_version_for_using_qt_in_cmake_min_required)
+qt_internal_get_computed_min_cmake_version_for_using_qt_in_cmake_min_required(
+    computed_min_version_for_using_qt_in_cmake_min_required)
+
 # Get the lower and upper policy range to embed into the Qt6 config file.
 qt_internal_get_min_new_policy_cmake_version(min_new_policy_version)
 qt_internal_get_max_new_policy_cmake_version(max_new_policy_version)
diff --git a/cmake/QtCMakeVersionHelpers.cmake b/cmake/QtCMakeVersionHelpers.cmake
index a42e1a523f..52f65ebc12 100644
--- a/cmake/QtCMakeVersionHelpers.cmake
+++ b/cmake/QtCMakeVersionHelpers.cmake
@@ -36,6 +36,25 @@ function(qt_internal_get_supported_min_cmake_version_for_using_qt out_var)
     set(${out_var} "${supported_version}" PARENT_SCOPE)
 endfunction()
 
+# Returns the minimum CMake version that needs to be specified in the cmake_minimum_required() call
+# of a Qt user project as originally advertised by Qt.
+function(qt_internal_get_supported_min_cmake_version_for_using_qt_in_cmake_min_required out_var)
+    if(NOT DEFINED BUILD_SHARED_LIBS)
+        message(FATAL_ERROR "BUILD_SHARED_LIBS is needed to decide the minimum CMake version. "
+            "It should have been set by this point.")
+    endif()
+
+    if(BUILD_SHARED_LIBS)
+        set(supported_version
+            "${QT_SUPPORTED_MIN_CMAKE_VERSION_FOR_USING_QT_SHARED_IN_CMAKE_MIN_REQUIRED}")
+    else()
+        set(supported_version
+            "${QT_SUPPORTED_MIN_CMAKE_VERSION_FOR_USING_QT_STATIC_IN_CMAKE_MIN_REQUIRED}")
+    endif()
+
+    set(${out_var} "${supported_version}" PARENT_SCOPE)
+endfunction()
+
 # Returns the computed minimum supported CMake version required to /build/ Qt.
 function(qt_internal_get_computed_min_cmake_version_for_building_qt out_var)
     # An explicit override for those that take it upon themselves to fix the build system
@@ -74,6 +93,23 @@ function(qt_internal_get_computed_min_cmake_version_for_using_qt out_var)
     set(${out_var} "${computed_min_version}" PARENT_SCOPE)
 endfunction()
 
+# Returns the computed minimum CMake version that needs to be specified in the
+# cmake_minimum_required() call of a Qt user project.
+function(qt_internal_get_computed_min_cmake_version_for_using_qt_in_cmake_min_required out_var)
+    # Allow overriding the version for user projects, without forcing
+    # each project developer to have to override it manually.
+    if(QT_FORCE_MIN_CMAKE_VERSION_FOR_USING_QT_IN_CMAKE_MIN_REQUIRED)
+        set(computed_min_version "${QT_FORCE_MIN_CMAKE_VERSION_FOR_USING_QT_IN_CMAKE_MIN_REQUIRED}")
+
+    # No override was given, thus initialize with the default minimum.
+    else()
+        qt_internal_get_supported_min_cmake_version_for_using_qt_in_cmake_min_required(
+            min_supported_version)
+        set(computed_min_version "${min_supported_version}")
+    endif()
+    set(${out_var} "${computed_min_version}" PARENT_SCOPE)
+endfunction()
+
 # Returns the oldest CMake version for which NEW policies should be enabled.
 # It can be older than the minimum supported or computed CMake version, as it
 # is only used for policy settings. The currently running CMake must not be
diff --git a/cmake/QtConfig.cmake.in b/cmake/QtConfig.cmake.in
index 75e15226dd..8b455b0bb6 100644
--- a/cmake/QtConfig.cmake.in
+++ b/cmake/QtConfig.cmake.in
@@ -1,5 +1,9 @@
 @PACKAGE_INIT@
 
+# Used by __qt_internal_warn_if_project_min_cmake_version_is_not_met
+if(NOT _qt_project_last_cmake_minimum_required_version)
+    set(_qt_project_last_cmake_minimum_required_version "${CMAKE_MINIMUM_REQUIRED_VERSION}")
+endif()
 cmake_minimum_required(VERSION @min_new_policy_version@...@max_new_policy_version@)
 
 include("${CMAKE_CURRENT_LIST_DIR}/@INSTALL_CMAKE_NAMESPACE@ConfigExtras.cmake")
diff --git a/cmake/QtConfigExtras.cmake.in b/cmake/QtConfigExtras.cmake.in
index bde3460cdc..627d326569 100644
--- a/cmake/QtConfigExtras.cmake.in
+++ b/cmake/QtConfigExtras.cmake.in
@@ -1,2 +1,7 @@
 set(QT_SUPPORTED_MIN_CMAKE_VERSION_FOR_USING_QT "@supported_min_version_for_using_qt@")
 set(QT_COMPUTED_MIN_CMAKE_VERSION_FOR_USING_QT "@computed_min_version_for_using_qt@")
+
+set(QT_SUPPORTED_MIN_CMAKE_VERSION_FOR_USING_QT_IN_CMAKE_MIN_REQUIRED
+    "@supported_min_version_for_using_qt_in_cmake_min_required@")
+set(QT_COMPUTED_MIN_CMAKE_VERSION_FOR_USING_QT_IN_CMAKE_MIN_REQUIRED
+    "@computed_min_version_for_using_qt_in_cmake_min_required@")
diff --git a/cmake/QtModuleConfig.cmake.in b/cmake/QtModuleConfig.cmake.in
index 76fde2dc1f..66e90fc6b1 100644
--- a/cmake/QtModuleConfig.cmake.in
+++ b/cmake/QtModuleConfig.cmake.in
@@ -1,5 +1,9 @@
 @PACKAGE_INIT@
 
+# Used by __qt_internal_warn_if_project_min_cmake_version_is_not_met
+if(NOT _qt_project_last_cmake_minimum_required_version)
+    set(_qt_project_last_cmake_minimum_required_version "${CMAKE_MINIMUM_REQUIRED_VERSION}")
+endif()
 cmake_minimum_required(VERSION @min_new_policy_version@...@max_new_policy_version@)
 
 include(CMakeFindDependencyMacro)
diff --git a/cmake/QtPublicCMakeVersionHelpers.cmake b/cmake/QtPublicCMakeVersionHelpers.cmake
index 2b3c697f4c..638c9edc2d 100644
--- a/cmake/QtPublicCMakeVersionHelpers.cmake
+++ b/cmake/QtPublicCMakeVersionHelpers.cmake
@@ -4,6 +4,12 @@ function(__qt_internal_get_supported_min_cmake_version_for_using_qt out_var)
     set(${out_var} "${supported_version}" PARENT_SCOPE)
 endfunction()
 
+function(__qt_internal_get_supported_min_cmake_version_for_using_qt_in_cmake_min_required out_var)
+    # This is recorded in Qt6ConfigExtras.cmake
+    set(supported_version "${QT_SUPPORTED_MIN_CMAKE_VERSION_FOR_USING_QT_IN_CMAKE_MIN_REQUIRED}")
+    set(${out_var} "${supported_version}" PARENT_SCOPE)
+endfunction()
+
 function(__qt_internal_get_computed_min_cmake_version_for_using_qt out_var)
     # Allow override when configuring user project.
     if(QT_FORCE_MIN_CMAKE_VERSION_FOR_USING_QT)
@@ -20,6 +26,23 @@ function(__qt_internal_get_computed_min_cmake_version_for_using_qt out_var)
     set(${out_var} "${computed_min_version}" PARENT_SCOPE)
 endfunction()
 
+function(__qt_internal_get_computed_min_cmake_version_for_using_qt_in_cmake_min_required out_var)
+    # Allow override when configuring user project.
+    if(QT_FORCE_MIN_CMAKE_VERSION_FOR_USING_QT_IN_CMAKE_MIN_REQUIRED)
+        set(computed_min_version "${QT_FORCE_MIN_CMAKE_VERSION_FOR_USING_QT_IN_CMAKE_MIN_REQUIRED}")
+
+    # Set in QtConfigExtras.cmake.
+    elseif(QT_COMPUTED_MIN_CMAKE_VERSION_FOR_USING_QT_IN_CMAKE_MIN_REQUIRED)
+        set(computed_min_version
+            "${QT_COMPUTED_MIN_CMAKE_VERSION_FOR_USING_QT_IN_CMAKE_MIN_REQUIRED}")
+    else()
+        message(FATAL_ERROR
+            "Qt Developer error: Can't compute the version that should appear in cmake_minimum_required to use this Qt.")
+    endif()
+
+    set(${out_var} "${computed_min_version}" PARENT_SCOPE)
+endfunction()
+
 function(__qt_internal_warn_if_min_cmake_version_not_met)
     __qt_internal_get_supported_min_cmake_version_for_using_qt(min_supported_version)
     __qt_internal_get_computed_min_cmake_version_for_using_qt(computed_min_version)
@@ -34,6 +57,22 @@ function(__qt_internal_warn_if_min_cmake_version_not_met)
     endif()
 endfunction()
 
+function(__qt_internal_warn_if_project_min_cmake_version_is_not_met)
+    __qt_internal_get_supported_min_cmake_version_for_using_qt_in_cmake_min_required(
+        min_supported_version)
+    __qt_internal_get_computed_min_cmake_version_for_using_qt_in_cmake_min_required(
+        computed_min_version)
+
+    if(computed_min_version VERSION_LESS min_supported_version)
+        message(WARNING
+           "To use this Qt, the minimum CMake version that should appear in the project's "
+           "cmake_minimum_required() call should be: '${min_supported_version}'. "
+           "You have explicitly chosen to require a lower version: '${computed_min_version}'. "
+           "Using Qt with this version is not officially supported. Use at your own risk."
+        )
+    endif()
+endfunction()
+
 function(__qt_internal_require_suitable_cmake_version_for_using_qt)
     # Skip the public project check if we're building a Qt repo because it's too early to do
     # it at find_package(Qt6) time.
@@ -66,4 +105,23 @@ function(__qt_internal_require_suitable_cmake_version_for_using_qt)
             "project. Using Qt with this CMake version is not officially supported. "
             "Use at your own risk.")
     endif()
+
+
+    # Check that the project has a supported version specified in the last cmake_minimum_required
+    # call before the Qt6 package was found.
+    __qt_internal_warn_if_project_min_cmake_version_is_not_met()
+    __qt_internal_get_computed_min_cmake_version_for_using_qt_in_cmake_min_required(
+        computed_min_version)
+
+    if(_qt_project_last_cmake_minimum_required_version VERSION_LESS computed_min_version)
+        message(FATAL_ERROR
+            "The last cmake_minimum_required() call before the Qt package was found had the "
+            "following version specified: '${_qt_project_last_cmake_minimum_required_version}' but "
+            "it needs to be ${computed_min_version} or higher to use Qt. "
+            "You can reduce the error into a warning by passing "
+            "-DQT_FORCE_MIN_CMAKE_VERSION_FOR_USING_QT_IN_CMAKE_MIN_REQUIRED=${_qt_project_last_cmake_minimum_required_version} "
+            "when configuring the project, but you do so at your own risk (it is not an officially "
+            "supported way of building Qt projects)."
+        )
+    endif()
 endfunction()