Commit da7ad799 authored by Brad King's avatar Brad King Committed by Craig Scott
Browse files

WriteCompilerDetectionHeader: Add policy to remove module

See justification in the policy documentation.

Closes: #17842
parent 541f1410
Pipeline #203625 passed with stage
......@@ -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
----------------------------
......
......@@ -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
=======================
......
......@@ -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>
......
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/
remove-WCDH-module
------------------
* The :module:`WriteCompilerDetectionHeader` module has been deprecated
via policy :policy:`CMP0120`. Projects should be ported away from it.
......@@ -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)
......
......@@ -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) {
......
......@@ -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) \
......
^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\)$
cmake_policy(SET CMP0120 NEW)
include(${CMAKE_ROOT}/Modules/WriteCompilerDetectionHeader.cmake)
^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\)$
cmake_policy(SET CMP0120 NEW)
include(WriteCompilerDetectionHeader)
cmake_policy(SET CMP0120 OLD)
include(${CMAKE_ROOT}/Modules/WriteCompilerDetectionHeader.cmake)
cmake_policy(SET CMP0120 OLD)
include(WriteCompilerDetectionHeader)
^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.$
include(${CMAKE_ROOT}/Modules/WriteCompilerDetectionHeader.cmake)
^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.$
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment