From 6be0fe22be0eff618730f96e8ceca7cbd15a47c8 Mon Sep 17 00:00:00 2001 From: Brad King Date: Mon, 20 Jan 2025 15:49:01 -0500 Subject: Help: Mention CMAKE_POLICY_DEFAULT_CMP in cmake_minimum_required We already mention it in equivalent text for `cmake_policy`. --- Help/command/cmake_minimum_required.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/Help/command/cmake_minimum_required.rst b/Help/command/cmake_minimum_required.rst index de2c8f3..2833ed7 100644 --- a/Help/command/cmake_minimum_required.rst +++ b/Help/command/cmake_minimum_required.rst @@ -59,9 +59,10 @@ project code is written for the given range of CMake versions. All policies known to the running version of CMake and introduced in the ```` (or ````, if specified) version or earlier will be set to use ``NEW`` behavior. All policies introduced in later -versions will be unset. This effectively requests behavior preferred -as of a given CMake version and tells newer CMake versions to warn -about their new policies. +versions will be unset (unless the +:variable:`CMAKE_POLICY_DEFAULT_CMP` variable sets a default). +This effectively requests behavior preferred as of a given CMake +version and tells newer CMake versions to warn about their new policies. When a ```` version higher than 2.4 is specified the command implicitly invokes -- cgit v0.12 From ec9e5feb936e0fe16f4d7d46182253334267ff70 Mon Sep 17 00:00:00 2001 From: Brad King Date: Mon, 20 Jan 2025 15:53:39 -0500 Subject: Help: Organize cmake-policies(7) by supported and unsupported policies --- Help/manual/cmake-policies.7.rst | 107 ++++++++++++++++++++++++--------------- 1 file changed, 67 insertions(+), 40 deletions(-) diff --git a/Help/manual/cmake-policies.7.rst b/Help/manual/cmake-policies.7.rst index 35e9403..d973c53 100644 --- a/Help/manual/cmake-policies.7.rst +++ b/Help/manual/cmake-policies.7.rst @@ -51,8 +51,13 @@ The :variable:`CMAKE_MINIMUM_REQUIRED_VERSION` variable may also be used to determine whether to report an error on use of deprecated macros or functions. +Supported Policies +================== + +The following policies are supported. + Policies Introduced by CMake 4.0 -================================ +-------------------------------- .. toctree:: :maxdepth: 1 @@ -62,7 +67,7 @@ Policies Introduced by CMake 4.0 CMP0181: Link command-line fragment variables are parsed and re-quoted. Policies Introduced by CMake 3.31 -================================= +--------------------------------- .. toctree:: :maxdepth: 1 @@ -79,7 +84,7 @@ Policies Introduced by CMake 3.31 CMP0171: 'codegen' is a reserved target name. Policies Introduced by CMake 3.30 -================================= +--------------------------------- .. toctree:: :maxdepth: 1 @@ -95,7 +100,7 @@ Policies Introduced by CMake 3.30 CMP0162: Visual Studio generators add UseDebugLibraries indicators by default. Policies Introduced by CMake 3.29 -================================= +--------------------------------- .. toctree:: :maxdepth: 1 @@ -108,7 +113,7 @@ Policies Introduced by CMake 3.29 CMP0156: De-duplicate libraries on link lines based on linker capabilities. Policies Introduced by CMake 3.28 -================================= +--------------------------------- .. toctree:: :maxdepth: 1 @@ -119,7 +124,7 @@ Policies Introduced by CMake 3.28 CMP0152: file(REAL_PATH) resolves symlinks before collapsing ../ components. Policies Introduced by CMake 3.27 -================================= +--------------------------------- .. toctree:: :maxdepth: 1 @@ -134,7 +139,7 @@ Policies Introduced by CMake 3.27 CMP0144: find_package uses upper-case PACKAGENAME_ROOT variables. Policies Introduced by CMake 3.26 -================================= +--------------------------------- .. toctree:: :maxdepth: 1 @@ -142,7 +147,7 @@ Policies Introduced by CMake 3.26 CMP0143: USE_FOLDERS global property is treated as ON by default. Policies Introduced by CMake 3.25 -================================= +--------------------------------- .. toctree:: :maxdepth: 1 @@ -152,7 +157,7 @@ Policies Introduced by CMake 3.25 CMP0140: The return() command checks its arguments. Policies Introduced by CMake 3.24 -================================= +--------------------------------- .. toctree:: :maxdepth: 1 @@ -169,7 +174,7 @@ Policies Introduced by CMake 3.24 CMP0130: while() diagnoses condition evaluation errors. Policies Introduced by CMake 3.23 -================================= +--------------------------------- .. toctree:: :maxdepth: 1 @@ -177,7 +182,7 @@ Policies Introduced by CMake 3.23 CMP0129: Compiler id for MCST LCC compilers is now LCC, not GNU. Policies Introduced by CMake 3.22 -================================= +--------------------------------- .. toctree:: :maxdepth: 1 @@ -186,7 +191,7 @@ Policies Introduced by CMake 3.22 CMP0127: cmake_dependent_option() supports full Condition Syntax. Policies Introduced by CMake 3.21 -================================= +--------------------------------- .. toctree:: :maxdepth: 1 @@ -199,7 +204,7 @@ Policies Introduced by CMake 3.21 CMP0121: The list command detects invalid indices. Policies Introduced by CMake 3.20 -================================= +--------------------------------- .. toctree:: :maxdepth: 1 @@ -212,7 +217,7 @@ Policies Introduced by CMake 3.20 CMP0115: Source file extensions must be explicit. Policies Introduced by CMake 3.19 -================================= +--------------------------------- .. toctree:: :maxdepth: 1 @@ -225,7 +230,7 @@ Policies Introduced by CMake 3.19 CMP0109: find_program() requires permission to execute but not to read. Policies Introduced by CMake 3.18 -================================= +--------------------------------- .. toctree:: :maxdepth: 1 @@ -238,7 +243,7 @@ Policies Introduced by CMake 3.18 CMP0103: Multiple export() with same FILE without APPEND is not allowed. Policies Introduced by CMake 3.17 -================================= +--------------------------------- .. toctree:: :maxdepth: 1 @@ -250,7 +255,7 @@ Policies Introduced by CMake 3.17 CMP0098: FindFLEX runs flex in CMAKE_CURRENT_BINARY_DIR when executing. Policies Introduced by CMake 3.16 -================================= +--------------------------------- .. toctree:: :maxdepth: 1 @@ -260,7 +265,7 @@ Policies Introduced by CMake 3.16 CMP0095: RPATH entries are properly escaped in the intermediary CMake install script. Policies Introduced by CMake 3.15 -================================= +--------------------------------- .. toctree:: :maxdepth: 1 @@ -273,7 +278,7 @@ Policies Introduced by CMake 3.15 CMP0089: Compiler id for IBM Clang-based XL compilers is now XLClang. Policies Introduced by CMake 3.14 -================================= +--------------------------------- .. toctree:: :maxdepth: 1 @@ -288,7 +293,7 @@ Policies Introduced by CMake 3.14 Policies Introduced by CMake 3.13 -================================= +--------------------------------- .. toctree:: :maxdepth: 1 @@ -301,7 +306,7 @@ Policies Introduced by CMake 3.13 CMP0076: target_sources() command converts relative paths to absolute. Policies Introduced by CMake 3.12 -================================= +--------------------------------- .. toctree:: :maxdepth: 1 @@ -311,7 +316,7 @@ Policies Introduced by CMake 3.12 CMP0073: Do not produce legacy _LIB_DEPENDS cache entries. Policies Introduced by CMake 3.11 -================================= +--------------------------------- .. toctree:: :maxdepth: 1 @@ -319,7 +324,7 @@ Policies Introduced by CMake 3.11 CMP0072: FindOpenGL prefers GLVND by default when available. Policies Introduced by CMake 3.10 -================================= +--------------------------------- .. toctree:: :maxdepth: 1 @@ -328,7 +333,7 @@ Policies Introduced by CMake 3.10 CMP0070: Define file(GENERATE) behavior for relative paths. Policies Introduced by CMake 3.9 -================================ +-------------------------------- .. toctree:: :maxdepth: 1 @@ -337,7 +342,7 @@ Policies Introduced by CMake 3.9 CMP0068: RPATH settings on macOS do not affect install_name. Policies Introduced by CMake 3.8 -================================ +-------------------------------- .. toctree:: :maxdepth: 1 @@ -345,15 +350,25 @@ Policies Introduced by CMake 3.8 CMP0067: Honor language standard in try_compile() source-file signature. Policies Introduced by CMake 3.7 -================================ +-------------------------------- .. toctree:: :maxdepth: 1 CMP0066: Honor per-config flags in try_compile() source-file signature. -Policies Introduced by CMake 3.4 -================================ +Unsupported Policies +==================== + +The following policies are no longer supported. +Projects' calls to :command:`cmake_minimum_required(VERSION)` or +:command:`cmake_policy(VERSION)` must set them to ``NEW``. +Their ``OLD`` behaviors have been removed from CMake. + +.. _`Policies Introduced by CMake 3.4`: + +Policies Introduced by CMake 3.4, Removed by CMake 4.0 +------------------------------------------------------ .. toctree:: :maxdepth: 1 @@ -361,8 +376,10 @@ Policies Introduced by CMake 3.4 CMP0065: Do not add flags to export symbols from executables without the ENABLE_EXPORTS target property. CMP0064: Support new TEST if() operator. -Policies Introduced by CMake 3.3 -================================ +.. _`Policies Introduced by CMake 3.3`: + +Policies Introduced by CMake 3.3, Removed by CMake 4.0 +------------------------------------------------------ .. toctree:: :maxdepth: 1 @@ -375,8 +392,10 @@ Policies Introduced by CMake 3.3 CMP0058: Ninja requires custom command byproducts to be explicit. CMP0057: Support new IN_LIST if() operator. -Policies Introduced by CMake 3.2 -================================ +.. _`Policies Introduced by CMake 3.2`: + +Policies Introduced by CMake 3.2, Removed by CMake 4.0 +------------------------------------------------------ .. toctree:: :maxdepth: 1 @@ -384,8 +403,10 @@ Policies Introduced by CMake 3.2 CMP0056: Honor link flags in try_compile() source-file signature. CMP0055: Strict checking for break() command. -Policies Introduced by CMake 3.1 -================================ +.. _`Policies Introduced by CMake 3.1`: + +Policies Introduced by CMake 3.1, Removed by CMake 4.0 +------------------------------------------------------ .. toctree:: :maxdepth: 1 @@ -395,8 +416,10 @@ Policies Introduced by CMake 3.1 CMP0052: Reject source and build dirs in installed INTERFACE_INCLUDE_DIRECTORIES. CMP0051: List TARGET_OBJECTS in SOURCES target property. -Policies Introduced by CMake 3.0 -================================ +.. _`Policies Introduced by CMake 3.0`: + +Policies Introduced by CMake 3.0, Removed by CMake 4.0 +------------------------------------------------------ .. toctree:: :maxdepth: 1 @@ -429,8 +452,10 @@ Policies Introduced by CMake 3.0 CMP0025: Compiler id for Apple Clang is now AppleClang. CMP0024: Disallow include export result. -Policies Introduced by CMake 2.8 -================================ +.. _`Policies Introduced by CMake 2.8`: + +Policies Introduced by CMake 2.8, Removed by CMake 4.0 +------------------------------------------------------ .. toctree:: :maxdepth: 1 @@ -448,8 +473,10 @@ Policies Introduced by CMake 2.8 CMP0013: Duplicate binary directories are not allowed. CMP0012: if() recognizes numbers and boolean constants. -Policies Introduced by CMake 2.6 -================================ +.. _`Policies Introduced by CMake 2.6`: + +Policies Introduced by CMake 2.6, Removed by CMake 4.0 +------------------------------------------------------ .. toctree:: :maxdepth: 1 -- cgit v0.12 From 3b926b32e32c1e7c7ed423eef25a2262f3f03a5b Mon Sep 17 00:00:00 2001 From: Brad King Date: Mon, 20 Jan 2025 15:57:35 -0500 Subject: Help: Drop CMAKE_MINIMUM_REQUIRED_VERSION from cmake-policies(7) The variable has little role with respect to policies, particularly since introduction of the `...` syntax. Furthermore, any role it may have is primarily in CMake's own modules. --- Help/manual/cmake-policies.7.rst | 4 ---- 1 file changed, 4 deletions(-) diff --git a/Help/manual/cmake-policies.7.rst b/Help/manual/cmake-policies.7.rst index d973c53..3caecbe 100644 --- a/Help/manual/cmake-policies.7.rst +++ b/Help/manual/cmake-policies.7.rst @@ -47,10 +47,6 @@ or the :command:`find_package` command contain a use of :command:`cmake_policy`, that policy setting will not affect the caller by default. Both commands accept an optional ``NO_POLICY_SCOPE`` keyword to control this behavior. -The :variable:`CMAKE_MINIMUM_REQUIRED_VERSION` variable may also be used -to determine whether to report an error on use of deprecated macros or -functions. - Supported Policies ================== -- cgit v0.12 From 60e302a539283133b877f5c5668b69963943a975 Mon Sep 17 00:00:00 2001 From: Brad King Date: Mon, 20 Jan 2025 16:00:20 -0500 Subject: Help: Drop policy scope from cmake-policies(7) The policy stack is covered by the `cmake_policy`, `include`, and `find_package` command documentation. Avoid distracting readers with such details in the main policy introduction. --- Help/manual/cmake-policies.7.rst | 6 ------ 1 file changed, 6 deletions(-) diff --git a/Help/manual/cmake-policies.7.rst b/Help/manual/cmake-policies.7.rst index 3caecbe..89fece6 100644 --- a/Help/manual/cmake-policies.7.rst +++ b/Help/manual/cmake-policies.7.rst @@ -41,12 +41,6 @@ CMake version, the :command:`if(POLICY)` command may be used: This has the effect of using the ``NEW`` behavior with newer CMake releases which users may be using and not issuing a compatibility warning. -The setting of a policy is confined in some cases to not propagate to the -parent scope. For example, if the files read by the :command:`include` command -or the :command:`find_package` command contain a use of :command:`cmake_policy`, -that policy setting will not affect the caller by default. Both commands accept -an optional ``NO_POLICY_SCOPE`` keyword to control this behavior. - Supported Policies ================== -- cgit v0.12 From 085de3987968efc79fb157030d970be7e174fe14 Mon Sep 17 00:00:00 2001 From: Brad King Date: Mon, 20 Jan 2025 16:05:52 -0500 Subject: Help: Document policy transition schedule in cmake-policies(7) Rewrite the introduction of the manual to focus on policies' role in evolution of CMake and how projects should be updated to account for them over time. Issue: #26613 --- Help/manual/cmake-policies.7.rst | 95 +++++++++++++++++++++++++++------------- 1 file changed, 65 insertions(+), 30 deletions(-) diff --git a/Help/manual/cmake-policies.7.rst b/Help/manual/cmake-policies.7.rst index 89fece6..c5ce23b 100644 --- a/Help/manual/cmake-policies.7.rst +++ b/Help/manual/cmake-policies.7.rst @@ -10,36 +10,71 @@ cmake-policies(7) Introduction ============ -Policies in CMake are used to preserve backward compatible behavior -across multiple releases. When a new policy is introduced, newer CMake -versions will begin to warn about the backward compatible behavior. It -is possible to disable the warning by explicitly requesting the OLD, or -backward compatible behavior using the :command:`cmake_policy` command. -It is also possible to request ``NEW``, or non-backward compatible behavior -for a policy, also avoiding the warning. Each policy can also be set to -either ``NEW`` or ``OLD`` behavior explicitly on the command line with the -:variable:`CMAKE_POLICY_DEFAULT_CMP` variable. - -A policy is a deprecation mechanism and not a reliable feature toggle. -A policy should almost never be set to ``OLD``, except to silence warnings -in an otherwise frozen or stable codebase, or temporarily as part of a -larger migration path. The ``OLD`` behavior of each policy is undesirable -and will be replaced with an error condition in a future release. - -The :command:`cmake_minimum_required` command does more than report an -error if a too-old version of CMake is used to build a project. It -also sets all policies introduced in that CMake version or earlier to -``NEW`` behavior. To manage policies without increasing the minimum required -CMake version, the :command:`if(POLICY)` command may be used: - -.. code-block:: cmake - - if(POLICY CMP0990) - cmake_policy(SET CMP0990 NEW) - endif() - -This has the effect of using the ``NEW`` behavior with newer CMake releases which -users may be using and not issuing a compatibility warning. +CMake policies introduce behavior changes while preserving compatibility +for existing project releases. Policies are deprecation mechanisms, not +feature toggles. Each policy documents a deprecated ``OLD`` behavior and +a preferred ``NEW`` behavior. Projects must be updated over time to +use the ``NEW`` behavior, but their existing releases will continue to +work with the ``OLD`` behavior. + +Updating Projects +----------------- + +When policies are newly introduced by a version of CMake, their ``OLD`` +behaviors are immediately deprecated by that version of CMake and later. +Projects should be updated to use the ``NEW`` behaviors of the policies +as soon as possible. + +Use the :command:`cmake_minimum_required` command to record the latest +version of CMake for which a project has been updated. +The ``VERSION ...`` syntax enables the ``NEW`` behaviors +of policies introduced in version ```` and earlier without +increasing the minimum version of CMake required by the project. + +Transition Schedule +------------------- + +To help projects port to the ``NEW`` behaviors of policies on their own +schedule, CMake offers a transition period: + +* If a policy is not set by a project, CMake uses its ``OLD`` behavior, + but may warn that the policy has not been set. + + * Users running CMake may silence the warning without modifying a + project by setting the :variable:`CMAKE_POLICY_DEFAULT_CMP` + variable as a cache entry on the :manual:`cmake(1)` command line: + + .. code-block:: shell + + cmake -DCMAKE_POLICY_DEFAULT_CMP0990=OLD ... + + * Projects may silence the warning by using the :command:`cmake_policy` + command to explicitly set the policy to ``OLD`` or ``NEW`` behavior: + + .. code-block:: cmake + + if(POLICY CMP0990) + cmake_policy(SET CMP0990 NEW) + endif() + + .. note:: + + A policy should almost never be set to ``OLD``, except to silence + warnings in an otherwise frozen or stable codebase, or temporarily + as part of a larger migration path. + +* If a policy is set to ``OLD`` by a project, CMake versions released + at least |POLICY_OLD_DELAY_WARNING| after the version that introduced + a policy may issue a warning that the policy's ``OLD`` behavior will + be removed from a future version of CMake. + +* If a policy is not set to ``NEW`` by a project, CMake versions released + at least |POLICY_OLD_DELAY_ERROR| after the version that introduced a + policy, and whose major version number is higher, may issue an error + that the policy's ``OLD`` behavior has been removed. + +.. |POLICY_OLD_DELAY_WARNING| replace:: 2 years +.. |POLICY_OLD_DELAY_ERROR| replace:: 6 years Supported Policies ================== -- cgit v0.12 From 3e0720a2ae1fbaa595435021f1e37e739f8a1203 Mon Sep 17 00:00:00 2001 From: Brad King Date: Mon, 20 Jan 2025 17:11:27 -0500 Subject: Help: Add cmake_minimum_required(VERSION) example to cmake-policies(7) --- Help/dev/maint.rst | 7 +++++++ Help/manual/cmake-policies.7.rst | 17 ++++++++++++++--- 2 files changed, 21 insertions(+), 3 deletions(-) diff --git a/Help/dev/maint.rst b/Help/dev/maint.rst index 4a6eea8..2f4babc 100644 --- a/Help/dev/maint.rst +++ b/Help/dev/maint.rst @@ -302,6 +302,13 @@ Update ``Source/CMakeVersion.cmake`` to set the version to set(CMake_VERSION_PATCH $date) #set(CMake_VERSION_RC 0) +Update ``Help/manual/cmake-policies.7.rst`` to set the ``...`` +example to ``...$major.$minor``: + +.. code-block:: cmake + + cmake_minimum_required(VERSION 3.10...$major.$minor) + Commit with a message such as:: Begin post-$ver development diff --git a/Help/manual/cmake-policies.7.rst b/Help/manual/cmake-policies.7.rst index c5ce23b..11849b9 100644 --- a/Help/manual/cmake-policies.7.rst +++ b/Help/manual/cmake-policies.7.rst @@ -27,9 +27,20 @@ as soon as possible. Use the :command:`cmake_minimum_required` command to record the latest version of CMake for which a project has been updated. -The ``VERSION ...`` syntax enables the ``NEW`` behaviors -of policies introduced in version ```` and earlier without -increasing the minimum version of CMake required by the project. +For example: + +.. + Sync this cmake_minimum_required example with ``Help/dev/maint.rst``. + +.. code-block:: cmake + + cmake_minimum_required(VERSION 3.10...3.31) + +This uses the ``...`` syntax to enable the ``NEW`` behaviors +of policies introduced in CMake 3.31 and earlier while only requiring a +minimum version of CMake 3.10. The project is expected to work with +both the ``OLD`` and ``NEW`` behaviors of policies introduced between +those versions. Transition Schedule ------------------- -- cgit v0.12