find_package(): Add policy to remove the FindQt module

Removing FindQt.cmake gives Qt upstream a path forward to export its
own QtConfig.cmake files which can be found by find_package()
without having to explicitly specify CONFIG. Projects that still
want to use Qt3/4 can call find_package(Qt[34]), include(FindQt),
or add FindQt.cmake to their CMAKE_MODULE_PATH.

Help/manual/cmake-modules.7.rst

@@ -225,7 +225,6 @@ They are normally called through the :command:`find_package` command.
    /module/FindPython3
    /module/FindQt3
    /module/FindQt4
-   /module/FindQt
    /module/FindQuickTime
    /module/FindRTI
    /module/FindRuby
@@ -283,6 +282,7 @@ Deprecated Find Modules
    /module/FindCUDA
    /module/FindPythonInterp
    /module/FindPythonLibs
+   /module/FindQt
    /module/FindwxWindows
 
 Legacy CPack Modules

Help/manual/cmake-policies.7.rst

@@ -57,6 +57,7 @@ Policies Introduced by CMake 3.14
 .. toctree::
    :maxdepth: 1
 
+   CMP0084: The FindQt module does not exist for find_package(). </policy/CMP0084>
    CMP0083: Add PIE options when linking executable. </policy/CMP0083>
    CMP0082: Install rules from add_subdirectory() are interleaved with those in caller. </policy/CMP0082>
 

Help/policy/CMP0084.rst

@@ -0,0 +1,26 @@
+CMP0084
+-------
+
+The :module:`FindQt` module does not exist for :command:`find_package`.
+
+The existence of :module:`FindQt` means that for Qt upstream to provide
+package config files that can be found by ``find_package(Qt)``, the consuming
+project has to explicitly specify ``find_package(Qt CONFIG)``. Removing this
+module gives Qt a path forward for exporting its own config files which can
+easily be found by consuming projects.
+
+This policy pretends that CMake's internal :module:`FindQt` module does not
+exist for :command:`find_package`. If a project really wants to use Qt 3 or 4,
+it can call ``find_package(Qt[34])``, ``include(FindQt)``, or add
+:module:`FindQt` to their :variable:`CMAKE_MODULE_PATH`.
+
+The ``OLD`` behavior of this policy is for :module:`FindQt` to exist for
+:command:`find_package`. The ``NEW`` behavior is to pretend that it doesn't
+exist for :command:`find_package`.
+
+This policy was introduced in CMake version 3.14.  CMake version
+|release| warns when the policy is not set and uses ``OLD`` behavior.
+Use the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW``
+explicitly.
+
+.. include:: DEPRECATED.txt

Help/release/dev/deprecate-findqt.rst

@@ -0,0 +1,8 @@
+deprecate-findqt
+----------------
+
+* The :module:`FindQt` module is no longer used by the :command:`find_package`
+  command as a find module.  This allows the Qt Project upstream to optionally
+  provide its own ``QtConfig.cmake`` package configuration file and have
+  applications use it via ``find_package(Qt)`` rather than
+  ``find_package(Qt CONFIG)``.  See policy :policy:`CMP0084`.

Modules/FindQt.cmake

@@ -10,6 +10,9 @@ Searches for all installed versions of Qt3 or Qt4.
 This module cannot handle Qt5 or any later versions.
 For those, see :manual:`cmake-qt(7)`.
 
+This module exists for the :command:`find_package` command only if
+policy :policy:`CMP0084` is not set to ``NEW``.
+
 This module should only be used if your project can work with multiple
 versions of Qt.  If not, you should just directly use FindQt4 or
 FindQt3.  If multiple versions of Qt are found on the machine, then
@@ -34,6 +37,11 @@ then the FindQt3 or FindQt4 module is included.
   QT3_INSTALLED is set to TRUE if qt3 is found.
 #]=======================================================================]
 
+if(_findqt_testing)
+  set(_findqt_included TRUE)
+  return()
+endif()
+
 # look for signs of qt3 installations
 file(GLOB GLOB_TEMP_VAR /usr/lib*/qt-3*/bin/qmake /usr/lib*/qt3*/bin/qmake)
 if(GLOB_TEMP_VAR)

