CMakeDependentOption: Introduce policy CMP0127 for full Condition Syntax

Fixes: #22303

3 files changed, 46 insertions, 0 deletions

diff --git a/Help/manual/cmake-policies.7.rst b/Help/manual/cmake-policies.7.rst
index b9e3d45..0f0c0ab 100644
--- a/Help/manual/cmake-policies.7.rst
+++ b/Help/manual/cmake-policies.7.rst
@@ -51,6 +51,14 @@ 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.
 
+Policies Introduced by CMake 3.22
+=================================
+
+.. toctree::
+   :maxdepth: 1
+
+   CMP0127: cmake_dependent_option() supports full Condition Syntax. </policy/CMP0127>
+
 Policies Introduced by CMake 3.21
 =================================
 
diff --git a/Help/policy/CMP0127.rst b/Help/policy/CMP0127.rst
new file mode 100644
index 0000000..8560bbf
--- /dev/null
+++ b/Help/policy/CMP0127.rst
@@ -0,0 +1,32 @@
+CMP0127
+-------
+
+:command:`cmake_dependent_option` supports full :ref:`Condition Syntax`.
+
+The ``<depends>`` parameter accepts a :ref:`semicolon-separated list <CMake
+Language Lists>` of conditions.  CMake 3.21 and lower evaluates each
+``condition`` as ``if(${condition})``, which does not properly handle
+conditions with nested paren groups.  CMake 3.22 and above instead prefer
+to evaluate each ``condition`` as ``if(<condition>)``, where ``<condition>``
+is re-parsed as if literally written in a call to :command:`if`.  This
+allows expressions like::
+
+  "A AND (B OR C)"
+
+but requires expressions like::
+
+  "FOO MATCHES (UPPER|lower)"
+
+to be re-written as::
+
+  "FOO MATCHES \"(UPPER|lower)\""
+
+Policy ``CMP0127`` provides compatibility for projects that have not
+been updated to expect the new behavior.
+
+This policy was introduced in CMake version 3.22.  CMake version
+|release| warns when the policy is not set and uses ``OLD`` behavior.
+Use the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW``
+explicitly.
+
+.. include:: DEPRECATED.txt
diff --git a/Help/release/dev/cmake_dependent_option_policy.rst b/Help/release/dev/cmake_dependent_option_policy.rst
new file mode 100644
index 0000000..c131170
--- /dev/null
+++ b/Help/release/dev/cmake_dependent_option_policy.rst
@@ -0,0 +1,6 @@
+cmake_dependent_option_policy
+-----------------------------
+
+* The :module:`CMakeDependentOption` module :command:`cmake_dependent_option`
+  macro now supports full :ref:`Condition Syntax`.
+  See policy :policy:`CMP0127`.