CMake: Add qt 'policy' support

This mimics CMake's policy support. The policy state is stored in an
internal __QT_INTERNAL_POLICY_<policy> variable; by using normal
variables, we gain support for stacking for free.
Policies can be explicitly en- or disable via qt6_policy; that command
also has a GET mode to retrieve them again.
Furthermore, one can now pass min and max version to
qt6_standard_project_setup, to opt in to a certain set of defaults
introduced in a given Qt version.

We add support for policies in QtModuleHelpers, so that we can check for
known policies while building Qt itself.

No actual policies exist yet; but a follow up commit will introduce one
for qt_add_qml_module.

Change-Id: I57a0404c9193926dd499f94cc5f73e359355c0b3
Reviewed-by: Marc Mutz <marc.mutz@qt.io>
Reviewed-by: Alexandru Croitor <alexandru.croitor@qt.io>

3 files changed, 69 insertions, 1 deletions

diff --git a/src/corelib/doc/src/cmake/qt_policy.qdoc b/src/corelib/doc/src/cmake/qt_policy.qdoc
new file mode 100644
index 0000000000..11e761b34a
--- /dev/null
+++ b/src/corelib/doc/src/cmake/qt_policy.qdoc
@@ -0,0 +1,49 @@
+// Copyright (C) 2022 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
+
+/*!
+\page qt-policy.html
+\ingroup cmake-commands-qtcore
+
+\summary {Modify the default behavior of Qt's CMake API.}
+
+\include cmake-find-package-core.qdocinc
+
+\cmakecommandsince 6.5
+
+\section1 Synopsis
+
+\badcode
+qt_policy(
+    [SET policy behavior]
+    [GET policy variable]
+)
+\endcode
+
+\versionlessCMakeCommandsNote qt6_policy()
+
+\section1 Description
+This command has two modes:
+\list
+\li When the \c{SET} keyword is used, this command can be used to opt in to
+    behavior changes in Qt's CMake API, or to explicitly opt out of them.
+\li When the \c{GET} keyword is used, \c{variable} is set to the current
+    value for the policy.
+\endlist
+\c{policyname} must be the name of a Qt cmake policy. Using an unknown policy
+is an error; code supporting older Qt versions should check with
+\badcode
+if(QT_KNOWN_POLICY_<policy_name>)
+\endcode
+whether the policy exists before querying or setting it.
+
+\c{behavior} can
+either be
+\list
+\li \c{NEW} to opt into the new behavior, or
+\li \c{OLD} to explicitly opt-out of it.
+\endlist
+
+\sa qt_standard_project_setup
+
+*/
diff --git a/src/corelib/doc/src/cmake/qt_standard_project_setup.qdoc b/src/corelib/doc/src/cmake/qt_standard_project_setup.qdoc
index 6e91779fb9..ad6541f08a 100644
--- a/src/corelib/doc/src/cmake/qt_standard_project_setup.qdoc
+++ b/src/corelib/doc/src/cmake/qt_standard_project_setup.qdoc
@@ -17,7 +17,10 @@
 \section1 Synopsis
 
 \badcode
-qt_standard_project_setup()
+qt_standard_project_setup(
+    [MIN_VERSION policy_min]
+    [MAX_VERSION policy_max]
+)
 \endcode
 
 \versionlessCMakeCommandsNote qt6_standard_project_setup()
@@ -47,6 +50,16 @@ have been defined. It does the following things:
     Qt-internal targets in this folder.
 \endlist
 
+Moreover, since Qt 6.5 it can be used to change the default behavior of Qt's CMake
+API, by opting in to changes from newer Qt versions. If \c{MIN_VERSION} is
+specified, all suggested changes introduced in Qt up to \c{MIN_VERSION} are enabled,
+and using an older Qt version will result in an error.
+If additionally \c{MAX_VERSION} has been specified, any new changes introduced
+in versions up to \c{MAX_VERSION} are also enabled (but using an older Qt
+version is not an error).
+This is similar to CMake's policy concept (compare \l{cmake_policy}).
+
+
 On platforms that support \c{RPATH} (other than Apple platforms), two values
 are appended to the \c{CMAKE_INSTALL_RPATH} variable by this command.
 \c{$ORIGIN} is appended so that libraries will find other libraries they depend
@@ -67,6 +80,7 @@ The \c{qt_standard_project_setup()} command can effectively be disabled by
 setting the \l{QT_NO_STANDARD_PROJECT_SETUP} variable to true.
 
 \sa {qt6_generate_deploy_app_script}{qt_generate_deploy_app_script()}
+\sa {qt6_policy}
 
 \section1 Example
 
diff --git a/src/corelib/doc/src/external-resources.qdoc b/src/corelib/doc/src/external-resources.qdoc
index ecda025820..6faae09b69 100644
--- a/src/corelib/doc/src/external-resources.qdoc
+++ b/src/corelib/doc/src/external-resources.qdoc
@@ -131,3 +131,8 @@
     \externalpage https://cmake.org/cmake/help/latest/prop_tgt/FOLDER.html
     \title FOLDER
 */
+
+/*!
+    \externalpage https://cmake.org/cmake/help/latest/command/cmake_policy.html
+    \title cmake_policy
+*/