FindBoost: Add policy to remove this module

Upstream Boost 1.70 and above provide a proper `BoostConfig.cmake`
package configuration file.  Packages for all major distros now
provide it in at least one LTS release.  Add a policy to pretend
that the `FindBoost` module does not exist so that projects calling
`find_package(Boost)` use the upstream package directly.

Closes: #19402

Help/manual/cmake-policies.7.rst

@@ -57,6 +57,7 @@ Policies Introduced by CMake 3.30
 .. toctree::
    :maxdepth: 1
 
+   CMP0167: The FindBoost module is removed. </policy/CMP0167>
    CMP0166: TARGET_PROPERTY evaluates link properties transitively over private dependencies of static libraries. </policy/CMP0166>
    CMP0165: enable_language() must not be called before project(). </policy/CMP0165>
    CMP0164: add_library() rejects SHARED libraries when not supported by the platform. </policy/CMP0164>

Help/policy/CMP0167.rst

@@ -0,0 +1,28 @@
+CMP0167
+-------
+
+.. versionadded:: 3.30
+
+The :module:`FindBoost` module is removed.
+
+CMake 3.29 and below provide a ``FindBoost`` module, but it needs constant
+updates to keep up with upstream Boost releases.  Upstream Boost 1.70
+and above provide a ``BoostConfig.cmake`` package configuration file.
+``find_package(Boost CONFIG)`` finds the upstream package directly,
+without the find module.
+
+CMake 3.30 and above prefer to not provide the ``FindBoost`` module
+so that ``find_package(Boost)`` calls, without the ``CONFIG`` or
+``NO_MODULE`` options, find the upstream ``BoostConfig.cmake`` directly.
+This policy provides compatibility for projects that have not been ported
+to use the upstream Boost package.
+
+The ``OLD`` behavior of this policy is for ``find_package(Boost)`` to
+load CMake's :module:`FindBoost` module.  The ``NEW`` behavior is for
+``find_package(Boost)`` to search for the upstream ``BoostConfig.cmake``.
+
+.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.30
+.. |WARNS_OR_DOES_NOT_WARN| replace:: warns
+.. include:: STANDARD_ADVICE.txt
+
+.. include:: DEPRECATED.txt

Help/release/dev/FindBoost-remove.rst

@@ -0,0 +1,6 @@
+FindBoost-remove
+-----------------
+
+* The :module:`FindBoost` module has been removed by policy :policy:`CMP0167`.
+  Port projects to upstream Boost's ``BoostConfig.cmake`` package
+  configuration file, for which ``find_package(Boost)`` now searches.

Modules/FindBoost.cmake

@@ -5,6 +5,11 @@
 FindBoost
 ---------
 
+.. versionchanged:: 3.30
+  This module is available only if policy :policy:`CMP0167` is not set to
+  ``NEW``.  Port projects to upstream Boost's ``BoostConfig.cmake`` package
+  configuration file, for which ``find_package(Boost)`` now searches.
+
 Find Boost include dirs and libraries
 
 Use this module by invoking :command:`find_package` with the form:
@@ -379,6 +384,16 @@ the Boost CMake package configuration for details on what it provides.
 Set ``Boost_NO_BOOST_CMAKE`` to ``ON``, to disable the search for boost-cmake.
 #]=======================================================================]
 
+cmake_policy(GET CMP0167 _FindBoost_CMP0167)
+if(_FindBoost_CMP0167 STREQUAL "NEW")
+  message(FATAL_ERROR "The FindBoost module has been removed by policy CMP0167.")
+endif()
+
+if(_FindBoost_testing)
+  set(_FindBoost_included TRUE)
+  return()
+endif()
+
 # The FPHSA helper provides standard way of reporting final search results to
 # the user including the version and component checks.
 include(${CMAKE_CURRENT_LIST_DIR}/FindPackageHandleStandardArgs.cmake)

Source/cmFindPackageCommand.cxx

@@ -547,6 +547,7 @@ cmFindPackageCommand::cmFindPackageCommand(cmExecutionStatus& status)
   this->DebugMode = false;
   this->AppendSearchPathGroups();
 
+  this->DeprecatedFindModules["Boost"] = cmPolicies::CMP0167;
   this->DeprecatedFindModules["CUDA"] = cmPolicies::CMP0146;
   this->DeprecatedFindModules["Dart"] = cmPolicies::CMP0145;
   this->DeprecatedFindModules["PythonInterp"] = cmPolicies::CMP0148;

Source/cmIncludeCommand.cxx

