Dart,FindDart: Add policy to remove these modules

These modules and the "DART" tool they support have long been replaced
by CTest.

Help/manual/cmake-policies.7.rst

@@ -57,6 +57,7 @@ Policies Introduced by CMake 3.27
 .. toctree::
    :maxdepth: 1
 
+   CMP0145: The Dart and FindDart modules are removed. </policy/CMP0145>
    CMP0144: find_package uses upper-case PACKAGENAME_ROOT variables. </policy/CMP0144>
 
 Policies Introduced by CMake 3.26

Help/policy/CMP0145.rst

@@ -0,0 +1,30 @@
+CMP0145
+-------
+
+.. versionadded:: 3.27
+
+The :module:`Dart` and :module:`FindDart` modules are removed.
+
+These modules were added very early in CMake's development to support
+driving tests with a "DART" tool, but DART has not been distributed or
+maintained for many years.  Projects would ``include(Dart)`` to use it,
+and the ``Dart`` module would run ``find_package(Dart)`` internally.
+Since :manual:`ctest(1)` was created, the ``Dart`` module has just been
+a compatibility shim that finds ``Dart`` to support some legacy
+functionality and then forwards to the :module:`CTest` module.
+
+CMake 3.27 and above prefer to not provide the :module:`Dart` or
+:module:`FindDart` modules.  This policy provides compatibility for
+projects that have not been ported away from them.  Projects using the
+``Dart`` module should be updated to use the :module:`CTest` module directly.
+
+The ``OLD`` behavior of this policy is for ``include(Dart)`` and
+``find_package(Dart)`` to load the deprecated modules.  The ``NEW``
+behavior is for uses of the modules to fail as if they do not exist.
+
+This policy was introduced in CMake version 3.27.  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/remove-dart-modules.rst

@@ -0,0 +1,5 @@
+remove-dart-modules
+-------------------
+
+* The :module:`Dart` and :module:`FindDart` modules have been deprecated via
+  policy :policy:`CMP0145`.  Port projects to the :module:`CTest` module.

Modules/Dart.cmake

@@ -5,6 +5,11 @@
 Dart
 ----
 
+.. deprecated:: 3.27
+  This module is available only if policy :policy:`CMP0145`
+  is not set to ``NEW``.  Do not use it in new code.
+  Use the :module:`CTest` module instead.
+
 Configure a project for testing with CTest or old Dart Tcl Client
 
 This file is the backwards-compatibility version of the CTest module.
@@ -33,10 +38,24 @@ whether testing support should be enabled.  The default is ON.
 #
 #
 
+# include(Dart) already warns about CMP0145, but back when this module was in
+# common use, it was often loaded via include(${CMAKE_ROOT}/Modules/Dart.cmake)
+# which will not warn.  Warn again just in case.
+cmake_policy(GET CMP0145 cmp0145)
+if(cmp0145 STREQUAL "")
+  cmake_policy(GET_WARNING CMP0145 _cmp0145_warning)
+  message(AUTHOR_WARNING "${_cmp0145_warning}")
+endif()
+
 option(BUILD_TESTING "Build the testing tree." ON)
 
 if(BUILD_TESTING)
+  # We only get here if a project already ran include(Dart),
+  # so avoid warning about CMP0145 again.
+  cmake_policy(PUSH)
+  cmake_policy(SET CMP0145 OLD)
   find_package(Dart QUIET)
+  cmake_policy(POP)
 
   #
   # Section #1:

Modules/FindDart.cmake

@@ -5,12 +5,20 @@
 FindDart
 --------
 
+.. deprecated:: 3.27
+  This module is available only if policy :policy:`CMP0145` is not set to ``NEW``.
+
 Find DART
 
 This module looks for the dart testing software and sets DART_ROOT to
 point to where it found it.
 #]=======================================================================]
 
+if(_FindDart_testing)
+  set(_FindDart_included TRUE)
+  return()
+endif()
+
 find_path(DART_ROOT README.INSTALL
     HINTS
       ENV DART_ROOT

Source/cmFindPackageCommand.cxx

@@ -502,6 +502,7 @@ cmFindPackageCommand::cmFindPackageCommand(cmExecutionStatus& status)
   this->DebugMode = false;
   this->AppendSearchPathGroups();
 
+  this->DeprecatedFindModules["Dart"] = cmPolicies::CMP0145;
   this->DeprecatedFindModules["Qt"] = cmPolicies::CMP0084;
 }
 

Source/cmIncludeCommand.cxx

