WriteCompilerDetectionHeader: Add policy to remove module

See justification in the policy documentation.

Closes: #17842

Help/manual/cmake-compile-features.7.rst

@@ -89,6 +89,8 @@ Feature requirements are evaluated transitively by consuming the link
 implementation.  See :manual:`cmake-buildsystem(7)` for more on
 transitive behavior of build properties and usage requirements.
 
+.. _`Requiring Language Standards`:
+
 Requiring Language Standards
 ----------------------------
 

Help/manual/cmake-modules.7.rst

@@ -99,7 +99,6 @@ These modules are loaded using the :command:`include` command.
    /module/UseJava
    /module/UseSWIG
    /module/UsewxWidgets
-   /module/WriteCompilerDetectionHeader
 
 Find Modules
 ^^^^^^^^^^^^
@@ -285,6 +284,7 @@ Deprecated Utility Modules
    /module/UsePkgConfig
    /module/Use_wxWindows
    /module/WriteBasicConfigVersionFile
+   /module/WriteCompilerDetectionHeader
 
 Deprecated Find Modules
 =======================

Help/manual/cmake-policies.7.rst

@@ -57,6 +57,7 @@ Policies Introduced by CMake 3.20
 .. toctree::
    :maxdepth: 1
 
+   CMP0120: The WriteCompilerDetectionHeader module is removed. </policy/CMP0120>
    CMP0119: LANGUAGE source file property explicitly compiles as language. </policy/CMP0119>
    CMP0118: The GENERATED source file property is now visible in all directories. </policy/CMP0118>
    CMP0117: MSVC RTTI flag /GR is not added to CMAKE_CXX_FLAGS by default. </policy/CMP0117>

Help/policy/CMP0120.rst

@@ -0,0 +1,47 @@
+CMP0120
+-------
+
+.. versionadded:: 3.20
+
+The :module:`WriteCompilerDetectionHeader` module is removed.
+
+CMake versions 3.1 through 3.19 provide this module to generate a
+C++ compatibility layer by re-using information from CMake's table of
+preprocessor checks for :manual:`cmake-compile-features(7)`.  However:
+
+* Those granular features have been superseded by meta-features for
+  :ref:`Requiring Language Standards` such as ``cxx_std_11``.  Therefore
+  no new granular feature checks will be added and projects will need to
+  use other means to conditionally use new C++ features.
+
+* The module exposes some of CMake's implementation details directly
+  to C++ translation units.
+
+* The module's approach effectively provides a header file with CMake,
+  thus tying the version of the header to the version of CMake.
+  Many projects found that the :module:`WriteCompilerDetectionHeader` was
+  best used by manually generating its header locally with a recent version
+  of CMake and then bundling it with the project source so that it could
+  be used with older CMake versions.
+
+For reasons including the above, CMake 3.20 and above prefer to not
+provide the :module:`WriteCompilerDetectionHeader` module.  This policy
+provides compatibility for projects that have not been ported away from
+it.  Projects using the module should be updated to stop using it.
+Alternatives include:
+
+* Bundle a copy of the generated header in the project's source.
+* Use a third-party alternative, such as the CC0-licensed `Hedley`_.
+* Drop support for compilers too old to provide the features natively.
+
+The ``OLD`` behavior of this policy is for inclusion of the deprecated
+:module:`WriteCompilerDetectionHeader` module to work.  The ``NEW``
+behavior is for inclusion of the module to fail as if it does not exist.
+
+This policy was introduced in CMake version 3.20.  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
+
+.. _`Hedley`: https://nemequ.github.io/hedley/

Help/release/dev/remove-WCDH-module.rst

@@ -0,0 +1,5 @@
+remove-WCDH-module
+------------------
+
+* The :module:`WriteCompilerDetectionHeader` module has been deprecated
+  via policy :policy:`CMP0120`.  Projects should be ported away from it.

Modules/WriteCompilerDetectionHeader.cmake

@@ -5,6 +5,10 @@
 WriteCompilerDetectionHeader
 ----------------------------
 
+.. deprecated:: 3.20
+  This module is available only if policy :policy:`CMP0120`
+  is not set to ``NEW``.  Do not use it in new code.
+
 .. versionadded:: 3.1
 
 This module provides the function ``write_compiler_detection_header()``.
@@ -243,6 +247,18 @@ library:
   )
 #]=======================================================================]
 
+# Guard against inclusion by absolute path.
+cmake_policy(GET CMP0120 _WCDH_policy)
+if(_WCDH_policy STREQUAL "NEW")
+  message(FATAL_ERROR "The WriteCompilerDetectionHeader module has been removed by policy CMP0120.")
+elseif(_WCDH_policy STREQUAL "")
+  message(AUTHOR_WARNING
+    "The WriteCompilerDetectionHeader module will be removed by policy CMP0120.  "
+    "Projects should be ported away from the module, perhaps by bundling a copy "
+    "of the generated header or using a third-party alternative."
+    )
+endif()
+
 include(${CMAKE_CURRENT_LIST_DIR}/CMakeCompilerIdDetection.cmake)
 
 function(_load_compiler_variables CompilerId lang)

