diff --git a/Help/command/cmake_minimum_required.rst b/Help/command/cmake_minimum_required.rst index 98861f9293..1eaba0c426 100644 --- a/Help/command/cmake_minimum_required.rst +++ b/Help/command/cmake_minimum_required.rst @@ -22,8 +22,8 @@ The optional ```` version, if specified, must be at least the ```` 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 -``...`` part being ignored and preserving the pre-3.12 behavior -of basing policies on ````. +``...`` part being ignored and preserving the pre-3.12 +behavior of basing policies on ````. This command will set the value of the :variable:`CMAKE_MINIMUM_REQUIRED_VERSION` variable to ````. @@ -53,11 +53,12 @@ with an error instead of just a warning. Policy Version ^^^^^^^^^^^^^^ -``cmake_minimum_required(VERSION [...])`` implicitly invokes +``cmake_minimum_required(VERSION [...])`` implicitly +invokes .. code-block:: cmake - cmake_policy(VERSION [...]) + cmake_policy(VERSION [...]) .. include:: include/POLICY_VERSION.rst diff --git a/Help/command/cmake_policy.rst b/Help/command/cmake_policy.rst index bbec8e63ea..5be074c791 100644 --- a/Help/command/cmake_policy.rst +++ b/Help/command/cmake_policy.rst @@ -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 [...]) +.. signature:: cmake_policy(VERSION [...]) :target: VERSION .. versionadded:: 3.12 - The optional ```` version. + The optional ```` version. -```` and the optional ```` are each CMake versions of the form -``major.minor[.patch[.tweak]]``, and the ``...`` is literal. The ```` -version must be at least ``2.4`` and at most the running version of CMake. -The ```` version, if specified, must be at least the ```` 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 ``...`` part being ignored and -preserving the pre-3.12 behavior of basing policies on ````. +```` and the optional ```` are each CMake versions of the +form ``major.minor[.patch[.tweak]]``, and the ``...`` is literal. +The ```` version must be at least ``2.4`` and at most the running +version of CMake. The ```` version, if specified, must be at +least the ```` 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 +``...`` part being ignored and preserving the pre-3.12 behavior +of basing policies on ````. .. include:: include/POLICY_VERSION.rst diff --git a/Help/command/include/DEPRECATED_POLICY_VERSIONS.rst b/Help/command/include/DEPRECATED_POLICY_VERSIONS.rst index 1b9f0d4d6d..dd4a10411e 100644 --- a/Help/command/include/DEPRECATED_POLICY_VERSIONS.rst +++ b/Help/command/include/DEPRECATED_POLICY_VERSIONS.rst @@ -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 ``...``) + 3.5 as their policy version (optionally via ``...``) 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 ``...``) + 3.10 as their policy version (optionally via ``...``) 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 ``...``) + 3.5 as their policy version (optionally via ``...``) 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 ``...``) + 2.8.12 as their policy version (optionally via ``...``) will produce a deprecation warning in CMake 3.19 and above. diff --git a/Help/command/include/POLICY_VERSION.rst b/Help/command/include/POLICY_VERSION.rst index 424849d60a..08c6afc848 100644 --- a/Help/command/include/POLICY_VERSION.rst +++ b/Help/command/include/POLICY_VERSION.rst @@ -1,7 +1,7 @@ This specifies that the current CMake code is written for the given range of -CMake versions, ``[...]``. It sets the "policy version" to: +CMake versions, ``[...]``. It sets the "policy version" to: -* the range's ```` version, if specified, or to +* the range's ```` version, if specified, or to * the ```` 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` 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:: + + ``...`` 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. diff --git a/Help/dev/maint.rst b/Help/dev/maint.rst index 33408c0595..787cd23f6f 100644 --- a/Help/dev/maint.rst +++ b/Help/dev/maint.rst @@ -302,7 +302,7 @@ 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 ``...`` +Update ``Help/manual/cmake-policies.7.rst`` to set the ``...`` example to ``...$major.$minor``: .. code-block:: cmake diff --git a/Help/manual/cmake-policies.7.rst b/Help/manual/cmake-policies.7.rst index 97d74ba6c6..7395adb956 100644 --- a/Help/manual/cmake-policies.7.rst +++ b/Help/manual/cmake-policies.7.rst @@ -38,7 +38,7 @@ For example: cmake_minimum_required(VERSION 3.10...4.2) -This uses the ``...`` syntax to enable the ``NEW`` behaviors +This uses the ``...`` syntax to enable the ``NEW`` behaviors 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 both the ``OLD`` and ``NEW`` behaviors of policies introduced between