@@ -20,7 +20,9 @@ bool cmIncludeCommand(std::vector<std::string> const& args,
 {
   static std::map<std::string, cmPolicies::PolicyID> DeprecatedModules;
   if (DeprecatedModules.empty()) {
+    DeprecatedModules["Dart"] = cmPolicies::CMP0145;
     DeprecatedModules["Documentation"] = cmPolicies::CMP0106;
+    DeprecatedModules["FindDart"] = cmPolicies::CMP0145;
     DeprecatedModules["WriteCompilerDetectionHeader"] = cmPolicies::CMP0120;
   }
 

Source/cmPolicies.h

@@ -437,7 +437,9 @@ class cmMakefile;
          cmPolicies::WARN)                                                    \
   SELECT(POLICY, CMP0144,                                                     \
          "find_package uses upper-case <PACKAGENAME>_ROOT variables.", 3, 27, \
-         0, cmPolicies::WARN)
+         0, cmPolicies::WARN)                                                 \
+  SELECT(POLICY, CMP0145, "The Dart and FindDart modules are removed.", 3,    \
+         27, 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/CTest/CMP0145-Dart-NEW-result.txt

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

Tests/RunCMake/CTest/CMP0145-Dart-NEW-stderr.txt

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

Tests/RunCMake/CTest/CMP0145-Dart-NEW.cmake

@@ -0,0 +1,2 @@
+cmake_policy(SET CMP0145 NEW)
+include(Dart)

Tests/RunCMake/CTest/CMP0145-Dart-OLD.cmake

@@ -0,0 +1,7 @@
+cmake_policy(SET CMP0145 OLD)
+set(_FindDart_testing 1)
+include(Dart)
+
+if(NOT _FindDart_included)
+  message(FATAL_ERROR "FindDart.cmake not included")
+endif()

Tests/RunCMake/CTest/CMP0145-Dart-WARN-stderr.txt

@@ -0,0 +1,18 @@
+^CMake Warning \(dev\) at CMP0145-Dart-WARN\.cmake:[0-9]+ \(include\):
+  Policy CMP0145 is not set: The Dart and FindDart modules are removed\.  Run
+  "cmake --help-policy CMP0145" 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\.
++
+CMake Warning \(dev\) at [^
+]*/Modules/Dart\.cmake:[0-9]+ \(message\):
+  Policy CMP0145 is not set: The Dart and FindDart modules are removed\.  Run
+  "cmake --help-policy CMP0145" for policy details\.  Use the cmake_policy
+  command to set the policy and suppress this warning\.
+Call Stack \(most recent call first\):
+  CMP0145-Dart-WARN\.cmake:[0-9]+ \(include\)
+  CMakeLists\.txt:[0-9]+ \(include\)
+This warning is for project developers\.  Use -Wno-dev to suppress it\.$

Tests/RunCMake/CTest/CMP0145-Dart-WARN.cmake

@@ -0,0 +1,7 @@
+# Do not set CMP0145.
+set(_FindDart_testing 1)
+include(Dart)
+
+if(NOT _FindDart_included)
+  message(FATAL_ERROR "FindDart.cmake not included")
+endif()

Tests/RunCMake/CTest/CMP0145-FindDart-NEW-result.txt

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

Tests/RunCMake/CTest/CMP0145-FindDart-NEW-stderr.txt

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

Tests/RunCMake/CTest/CMP0145-FindDart-NEW.cmake

@@ -0,0 +1,2 @@
+cmake_policy(SET CMP0145 NEW)
+include(FindDart)

Tests/RunCMake/CTest/CMP0145-FindDart-OLD.cmake

@@ -0,0 +1,7 @@
+cmake_policy(SET CMP0145 OLD)
+set(_FindDart_testing 1)
+include(FindDart)
+
+if(NOT _FindDart_included)
+  message(FATAL_ERROR "FindDart.cmake not included")
+endif()

Tests/RunCMake/CTest/CMP0145-FindDart-WARN-stderr.txt

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

@@ -0,0 +1,7 @@
+# Do not set CMP0145.
+set(_FindDart_testing 1)
+include(FindDart)
+
+if(NOT _FindDart_included)
+  message(FATAL_ERROR "FindDart.cmake not included")
+endif()

Tests/RunCMake/CTest/RunCMakeTest.cmake

@@ -39,3 +39,10 @@ endfunction()
 if(NOT RunCMake_GENERATOR_IS_MULTI_CONFIG)
   run_SingleConfig()
 endif()
+
+run_cmake(CMP0145-Dart-OLD)
+run_cmake(CMP0145-Dart-WARN)
+run_cmake(CMP0145-Dart-NEW)
+run_cmake(CMP0145-FindDart-OLD)
+run_cmake(CMP0145-FindDart-WARN)
+run_cmake(CMP0145-FindDart-NEW)

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

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

Tests/RunCMake/find_package/CMP0145-NEW.cmake

@@ -0,0 +1,7 @@
+cmake_policy(SET CMP0145 NEW)
+set(_FindDart_testing TRUE)
+find_package(Dart MODULE)
+
+if(_FindDart_included)
+  message(FATAL_ERROR "FindDart.cmake erroneously included")
+endif()

Tests/RunCMake/find_package/CMP0145-OLD.cmake

@@ -0,0 +1,7 @@
+cmake_policy(SET CMP0145 OLD)
+set(_FindDart_testing TRUE)
+find_package(Dart MODULE)
+
+if(NOT _FindDart_included)
+  message(FATAL_ERROR "FindDart.cmake not included")
+endif()

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

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

@@ -0,0 +1,6 @@
+set(_FindDart_testing TRUE)
+find_package(Dart MODULE)
+
+if(NOT _FindDart_included)
+  message(FATAL_ERROR "FindDart.cmake not included")
+endif()

Tests/RunCMake/find_package/RunCMakeTest.cmake

@@ -36,6 +36,9 @@ run_cmake(WrongVersionConfig)
 run_cmake(CMP0084-OLD)
 run_cmake(CMP0084-WARN)
 run_cmake(CMP0084-NEW)
+run_cmake(CMP0145-OLD)
+run_cmake(CMP0145-WARN)
+run_cmake(CMP0145-NEW)
 run_cmake(WrongVersionRange)
 run_cmake(EmptyVersionRange)
 run_cmake(VersionRangeWithEXACT)