CMakeFindFrameworks: Deprecate the module subject to policy CMP0173

Fixes: #20446

Help/manual/cmake-modules.7.rst

@@ -55,7 +55,6 @@ These modules are loaded using the :command:`include` command.
    /module/CMakeBackwardCompatibilityCXX
    /module/CMakeDependentOption
    /module/CMakeFindDependencyMacro
-   /module/CMakeFindFrameworks
    /module/CMakeFindPackageMode
    /module/CMakeGraphVizOptions
    /module/CMakePackageConfigHelpers
@@ -269,6 +268,7 @@ Deprecated Utility Modules
    /module/AddFileDependencies
    /module/CMakeDetermineVSServicePack
    /module/CMakeExpandImportedTargets
+   /module/CMakeFindFrameworks
    /module/CMakeForceCompiler
    /module/CMakeParseArguments
    /module/Dart

Help/manual/cmake-policies.7.rst

@@ -57,6 +57,7 @@ Policies Introduced by CMake 3.31
 .. toctree::
    :maxdepth: 1
 
+   CMP0173: The CMakeFindFrameworks module is removed. </policy/CMP0173>
    CMP0172: The CPack module enables per-machine installation by default in the CPack WIX Generator. </policy/CMP0172>
    CMP0171: 'codegen' is a reserved target name. </policy/CMP0171>
 

Help/policy/CMP0173.rst

@@ -0,0 +1,22 @@
+CMP0173
+-------
+
+.. versionadded:: 3.31
+
+The :module:`CMakeFindFrameworks` module is removed.
+
+CMake's framework handling has evolved well beyond what the
+``CMakeFindFrameworks`` module supports. The module lacks any handling of
+XCFrameworks, it never documented the one command it provides, and
+:command:`find_library` provides superior capabilities in all respects.
+
+The ``OLD`` behavior of this policy is for :module:`CMakeFindFrameworks` to
+continue to provide the undocumented ``cmake_find_frameworks()`` command.
+The ``NEW`` behavior halts with a fatal error if anything tries to include
+the module.
+
+.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.31
+.. |WARNS_OR_DOES_NOT_WARN| replace:: warns
+.. include:: STANDARD_ADVICE.txt
+
+.. include:: DEPRECATED.txt

Help/release/dev/deprecate-CMakeFindFrameworks.rst

@@ -0,0 +1,5 @@
+deprecate-CMakeFindFrameworks
+-----------------------------
+
+* The :module:`CMakeFindFrameworks` module has been deprecated via
+  :policy:`CMP0173`. Projects should use :command:`find_library` instead.

Modules/CMakeFindFrameworks.cmake

@@ -5,6 +5,9 @@
 CMakeFindFrameworks
 -------------------
 
+.. deprecated:: 3.31
+  This module does nothing, unless policy :policy:`CMP0173` is set to ``OLD``.
+
 helper module to find OSX frameworks
 
 This module reads hints about search locations from variables::
@@ -12,6 +15,25 @@ This module reads hints about search locations from variables::
   CMAKE_FIND_FRAMEWORK_EXTRA_LOCATIONS - Extra directories
 #]=======================================================================]
 
+cmake_policy(GET CMP0173 _cmp0173)
+if(_cmp0173 STREQUAL "NEW")
+  message(FATAL_ERROR
+    "CMakeFindFrameworks.cmake is not maintained and lacks support for more "
+    "recent framework handling. It will be removed in a future version of "
+    "CMake. Update the code to use find_library() instead. "
+    "Use of this module is now an error according to policy CMP0173."
+  )
+elseif(_cmp0173 STREQUAL "")
+  # CMake will have already emitted the standard policy warning for the point
+  # of inclusion. We only need to add the context-specific info here.
+  message(AUTHOR_WARNING
+    "CMakeFindFrameworks.cmake is not maintained and lacks support for more "
+    "recent framework handling. It will be removed in a future version of "
+    "CMake. Update the code to use find_library() instead."
+  )
+endif ()
+unset(_cmp0173)
+
 if(NOT CMAKE_FIND_FRAMEWORKS_INCLUDED)
   set(CMAKE_FIND_FRAMEWORKS_INCLUDED 1)
   macro(CMAKE_FIND_FRAMEWORKS fwk)

