Merge topic 'remove-documentation-module'

306a1ba960 Modules/Documentation: remove
ad4487a96a cmIncludeCommand: add infrastructure for deprecated modules

Acked-by: Kitware Robot <[email protected]>
Merge-request: !4617

Help/manual/cmake-policies.7.rst

@@ -57,6 +57,7 @@ Policies Introduced by CMake 3.18
 .. toctree::
    :maxdepth: 1
 
+   CMP0106: The Documentation module is removed. </policy/CMP0106>
    CMP0105: Device link step uses the link options. </policy/CMP0105>
    CMP0104: CMAKE_CUDA_ARCHITECTURES now detected for NVCC, empty CUDA_ARCHITECTURES not allowed. </policy/CMP0104>
    CMP0103: Multiple export() with same FILE without APPEND is not allowed. </policy/CMP0103>

Help/policy/CMP0106.rst

@@ -0,0 +1,19 @@
+CMP0106
+-------
+
+The :module:`Documentation` module is removed.
+
+The :module:`Documentation` was added as a support mechanism for the VTK
+project and was tuned for that project. Instead of CMake providing this module
+with (now old) VTK patterns for cache variables and required packages, the
+module is now deprecated by CMake itself.
+
+The ``OLD`` behavior of this policy is for :module:`Documentation` to add
+cache variables and find VTK documentation dependent packages. The ``NEW``
+behavior is to act as an empty module.
+
+This policy was introduced in CMake version 3.18.  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-documentation-module.rst

@@ -0,0 +1,6 @@
+deprecate-documentation-module
+------------------------------
+
+* The :module:`Documentation` module has been deprecated via
+  :policy:`CMP0106`. This module was essentially VTK code that CMake should
+  not be shipping anymore.

Modules/Documentation.cmake

@@ -9,6 +9,30 @@ This module provides support for the VTK documentation framework.  It
 relies on several tools (Doxygen, Perl, etc).
 #]=======================================================================]
 
+cmake_policy(GET CMP0106 _Documentation_policy)
+
+if (_Documentation_policy STREQUAL "NEW")
+  message(FATAL_ERROR
+    "Documentation.cmake is VTK-specific code and should not be used in "
+    "non-VTK projects. This logic in this module is best shipped with the "
+    "project using it rather than with CMake. This is now an error according "
+    "to policy CMP0106.")
+else ()
+
+if (_Documentation_policy STREQUAL "")
+  # Ignore the warning if the project is detected as VTK itself.
+  if (NOT CMAKE_PROJECT_NAME STREQUAL "VTK" AND
+      NOT PROJECT_NAME STREQUAL "VTK")
+    cmake_policy(GET_WARNING CMP0106 _Documentation_policy_warning)
+    message(AUTHOR_WARNING
+      "${_Documentation_policy_warning}\n"
+      "Documentation.cmake is VTK-specific code and should not be used in "
+      "non-VTK projects. This logic in this module is best shipped with the "
+      "project using it rather than with CMake.")
+  endif ()
+  unset(_Documentation_policy_warning)
+endif ()
+
 #
 # Build the documentation ?
 #
@@ -44,3 +68,7 @@ if (BUILD_DOCUMENTATION)
   #
 
 endif ()
+
+endif ()
+
+unset(_Documentation_policy)

Source/cmIncludeCommand.cxx

@@ -2,7 +2,9 @@
    file Copyright.txt or https://cmake.org/licensing for details.  */
 #include "cmIncludeCommand.h"
 
+#include <map>
 #include <sstream>
+#include <utility>
 
 #include "cmExecutionStatus.h"
 #include "cmGlobalGenerator.h"
