dilim/CMake
1
0
Fork 0
mirror of https://github.com/Kitware/CMake.git synced 2026-08-04 14:50:23 +00: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`_. ``<min>`` version and sets the `Policy Version`_.
If the running version of CMake is older than 3.12, the extra ``...`` If the running version of CMake is older than 3.12, the extra ``...``
dots will be seen as version component separators, resulting in the dots will be seen as version component separators, resulting in the
``...<max>`` part being ignored and preserving the pre-3.12 behavior ``...<policy_max>`` part being ignored and preserving the pre-3.12
of basing policies on ``<min>``. behavior of basing policies on ``<min>``.
This command will set the value of the This command will set the value of the
:variable:`CMAKE_MINIMUM_REQUIRED_VERSION` variable to ``<min>``. :variable:`CMAKE_MINIMUM_REQUIRED_VERSION` variable to ``<min>``.
@@ -53,11 +53,12 @@ with an error instead of just a warning.
Policy Version Policy Version
^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^
``cmake_minimum_required(VERSION <min>[...<max>])`` implicitly invokes ``cmake_minimum_required(VERSION <min>[...<policy_max>])`` implicitly
invokes
.. code-block:: cmake .. code-block:: cmake
cmake_policy(VERSION <min>[...<max>]) cmake_policy(VERSION <min>[...<policy_max>])
.. include:: include/POLICY_VERSION.rst .. 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 behavior. While setting policies individually is supported, we
encourage projects to set policies based on CMake versions: encourage projects to set policies based on CMake versions:
.. signature:: cmake_policy(VERSION <min>[...<max>]) .. signature:: cmake_policy(VERSION <min>[...<policy_max>])
:target: VERSION :target: VERSION
.. versionadded:: 3.12 .. versionadded:: 3.12
The optional ``<max>`` version. The optional ``<policy_max>`` version.
``<min>`` and the optional ``<max>`` are each CMake versions of the form ``<min>`` and the optional ``<policy_max>`` are each CMake versions of the
``major.minor[.patch[.tweak]]``, and the ``...`` is literal. The ``<min>`` form ``major.minor[.patch[.tweak]]``, and the ``...`` is literal.
version must be at least ``2.4`` and at most the running version of CMake. The ``<min>`` version must be at least ``2.4`` and at most the running
The ``<max>`` version, if specified, must be at least the ``<min>`` version version of CMake. The ``<policy_max>`` version, if specified, must be at
but may exceed the running version of CMake. If the running version of least the ``<min>`` version but may exceed the running version of CMake.
CMake is older than 3.12, the extra ``...`` dots will be seen as version If the running version of CMake is older than 3.12, the extra ``...``
component separators, resulting in the ``...<max>`` part being ignored and dots will be seen as version component separators, resulting in the
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>``.
.. include:: include/POLICY_VERSION.rst .. 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. Compatibility with versions of CMake older than 3.5 is removed.
Calls to :command:`cmake_minimum_required(VERSION)` or Calls to :command:`cmake_minimum_required(VERSION)` or
:command:`cmake_policy(VERSION)` that do not specify at least :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. will produce an error in CMake 4.0 and above.
.. versionchanged:: 3.31 .. versionchanged:: 3.31
@@ -11,7 +11,7 @@
Compatibility with versions of CMake older than 3.10 is deprecated. Compatibility with versions of CMake older than 3.10 is deprecated.
Calls to :command:`cmake_minimum_required(VERSION)` or Calls to :command:`cmake_minimum_required(VERSION)` or
:command:`cmake_policy(VERSION)` that do not specify at least :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. will produce a deprecation warning in CMake 3.31 and above.
.. versionchanged:: 3.27 .. versionchanged:: 3.27
@@ -19,7 +19,7 @@
Compatibility with versions of CMake older than 3.5 is deprecated. Compatibility with versions of CMake older than 3.5 is deprecated.
Calls to :command:`cmake_minimum_required(VERSION)` or Calls to :command:`cmake_minimum_required(VERSION)` or
:command:`cmake_policy(VERSION)` that do not specify at least :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. will produce a deprecation warning in CMake 3.27 and above.
.. versionchanged:: 3.19 .. versionchanged:: 3.19
@@ -27,5 +27,5 @@
Compatibility with versions of CMake older than 2.8.12 is deprecated. Compatibility with versions of CMake older than 2.8.12 is deprecated.
Calls to :command:`cmake_minimum_required(VERSION)` or Calls to :command:`cmake_minimum_required(VERSION)` or
:command:`cmake_policy(VERSION)` that do not specify at least :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. 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 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 ``<min>`` version, or to
* the value of the :variable:`CMAKE_POLICY_VERSION_MINIMUM` variable * the value of the :variable:`CMAKE_POLICY_VERSION_MINIMUM` variable
if it is higher than the other two versions. 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). :variable:`CMAKE_POLICY_DEFAULT_CMP<NNNN>` variable sets a default).
This effectively requests behavior preferred as of a given CMake This effectively requests behavior preferred as of a given CMake
version and tells newer CMake versions to warn about their new policies. 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.

2
Help/dev/maint.rst
View File

@@ -302,7 +302,7 @@ Update ``Source/CMakeVersion.cmake`` to set the version to
set(CMake_VERSION_PATCH $date) set(CMake_VERSION_PATCH $date)
#set(CMake_VERSION_RC 0) #set(CMake_VERSION_RC 0)
Update ``Help/manual/cmake-policies.7.rst`` to set the ``...<max>`` Update ``Help/manual/cmake-policies.7.rst`` to set the ``...<policy_max>``
example to ``...$major.$minor``: example to ``...$major.$minor``:
.. code-block:: cmake .. code-block:: cmake

2
Help/manual/cmake-policies.7.rst
View File

@@ -38,7 +38,7 @@ For example:
cmake_minimum_required(VERSION 3.10...4.2) cmake_minimum_required(VERSION 3.10...4.2)
This uses the ``<min>...<max>`` syntax to enable the ``NEW`` behaviors This uses the ``<min>...<policy_max>`` syntax to enable the ``NEW`` behaviors
of policies introduced in CMake 4.2 and earlier while only requiring a of policies introduced in CMake 4.2 and earlier while only requiring a
minimum version of CMake 3.10. The project is expected to work with minimum version of CMake 3.10. The project is expected to work with
both the ``OLD`` and ``NEW`` behaviors of policies introduced between both the ``OLD`` and ``NEW`` behaviors of policies introduced between