Source/cmFindPackageCommand.cxx

@@ -111,6 +111,8 @@ cmFindPackageCommand::cmFindPackageCommand()
   this->SortOrder = None;
   this->SortDirection = Asc;
   this->AppendSearchPathGroups();
+
+  this->DeprecatedFindModules["Qt"] = cmPolicies::CMP0084;
 }
 
 void cmFindPackageCommand::AppendSearchPathGroups()
@@ -653,8 +655,31 @@ bool cmFindPackageCommand::FindModule(bool& found)
   std::string module = "Find";
   module += this->Name;
   module += ".cmake";
-  std::string mfile = this->Makefile->GetModulesFile(module.c_str());
+  bool system = false;
+  std::string mfile = this->Makefile->GetModulesFile(module.c_str(), system);
   if (!mfile.empty()) {
+    if (system) {
+      auto it = this->DeprecatedFindModules.find(this->Name);
+      if (it != this->DeprecatedFindModules.end()) {
+        cmPolicies::PolicyStatus status =
+          this->Makefile->GetPolicyStatus(it->second);
+        switch (status) {
+          case cmPolicies::WARN: {
+            std::ostringstream e;
+            e << cmPolicies::GetPolicyWarning(it->second) << "\n";
+            this->Makefile->IssueMessage(cmake::AUTHOR_WARNING, e.str());
+            CM_FALLTHROUGH;
+          }
+          case cmPolicies::OLD:
+            break;
+          case cmPolicies::REQUIRED_IF_USED:
+          case cmPolicies::REQUIRED_ALWAYS:
+          case cmPolicies::NEW:
+            return true;
+        }
+      }
+    }
+
     // Load the module we found, and set "<name>_FIND_MODULE" to true
     // while inside it.
     found = true;

Source/cmFindPackageCommand.h

@@ -4,6 +4,7 @@
 #define cmFindPackageCommand_h
 
 #include "cmConfigure.h" // IWYU pragma: keep
+#include "cmPolicies.h"
 
 #include "cm_kwiml.h"
 #include <cstddef>
@@ -148,6 +149,8 @@ private:
   };
   std::map<std::string, OriginalDef> OriginalDefs;
 
+  std::map<std::string, cmPolicies::PolicyID> DeprecatedFindModules;
+
   std::string Name;
   std::string Variable;
   std::string Version;

Source/cmMakefile.cxx

@@ -3500,7 +3500,8 @@ void cmMakefile::DisplayStatus(const char* message, float s) const
   cm->UpdateProgress(message, s);
 }
 
-std::string cmMakefile::GetModulesFile(const char* filename) const
+std::string cmMakefile::GetModulesFile(const char* filename,
+                                       bool& system) const
 {
   std::string result;
 
@@ -3547,8 +3548,10 @@ std::string cmMakefile::GetModulesFile(const char* filename) const
   // Normally, prefer the files found in CMAKE_MODULE_PATH. Only when the file
   // from which we are being called is located itself in CMAKE_ROOT, then
   // prefer results from CMAKE_ROOT depending on the policy setting.
+  system = false;
   result = moduleInCMakeModulePath;
   if (result.empty()) {
+    system = true;
     result = moduleInCMakeRoot;
   }
 
@@ -3571,11 +3574,13 @@ std::string cmMakefile::GetModulesFile(const char* filename) const
           CM_FALLTHROUGH;
         }
         case cmPolicies::OLD:
+          system = false;
           result = moduleInCMakeModulePath;
           break;
         case cmPolicies::REQUIRED_IF_USED:
         case cmPolicies::REQUIRED_ALWAYS:
         case cmPolicies::NEW:
+          system = true;
           result = moduleInCMakeRoot;
           break;
       }

Source/cmMakefile.h

@@ -689,7 +689,13 @@ public:
   /**
    * Return a location of a file in cmake or custom modules directory
    */
-  std::string GetModulesFile(const char* name) const;
+  std::string GetModulesFile(const char* name) const
+  {
+    bool system;
+    return this->GetModulesFile(name, system);
+  }
+
+  std::string GetModulesFile(const char* name, bool& system) const;
 
   ///! Set/Get a property of this directory
   void SetProperty(const std::string& prop, const char* value);