@@ -22,6 +22,7 @@ bool cmIncludeCommand(std::vector<std::string> const& args,
   if (DeprecatedModules.empty()) {
     DeprecatedModules["Dart"] = cmPolicies::CMP0145;
     DeprecatedModules["Documentation"] = cmPolicies::CMP0106;
+    DeprecatedModules["FindBoost"] = cmPolicies::CMP0167;
     DeprecatedModules["FindCUDA"] = cmPolicies::CMP0146;
     DeprecatedModules["FindDart"] = cmPolicies::CMP0145;
     DeprecatedModules["FindPythonInterp"] = cmPolicies::CMP0148;

Source/cmPolicies.h

@@ -512,7 +512,9 @@ class cmMakefile;
   SELECT(POLICY, CMP0166,                                                     \
          "TARGET_PROPERTY evaluates link properties transitively over "       \
          "private dependencies of static libraries.",                         \
-         3, 30, 0, cmPolicies::WARN)
+         3, 30, 0, cmPolicies::WARN)                                          \
+  SELECT(POLICY, CMP0167, "The FindBoost module is removed.", 3, 30, 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/FindBoost/CMakeLists.txt

@@ -1,3 +1,4 @@
 cmake_minimum_required(VERSION 3.9)
+cmake_policy(SET CMP0167 OLD) # This test covers FindBoost
 project(${RunCMake_TEST} NONE)
 include(${RunCMake_TEST}.cmake)

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

@@ -0,0 +1,4 @@
+^CMake Warning at CMP0167-NEW\.cmake:[0-9]+ \(find_package\):
+  No "FindBoost\.cmake" found in CMAKE_MODULE_PATH\.
+Call Stack \(most recent call first\):
+  CMakeLists\.txt:[0-9]+ \(include\)

Tests/RunCMake/find_package/CMP0167-NEW.cmake

@@ -0,0 +1,7 @@
+cmake_policy(SET CMP0167 NEW)
+set(_FindBoost_testing TRUE)
+find_package(Boost MODULE)
+
+if(_FindBoost_included)
+  message(FATAL_ERROR "FindBoost.cmake erroneously included")
+endif()

Tests/RunCMake/find_package/CMP0167-OLD.cmake

@@ -0,0 +1,7 @@
+cmake_policy(SET CMP0167 OLD)
+set(_FindBoost_testing TRUE)
+find_package(Boost MODULE)
+
+if(NOT _FindBoost_included)
+  message(FATAL_ERROR "FindBoost.cmake not included")
+endif()

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

@@ -0,0 +1,8 @@
+CMake Warning \(dev\) at CMP0167-WARN\.cmake:[0-9]+ \(find_package\):
+  Policy CMP0167 is not set: The FindBoost module is removed\.  Run "cmake
+  --help-policy CMP0167" 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/CMP0167-WARN.cmake

@@ -0,0 +1,6 @@
+set(_FindBoost_testing TRUE)
+find_package(Boost MODULE)
+
+if(NOT _FindBoost_included)
+  message(FATAL_ERROR "FindBoost.cmake not included")
+endif()

Tests/RunCMake/find_package/RunCMakeTest.cmake

@@ -53,6 +53,9 @@ run_cmake(CMP0148-Interp-NEW)
 run_cmake(CMP0148-Libs-OLD)
 run_cmake(CMP0148-Libs-WARN)
 run_cmake(CMP0148-Libs-NEW)
+run_cmake(CMP0167-OLD)
+run_cmake(CMP0167-WARN)
+run_cmake(CMP0167-NEW)
 run_cmake(WrongVersionRange)
 run_cmake(EmptyVersionRange)
 run_cmake(VersionRangeWithEXACT)

Tests/RunCMake/include/CMP0167-NEW-name-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/include/CMP0167-NEW-name-stderr.txt

@@ -0,0 +1,6 @@
+^CMake Error at CMP0167-NEW-name\.cmake:[0-9]+ \(include\):
+  include could not find requested file:
+
+    FindBoost
+Call Stack \(most recent call first\):
+  CMakeLists\.txt:[0-9]+ \(include\)$

Tests/RunCMake/include/CMP0167-NEW-name.cmake

@@ -0,0 +1,2 @@
+cmake_policy(SET CMP0167 NEW)
+include(FindBoost)

Tests/RunCMake/include/CMP0167-NEW-path-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/include/CMP0167-NEW-path-stderr.txt

@@ -0,0 +1,6 @@
+^CMake Error at [^
+]*/Modules/FindBoost.cmake:[0-9]+ \(message\):
+  The FindBoost module has been removed by policy CMP0167\.
+Call Stack \(most recent call first\):
+  CMP0167-NEW-path\.cmake:[0-9]+ \(include\)
+  CMakeLists\.txt:[0-9]+ \(include\)$

Tests/RunCMake/include/CMP0167-NEW-path.cmake

@@ -0,0 +1,2 @@
+cmake_policy(SET CMP0167 NEW)
+include(${CMAKE_ROOT}/Modules/FindBoost.cmake)

Tests/RunCMake/include/CMP0167-OLD.cmake

@@ -0,0 +1,7 @@
+cmake_policy(SET CMP0167 OLD)
+set(_FindBoost_testing 1)
+include(FindBoost)
+
+if(NOT _FindBoost_included)
+  message(FATAL_ERROR "FindBoost.cmake not included")
+endif()

Tests/RunCMake/include/CMP0167-WARN-stderr.txt

@@ -0,0 +1,8 @@
+^CMake Warning \(dev\) at CMP0167-WARN\.cmake:[0-9]+ \(include\):
+  Policy CMP0167 is not set: The FindBoost module is removed\.  Run "cmake
+  --help-policy CMP0167" 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/include/CMP0167-WARN.cmake

@@ -0,0 +1,7 @@
+# Do not set CMP0167.
+set(_FindBoost_testing 1)
+include(FindBoost)
+
+if(NOT _FindBoost_included)
+  message(FATAL_ERROR "FindBoost.cmake not included")
+endif()

Tests/RunCMake/include/RunCMakeTest.cmake

@@ -21,3 +21,8 @@ run_cmake(CMP0148-Libs-OLD)
 run_cmake(CMP0148-Libs-WARN)
 run_cmake(CMP0148-Libs-NEW-name)
 run_cmake(CMP0148-Libs-NEW-path)
+
+run_cmake(CMP0167-OLD)
+run_cmake(CMP0167-WARN)
+run_cmake(CMP0167-NEW-name)
+run_cmake(CMP0167-NEW-path)