Modules/FindPythonLibs.cmake

@@ -81,7 +81,10 @@ if(IS_ABSOLUTE "${PYTHON_EXECUTABLE}")
   endif()
 endif()
 
-include(${CMAKE_CURRENT_LIST_DIR}/CMakeFindFrameworks.cmake)
+block(SCOPE_FOR POLICIES)
+  cmake_policy(SET CMP0173 OLD)
+  include(${CMAKE_CURRENT_LIST_DIR}/CMakeFindFrameworks.cmake)
+endblock()
 # Search for the python framework on Apple.
 CMAKE_FIND_FRAMEWORKS(Python)
 

Modules/FindTCL.cmake

@@ -45,7 +45,10 @@ variables were moved or removed.  Changes compared to CMake 2.4 are:
       and dig from there.
 #]=======================================================================]
 
-include(${CMAKE_CURRENT_LIST_DIR}/CMakeFindFrameworks.cmake)
+block(SCOPE_FOR POLICIES)
+  cmake_policy(SET CMP0173 OLD)
+  include(${CMAKE_CURRENT_LIST_DIR}/CMakeFindFrameworks.cmake)
+endblock()
 include(${CMAKE_CURRENT_LIST_DIR}/FindTclsh.cmake)
 include(${CMAKE_CURRENT_LIST_DIR}/FindWish.cmake)
 

Source/cmIncludeCommand.cxx

