mirror/CMake
1
0
Fork 0
mirror of https://github.com/Kitware/CMake.git synced 2026-01-07 22:30:13 -06:00
Code Issues Packages Projects Releases Wiki Activity

Help: Be more explicit about what ...<policy_max> does not mean

Browse Source 
Also use `<policy_max>` more consistently in signatures.
This commit is contained in:
ferdymercury
2025-11-23 04:43:55 -05:00
committed by Brad King
parent 33a4a3c43a
commit 7323fbd65e
6 changed files with 30 additions and 22 deletions
Download Patch File Download Diff File Expand all files Collapse all files

9
Help/command/cmake_minimum_required.rst
View File

@@ -22,8 +22,8 @@ The optional ``<policy_max>`` version, if specified, must be at least the
``<min>`` version and sets the `Policy Version`_.
If the running version of CMake is older than 3.12, the extra ``...``
dots will be seen as version component separators, resulting in the
``...<max>`` part being ignored and preserving the pre-3.12 behavior
of basing policies on ``<min>``.
``...<policy_max>`` part being ignored and preserving the pre-3.12
behavior of basing policies on ``<min>``.
This command will set the value of the
:variable:`CMAKE_MINIMUM_REQUIRED_VERSION` variable to ``<min>``.
@@ -53,11 +53,12 @@ with an error instead of just a warning.
Policy Version
^^^^^^^^^^^^^^
``cmake_minimum_required(VERSION <min>[...<max>])`` implicitly invokes
``cmake_minimum_required(VERSION <min>[...<policy_max>])`` implicitly
invokes
.. code-block:: cmake
cmake_policy(VERSION <min>[...<max>])
cmake_policy(VERSION <min>[...<policy_max>])
.. include:: include/POLICY_VERSION.rst

21
Help/command/cmake_policy.rst
View File

@@ -24,20 +24,21 @@ The ``cmake_policy`` command is used to set policies to ``OLD`` or ``NEW``
behavior. While setting policies individually is supported, we
encourage projects to set policies based on CMake versions:
.. signature:: cmake_policy(VERSION <min>[...<max>])
.. signature:: cmake_policy(VERSION <min>[...<policy_max>])
:target: VERSION
.. versionadded:: 3.12
The optional ``<max>`` version.
The optional ``<policy_max>`` version.
``<min>`` and the optional ``<max>`` are each CMake versions of the form
``major.minor[.patch[.tweak]]``, and the ``...`` is literal. The ``<min>``
version must be at least ``2.4`` and at most the running version of CMake.
The ``<max>`` version, if specified, must be at least the ``<min>`` version
but may exceed the running version of CMake. If the running version of
CMake is older than 3.12, the extra ``...`` dots will be seen as version
component separators, resulting in the ``...<max>`` part being ignored and
preserving the pre-3.12 behavior of basing policies on ``<min>``.
``<min>`` and the optional ``<policy_max>`` are each CMake versions of the
form ``major.minor[.patch[.tweak]]``, and the ``...`` is literal.
The ``<min>`` version must be at least ``2.4`` and at most the running
version of CMake. The ``<policy_max>`` version, if specified, must be at
least the ``<min>`` version but may exceed the running version of CMake.
If the running version of CMake is older than 3.12, the extra ``...``
dots will be seen as version component separators, resulting in the
``...<policy_max>`` part being ignored and preserving the pre-3.12 behavior
of basing policies on ``<min>``.
.. include:: include/POLICY_VERSION.rst

8
Help/command/include/DEPRECATED_POLICY_VERSIONS.rst
View File

@@ -3,7 +3,7 @@
Compatibility with versions of CMake older than 3.5 is removed.
Calls to :command:`cmake_minimum_required(VERSION)` or
:command:`cmake_policy(VERSION)` that do not specify at least
3.5 as their policy version (optionally via ``...<max>``)
3.5 as their policy version (optionally via ``...<policy_max>``)
will produce an error in CMake 4.0 and above.
.. versionchanged:: 3.31
@@ -11,7 +11,7 @@
Compatibility with versions of CMake older than 3.10 is deprecated.
Calls to :command:`cmake_minimum_required(VERSION)` or
:command:`cmake_policy(VERSION)` that do not specify at least
3.10 as their policy version (optionally via ``...<max>``)
3.10 as their policy version (optionally via ``...<policy_max>``)
will produce a deprecation warning in CMake 3.31 and above.
.. versionchanged:: 3.27
@@ -19,7 +19,7 @@
Compatibility with versions of CMake older than 3.5 is deprecated.
Calls to :command:`cmake_minimum_required(VERSION)` or
:command:`cmake_policy(VERSION)` that do not specify at least
3.5 as their policy version (optionally via ``...<max>``)
3.5 as their policy version (optionally via ``...<policy_max>``)
will produce a deprecation warning in CMake 3.27 and above.
.. versionchanged:: 3.19
@@ -27,5 +27,5 @@
Compatibility with versions of CMake older than 2.8.12 is deprecated.
Calls to :command:`cmake_minimum_required(VERSION)` or
:command:`cmake_policy(VERSION)` that do not specify at least
2.8.12 as their policy version (optionally via ``...<max>``)
2.8.12 as their policy version (optionally via ``...<policy_max>``)
will produce a deprecation warning in CMake 3.19 and above.

10
Help/command/include/POLICY_VERSION.rst
View File

@@ -1,7 +1,7 @@
This specifies that the current CMake code is written for the given range of
CMake versions, ``<min>[...<max>]``. It sets the "policy version" to:
CMake versions, ``<min>[...<policy_max>]``. It sets the "policy version" to:
* the range's ``<max>`` version, if specified, or to
* the range's ``<policy_max>`` version, if specified, or to
* the ``<min>`` version, or to
* the value of the :variable:`CMAKE_POLICY_VERSION_MINIMUM` variable
if it is higher than the other two versions.
@@ -14,3 +14,9 @@ All policies introduced in later versions will be unset (unless the
:variable:`CMAKE_POLICY_DEFAULT_CMP<NNNN>` 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.
.. note::
``...<policy_max>`` does *not* signify that later CMake versions are
forbidden. It merely specifies the highest CMake version for which
the project or module has been actively updated and maintained.