Source/cmPolicies.h

@@ -246,7 +246,10 @@ class cmMakefile;
          "in caller.",                                                        \
          3, 14, 0, cmPolicies::WARN)                                          \
   SELECT(POLICY, CMP0083, "Add PIE options when linking executable.", 3, 14,  \
-         0, cmPolicies::WARN)
+         0, cmPolicies::WARN)                                                 \
+  SELECT(POLICY, CMP0084,                                                     \
+         "The FindQt module does not exist for find_package().", 3, 14, 0,    \
+         cmPolicies::WARN)
 
 #define CM_SELECT_ID(F, A1, A2, A3, A4, A5, A6) F(A1)
 #define CM_FOR_EACH_POLICY_ID(POLICY)                                         \

Tests/RunCMake/find_package/CMP0084-NEW-stderr.txt

@@ -0,0 +1,20 @@
+^CMake Warning at CMP0084-NEW\.cmake:[0-9]+ \(find_package\):
+  No "FindQt\.cmake" found in CMAKE_MODULE_PATH\.
+Call Stack \(most recent call first\):
+  CMakeLists\.txt:3 \(include\)
++
+CMake Warning \(dev\) at CMP0084-NEW\.cmake:[0-9]+ \(find_package\):
+  FindQt\.cmake must either be part of this project itself, in this case
+  adjust CMAKE_MODULE_PATH so that it points to the correct location inside
+  its source tree\.
+
+  Or it must be installed by a package which has already been found via
+  find_package\(\)\.  In this case make sure that package has indeed been found
+  and adjust CMAKE_MODULE_PATH to contain the location where that package has
+  installed FindQt\.cmake\.  This must be a location provided by that package\.
+  This error in general means that the buildsystem of this project is relying
+  on a Find-module without ensuring that it is actually available\.
+
+Call Stack \(most recent call first\):
+  CMakeLists\.txt:[0-9]+ \(include\)
+This warning is for project developers\.  Use -Wno-dev to suppress it\.$

Tests/RunCMake/find_package/CMP0084-NEW.cmake

@@ -0,0 +1,7 @@
+cmake_policy(SET CMP0084 NEW)
+set(_findqt_testing TRUE)
+find_package(Qt MODULE)
+
+if(_findqt_included)
+  message(FATAL_ERROR "FindQt.cmake erroneously included")
+endif()

Tests/RunCMake/find_package/CMP0084-OLD.cmake

@@ -0,0 +1,7 @@
+cmake_policy(SET CMP0084 OLD)
+set(_findqt_testing TRUE)
+find_package(Qt MODULE)
+
+if(NOT _findqt_included)
+  message(FATAL_ERROR "FindQt.cmake not included")
+endif()

Tests/RunCMake/find_package/CMP0084-WARN-stderr.txt

@@ -0,0 +1,8 @@
+^CMake Warning \(dev\) at CMP0084-WARN\.cmake:[0-9]+ \(find_package\):
+  Policy CMP0084 is not set: The FindQt module does not exist for
+  find_package\(\)\.  Run "cmake --help-policy CMP0084" for policy details\.  Use
+  the cmake_policy command to set the policy and suppress this warning\.
+
+Call Stack \(most recent call first\):
+  CMakeLists\.txt:[0-9]+ \(include\)
+This warning is for project developers\.  Use -Wno-dev to suppress it\.$

Tests/RunCMake/find_package/CMP0084-WARN.cmake

@@ -0,0 +1,6 @@
+set(_findqt_testing TRUE)
+find_package(Qt MODULE)
+
+if(NOT _findqt_included)
+  message(FATAL_ERROR "FindQt.cmake not included")
+endif()

Tests/RunCMake/find_package/RunCMakeTest.cmake

@@ -23,3 +23,6 @@ run_cmake(PolicyPop)
 run_cmake(SetFoundFALSE)
 run_cmake(WrongVersion)
 run_cmake(WrongVersionConfig)
+run_cmake(CMP0084-OLD)
+run_cmake(CMP0084-WARN)
+run_cmake(CMP0084-NEW)