@@ -20,6 +20,7 @@ bool cmIncludeCommand(std::vector<std::string> const& args,
 {
   static std::map<std::string, cmPolicies::PolicyID> DeprecatedModules;
   if (DeprecatedModules.empty()) {
+    DeprecatedModules["CMakeFindFrameworks"] = cmPolicies::CMP0173;
     DeprecatedModules["Dart"] = cmPolicies::CMP0145;
     DeprecatedModules["Documentation"] = cmPolicies::CMP0106;
     DeprecatedModules["FindBoost"] = cmPolicies::CMP0167;

Source/cmPolicies.h

@@ -531,7 +531,9 @@ class cmMakefile;
   SELECT(POLICY, CMP0172,                                                     \
          "The CPack module enables per-machine installation by default in "   \
          "the CPack WIX Generator.",                                          \
-         3, 31, 0, cmPolicies::WARN)
+         3, 31, 0, cmPolicies::WARN)                                          \
+  SELECT(POLICY, CMP0173, "The CMakeFindFrameworks module is removed.", 3,    \
+         31, 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/CMP0173/CMP0173-NEW-result.txt

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

Tests/RunCMake/CMP0173/CMP0173-NEW-stderr.txt

@@ -0,0 +1,9 @@
+CMake Error at .*/Modules/CMakeFindFrameworks\.cmake:[0-9]+ \(message\):
+  CMakeFindFrameworks\.cmake is not maintained and lacks support for more
+  recent framework handling\.  It will be removed in a future version of
+  CMake\.  Update the code to use find_library\(\) instead\.  Use of this module
+  is now an error according to policy CMP0173\.
+Call Stack \(most recent call first\):
+  CMP0173-common\.cmake:12 \(include\)
+  CMP0173-NEW\.cmake:4 \(include\)
+  CMakeLists\.txt:3 \(include\)

Tests/RunCMake/CMP0173/CMP0173-NEW.cmake

@@ -0,0 +1,4 @@
+cmake_policy(SET CMP0173 NEW)
+
+set(should_find NO)
+include(CMP0173-common.cmake)

Tests/RunCMake/CMP0173/CMP0173-OLD-stdout.txt

@@ -0,0 +1,2 @@
+-- Configuring done \([0-9]+\.[0-9]s\)
+-- Generating done \([0-9]+\.[0-9]s\)

Tests/RunCMake/CMP0173/CMP0173-OLD.cmake

@@ -0,0 +1,4 @@
+cmake_policy(SET CMP0173 OLD)
+
+set(should_find YES)
+include(CMP0173-common.cmake)

Tests/RunCMake/CMP0173/CMP0173-WARN-stderr.txt

@@ -0,0 +1,29 @@
+CMake Warning \(dev\) at CMP0173-common\.cmake:1 \(include\):
+  Policy CMP0173 is not set: The CMakeFindFrameworks module is removed\.  Run
+  "cmake --help-policy CMP0173" for policy details\.  Use the cmake_policy
+  command to set the policy and suppress this warning\.
+
+Call Stack \(most recent call first\):
+  CMP0173-WARN\.cmake:2 \(include\)
+  CMakeLists\.txt:3 \(include\)
+This warning is for project developers\.  Use -Wno-dev to suppress it\.
+
+CMake Warning \(dev\) at .*/Modules/CMakeFindFrameworks\.cmake:[0-9]+ \(message\):
+  CMakeFindFrameworks\.cmake is not maintained and lacks support for more
+  recent framework handling\.  It will be removed in a future version of
+  CMake\.  Update the code to use find_library\(\) instead\.
+Call Stack \(most recent call first\):
+  CMP0173-common\.cmake:1 \(include\)
+  CMP0173-WARN\.cmake:2 \(include\)
+  CMakeLists\.txt:3 \(include\)
+This warning is for project developers\.  Use -Wno-dev to suppress it\.
+
+CMake Warning \(dev\) at .*/Modules/CMakeFindFrameworks\.cmake:[0-9]+ \(message\):
+  CMakeFindFrameworks\.cmake is not maintained and lacks support for more
+  recent framework handling\.  It will be removed in a future version of
+  CMake\.  Update the code to use find_library\(\) instead\.
+Call Stack \(most recent call first\):
+  CMP0173-common\.cmake:12 \(include\)
+  CMP0173-WARN\.cmake:2 \(include\)
+  CMakeLists\.txt:3 \(include\)
+This warning is for project developers\.  Use -Wno-dev to suppress it\.

Tests/RunCMake/CMP0173/CMP0173-WARN.cmake

@@ -0,0 +1,2 @@
+set(should_find YES)
+include(CMP0173-common.cmake)

Tests/RunCMake/CMP0173/CMP0173-common.cmake

@@ -0,0 +1,12 @@
+include(CMakeFindFrameworks OPTIONAL RESULT_VARIABLE found)
+if(NOT should_find AND found)
+  message(FATAL_ERROR
+    "The CMakeFindFrameworks module should not have been found, but it was."
+  )
+endif()
+if(should_find AND NOT found)
+  message(FATAL_ERROR
+    "The CMakeFindFrameworks module should have been found, but it was not."
+  )
+endif()
+include(${CMAKE_ROOT}/Modules/CMakeFindFrameworks.cmake)

Tests/RunCMake/CMP0173/CMakeLists.txt

@@ -0,0 +1,3 @@
+cmake_minimum_required(VERSION 3.30)
+project(${RunCMake_TEST} NONE)
+include(${RunCMake_TEST}.cmake)

Tests/RunCMake/CMP0173/RunCMakeTest.cmake

@@ -0,0 +1,5 @@
+include(RunCMake)
+
+run_cmake(CMP0173-OLD)
+run_cmake(CMP0173-NEW)
+run_cmake(CMP0173-WARN)

Tests/RunCMake/CMakeLists.txt

@@ -177,6 +177,7 @@ add_RunCMake_test(CMP0165)
 add_RunCMake_test(CMP0169)
 add_RunCMake_test(CMP0170)
 add_RunCMake_test(CMP0171)
+add_RunCMake_test(CMP0173)
 
 # The test for Policy 65 requires the use of the
 # CMAKE_SHARED_LIBRARY_LINK_CXX_FLAGS variable, which both the VS and Xcode