@@ -16,6 +18,11 @@
 bool cmIncludeCommand(std::vector<std::string> const& args,
                       cmExecutionStatus& status)
 {
+  static std::map<std::string, cmPolicies::PolicyID> DeprecatedModules;
+  if (DeprecatedModules.empty()) {
+    DeprecatedModules["Documentation"] = cmPolicies::CMP0106;
+  }
+
   if (args.empty() || args.size() > 4) {
     status.SetError("called with wrong number of arguments.  "
                     "include() only takes one file.");
@@ -65,9 +72,35 @@ bool cmIncludeCommand(std::vector<std::string> const& args,
   }
 
   if (!cmSystemTools::FileIsFullPath(fname)) {
+    bool system = false;
     // Not a path. Maybe module.
     std::string module = cmStrCat(fname, ".cmake");
-    std::string mfile = status.GetMakefile().GetModulesFile(module);
+    std::string mfile = status.GetMakefile().GetModulesFile(module, system);
+
+    if (system) {
+      auto ModulePolicy = DeprecatedModules.find(fname);
+      if (ModulePolicy != DeprecatedModules.end()) {
+        cmPolicies::PolicyStatus PolicyStatus =
+          status.GetMakefile().GetPolicyStatus(ModulePolicy->second);
+        switch (PolicyStatus) {
+          case cmPolicies::WARN: {
+            status.GetMakefile().IssueMessage(
+              MessageType::AUTHOR_WARNING,
+              cmStrCat(cmPolicies::GetPolicyWarning(ModulePolicy->second),
+                       "\n"));
+            CM_FALLTHROUGH;
+          }
+          case cmPolicies::OLD:
+            break;
+          case cmPolicies::REQUIRED_IF_USED:
+          case cmPolicies::REQUIRED_ALWAYS:
+          case cmPolicies::NEW:
+            mfile = "";
+            break;
+        }
+      }
+    }
+
     if (!mfile.empty()) {
       fname = mfile;
     }

Source/cmPolicies.h

@@ -314,7 +314,9 @@ class cmMakefile;
          "CUDA_ARCHITECTURES not allowed.",                                   \
          3, 18, 0, cmPolicies::WARN)                                          \
   SELECT(POLICY, CMP0105, "Device link step uses the link options.", 3, 18,   \
-         0, cmPolicies::WARN)
+         0, cmPolicies::WARN)                                                 \
+  SELECT(POLICY, CMP0106, "The Documentation module is removed.", 3, 18, 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/CMP0106/CMP0106-Common.cmake

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

Tests/RunCMake/CMP0106/CMP0106-NEW-result.txt

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

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

@@ -0,0 +1,9 @@
+CMake Error at .*/Modules/Documentation.cmake:15 \(message\):
+  Documentation.cmake is VTK-specific code and should not be used in non-VTK
+  projects.  This logic in this module is best shipped with the project using
+  it rather than with CMake.  This is now an error according to policy
+  CMP0106.
+Call Stack \(most recent call first\):
+  CMP0106-Common.cmake:10 \(include\)
+  CMP0106-NEW.cmake:4 \(include\)
+  CMakeLists.txt:7 \(include\)

Tests/RunCMake/CMP0106/CMP0106-NEW.cmake

@@ -0,0 +1,4 @@
+cmake_policy(SET CMP0106 NEW)
+
+set(should_find OFF)
+include(CMP0106-Common.cmake)

Tests/RunCMake/CMP0106/CMP0106-OLD.cmake

@@ -0,0 +1,9 @@
+cmake_policy(SET CMP0106 OLD)
+
+set(should_find ON)
+include(CMP0106-Common.cmake)
+if (NOT DEFINED BUILD_DOCUMENTATION)
+  message(FATAL_ERROR
+    "Cache variables seem to have not been made with a `OLD` policy "
+    "setting.")
+endif ()

Tests/RunCMake/CMP0106/CMP0106-WARN-ParaView-stderr.txt

@@ -0,0 +1,8 @@
+CMake Warning \(dev\) at CMP0106-Common.cmake:1 \(include\):
+  Policy CMP0106 is not set: The Documentation module is removed.  Run "cmake
+  --help-policy CMP0106" for policy details.  Use the cmake_policy command to
+  set the policy and suppress this warning.
+
+Call Stack \(most recent call first\):
+  subdir/CMakeLists.txt:2 \(include\)
+This warning is for project developers.  Use -Wno-dev to suppress it.

Tests/RunCMake/CMP0106/CMP0106-WARN-ParaView.cmake

@@ -0,0 +1,2 @@
+set(should_find ON)
+add_subdirectory(subdir)

Tests/RunCMake/CMP0106/CMP0106-WARN-VTK-stderr.txt

@@ -0,0 +1,9 @@
+CMake Warning \(dev\) at CMP0106-Common.cmake:1 \(include\):
+  Policy CMP0106 is not set: The Documentation module is removed.  Run "cmake
+  --help-policy CMP0106" for policy details.  Use the cmake_policy command to
+  set the policy and suppress this warning.
+
+Call Stack \(most recent call first\):
+  CMP0106-WARN-VTK.cmake:2 \(include\)
+  CMakeLists.txt:7 \(include\)
+This warning is for project developers.  Use -Wno-dev to suppress it.

Tests/RunCMake/CMP0106/CMP0106-WARN-VTK.cmake

@@ -0,0 +1,2 @@
+set(should_find ON)
+include(CMP0106-Common.cmake)

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

@@ -0,0 +1,37 @@
+CMake Warning \(dev\) at CMP0106-Common.cmake:1 \(include\):
+  Policy CMP0106 is not set: The Documentation module is removed.  Run "cmake
+  --help-policy CMP0106" for policy details.  Use the cmake_policy command to
+  set the policy and suppress this warning.
+
+Call Stack \(most recent call first\):
+  CMP0106-WARN.cmake:2 \(include\)
+  CMakeLists.txt:7 \(include\)
+This warning is for project developers.  Use -Wno-dev to suppress it.
+
+CMake Warning \(dev\) at .*/Modules/Documentation.cmake:27 \(message\):
+  Policy CMP0106 is not set: The Documentation module is removed.  Run "cmake
+  --help-policy CMP0106" for policy details.  Use the cmake_policy command to
+  set the policy and suppress this warning.
+
+  Documentation.cmake is VTK-specific code and should not be used in non-VTK
+  projects.  This logic in this module is best shipped with the project using
+  it rather than with CMake.
+Call Stack \(most recent call first\):
+  CMP0106-Common.cmake:1 \(include\)
+  CMP0106-WARN.cmake:2 \(include\)
+  CMakeLists.txt:7 \(include\)
+This warning is for project developers.  Use -Wno-dev to suppress it.
+
+CMake Warning \(dev\) at .*/Modules/Documentation.cmake:27 \(message\):
+  Policy CMP0106 is not set: The Documentation module is removed.  Run "cmake
+  --help-policy CMP0106" for policy details.  Use the cmake_policy command to
+  set the policy and suppress this warning.
+
+  Documentation.cmake is VTK-specific code and should not be used in non-VTK
+  projects.  This logic in this module is best shipped with the project using
+  it rather than with CMake.
+Call Stack \(most recent call first\):
+  CMP0106-Common.cmake:10 \(include\)
+  CMP0106-WARN.cmake:2 \(include\)
+  CMakeLists.txt:7 \(include\)
+This warning is for project developers.  Use -Wno-dev to suppress it.

Tests/RunCMake/CMP0106/CMP0106-WARN.cmake

@@ -0,0 +1,2 @@
+set(should_find ON)
+include(CMP0106-Common.cmake)

Tests/RunCMake/CMP0106/CMakeLists.txt

@@ -0,0 +1,7 @@
+cmake_minimum_required(VERSION 3.1)
+if (RunCMake_TEST STREQUAL "CMP0106-WARN-VTK")
+  project(VTK NONE)
+else ()
+  project(${RunCMake_TEST} NONE)
+endif ()
+include(${RunCMake_TEST}.cmake)

Tests/RunCMake/CMP0106/RunCMakeTest.cmake

@@ -0,0 +1,7 @@
+include(RunCMake)
+
+run_cmake(CMP0106-OLD)
+run_cmake(CMP0106-NEW)
+run_cmake(CMP0106-WARN)
+run_cmake(CMP0106-WARN-VTK)
+run_cmake(CMP0106-WARN-ParaView)

Tests/RunCMake/CMP0106/subdir/CMakeLists.txt

@@ -0,0 +1,2 @@
+project(VTK NONE)
+include(${CMAKE_CURRENT_SOURCE_DIR}/../CMP0106-Common.cmake)

Tests/RunCMake/CMakeLists.txt

@@ -119,6 +119,7 @@ add_RunCMake_test(CMP0102)
 if(CMake_TEST_CUDA)
   add_RunCMake_test(CMP0104)
 endif()
+add_RunCMake_test(CMP0106)
 
 # The test for Policy 65 requires the use of the
 # CMAKE_SHARED_LIBRARY_LINK_CXX_FLAGS variable, which both the VS and Xcode