Source/cmIncludeCommand.cxx

@@ -21,6 +21,7 @@ bool cmIncludeCommand(std::vector<std::string> const& args,
   static std::map<std::string, cmPolicies::PolicyID> DeprecatedModules;
   if (DeprecatedModules.empty()) {
     DeprecatedModules["Documentation"] = cmPolicies::CMP0106;
+    DeprecatedModules["WriteCompilerDetectionHeader"] = cmPolicies::CMP0120;
   }
 
   if (args.empty() || args.size() > 4) {

Source/cmPolicies.h

@@ -356,7 +356,10 @@ class cmMakefile;
   SELECT(POLICY, CMP0119,                                                     \
          "LANGUAGE source file property explicitly compiles as specified "    \
          "language.",                                                         \
-         3, 20, 0, cmPolicies::WARN)
+         3, 20, 0, cmPolicies::WARN)                                          \
+  SELECT(POLICY, CMP0120,                                                     \
+         "The WriteCompilerDetectionHeader module is removed.", 3, 20, 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/WriteCompilerDetectionHeader/CMP0120-NEW-Direct-result.txt

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

Tests/RunCMake/WriteCompilerDetectionHeader/CMP0120-NEW-Direct-stderr.txt

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

Tests/RunCMake/WriteCompilerDetectionHeader/CMP0120-NEW-Direct.cmake

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

Tests/RunCMake/WriteCompilerDetectionHeader/CMP0120-NEW-result.txt

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

Tests/RunCMake/WriteCompilerDetectionHeader/CMP0120-NEW-stderr.txt

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

Tests/RunCMake/WriteCompilerDetectionHeader/CMP0120-NEW.cmake

@@ -0,0 +1,2 @@
+cmake_policy(SET CMP0120 NEW)
+include(WriteCompilerDetectionHeader)

Tests/RunCMake/WriteCompilerDetectionHeader/CMP0120-OLD-Direct.cmake

@@ -0,0 +1,2 @@
+cmake_policy(SET CMP0120 OLD)
+include(${CMAKE_ROOT}/Modules/WriteCompilerDetectionHeader.cmake)

Tests/RunCMake/WriteCompilerDetectionHeader/CMP0120-OLD.cmake

@@ -0,0 +1,2 @@
+cmake_policy(SET CMP0120 OLD)
+include(WriteCompilerDetectionHeader)

Tests/RunCMake/WriteCompilerDetectionHeader/CMP0120-WARN-Direct-stderr.txt

@@ -0,0 +1,9 @@
+^CMake Warning \(dev\) at [^
+]*/Modules/WriteCompilerDetectionHeader.cmake:[0-9]+ \(message\):
+  The WriteCompilerDetectionHeader module will be removed by policy CMP0120.
+  Projects should be ported away from the module, perhaps by bundling a copy
+  of the generated header or using a third-party alternative.
+Call Stack \(most recent call first\):
+  CMP0120-WARN-Direct.cmake:[0-9]+ \(include\)
+  CMakeLists.txt:[0-9]+ \(include\)
+This warning is for project developers.  Use -Wno-dev to suppress it.$

Tests/RunCMake/WriteCompilerDetectionHeader/CMP0120-WARN-Direct.cmake

@@ -0,0 +1,2 @@
+
+include(${CMAKE_ROOT}/Modules/WriteCompilerDetectionHeader.cmake)

Tests/RunCMake/WriteCompilerDetectionHeader/CMP0120-WARN-stderr.txt

@@ -0,0 +1,18 @@
+^CMake Warning \(dev\) at CMP0120-WARN.cmake:[0-9]+ \(include\):
+  Policy CMP0120 is not set: The WriteCompilerDetectionHeader module is
+  removed.  Run "cmake --help-policy CMP0120" 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/WriteCompilerDetectionHeader.cmake:[0-9]+ \(message\):
+  The WriteCompilerDetectionHeader module will be removed by policy CMP0120.
+  Projects should be ported away from the module, perhaps by bundling a copy
+  of the generated header or using a third-party alternative.
+Call Stack \(most recent call first\):
+  CMP0120-WARN.cmake:[0-9]+ \(include\)
+  CMakeLists.txt:[0-9]+ \(include\)
+This warning is for project developers.  Use -Wno-dev to suppress it.$

Tests/RunCMake/WriteCompilerDetectionHeader/CMP0120-WARN.cmake

@@ -0,0 +1,2 @@
+
+include(WriteCompilerDetectionHeader)

Tests/RunCMake/WriteCompilerDetectionHeader/RunCMakeTest.cmake

@@ -1,5 +1,12 @@
 include(RunCMake)
 
+run_cmake(CMP0120-WARN)
+run_cmake(CMP0120-OLD)
+run_cmake(CMP0120-NEW)
+run_cmake(CMP0120-WARN-Direct)
+run_cmake(CMP0120-OLD-Direct)
+run_cmake(CMP0120-NEW-Direct)
+
 run_cmake(InvalidArgs)
 run_cmake(NoCompiler)
 run_cmake(NoFeature)