cmake_minimum_required: Optionally set policies with version range

Teach `cmake_minimum_required` and `cmake_policy(VERSION)` to support a
version range of the form `<min>[...<max>]`.  Define this to mean that
version `<min>` is required, but known policies up to those introduced
by `<max>` will be set to `NEW`.  This will allow projects to easily
specify a range of versions for which they have been updated.

Help/command/cmake_minimum_required.rst

@@ -4,11 +4,15 @@ cmake_minimum_required
 Set the minimum required version of cmake for a project and
 update `Policy Settings`_ to match the version given::
 
-  cmake_minimum_required(VERSION major.minor[.patch[.tweak]]
-                         [FATAL_ERROR])
+  cmake_minimum_required(VERSION <min>[...<max>] [FATAL_ERROR])
 
-If the current version of CMake is lower than that required it will
-stop processing the project and report an error.
+``<min>`` and the optional ``<max>`` are each CMake versions of the form
+``major.minor[.patch[.tweak]]``, and the ``...`` is literal.
+
+If the running version of CMake is lower than the ``<min>`` required
+version it will stop processing the project and report an error.
+The optional ``<max>`` version, if specified, must be at least the
+``<min>`` version and affects policy settings as described below.
 
 The ``FATAL_ERROR`` option is accepted but ignored by CMake 2.6 and
 higher.  It should be specified so CMake versions 2.4 and lower fail
@@ -30,21 +34,23 @@ Policy Settings
 
 The ``cmake_minimum_required(VERSION)`` command implicitly invokes the
 :command:`cmake_policy(VERSION)` command to specify that the current
-project code is written for the given version of CMake.
-All policies introduced in the specified version or earlier will be
-set to use NEW behavior.  All policies introduced after the specified
-version will be unset.  This effectively requests behavior preferred
+project code is written for the given range of CMake versions.
+All policies known to the running version of CMake and introduced
+in the ``<min>`` (or ``<max>``, 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.
 
-When a version higher than 2.4 is specified the command implicitly
+When a ``<min>`` version higher than 2.4 is specified the command
+implicitly invokes::
+
+  cmake_policy(VERSION <min>[...<max>])
+
+which sets CMake policies based on the range of versions specified.
+When a ``<min>`` version 2.4 or lower is given the command implicitly
 invokes::
 
-  cmake_policy(VERSION major[.minor[.patch[.tweak]]])
-
-which sets the cmake policy version level to the version specified.
-When version 2.4 or lower is given the command implicitly invokes::
-
-  cmake_policy(VERSION 2.4)
+  cmake_policy(VERSION 2.4[...<max>])
 
 which enables compatibility features for CMake 2.4 and lower.

Help/command/cmake_policy.rst

@@ -24,17 +24,22 @@ 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::
 
-  cmake_policy(VERSION major.minor[.patch[.tweak]])
+  cmake_policy(VERSION <min>[...<max>])
 
-Specify that the current CMake code is written for the given
-version of CMake.  All policies introduced in the specified version or
-earlier will be set to use ``NEW`` behavior.  All policies introduced
-after the specified version will be unset (unless the
+``<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.
+
+This specifies that the current CMake code is written for the given
+range of CMake versions.  All policies known to the running version of CMake
+and introduced in the ``<min>`` (or ``<max>``, if specified) version
+or earlier will be set to use ``NEW`` behavior.  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.
-The policy version specified must be at least 2.4 or the command will
-report an error.
 
 Note that the :command:`cmake_minimum_required(VERSION)`
 command implicitly calls ``cmake_policy(VERSION)`` too.

Help/release/dev/policy-version-range.rst

@@ -0,0 +1,8 @@
+policy-version-range
+--------------------
+
+* The :command:`cmake_minimum_required` and :command:`cmake_policy(VERSION)`
+  commands now accept a version range using the form ``<min>[...<max>]``.
+  The ``<min>`` version is required but policies are set based on the
+  ``<max>`` version.  This allows projects to specify a range of versions
+  for which they have been updated and avoid explicit policy settings.

Help/variable/CMAKE_MINIMUM_REQUIRED_VERSION.rst

@@ -1,7 +1,5 @@
 CMAKE_MINIMUM_REQUIRED_VERSION
 ------------------------------
 
-Version specified to :command:`cmake_minimum_required` command
-
-Variable containing the ``VERSION`` component specified in the
-:command:`cmake_minimum_required` command.
+The ``<min>`` version of CMake given to the most recent call to the
+:command:`cmake_minimum_required(VERSION)` command.