Merge topic 'foreach-loop-variable'

46896d98bb foreach(): loop variables are only available in the loop scope

Acked-by: Kitware Robot <kwrobot@kitware.com>
Acked-by: Ben Boeckel <ben.boeckel@kitware.com>
Acked-by: Michael Hirsch <michael@scivision.dev>
Merge-request: !6044

4 files changed, 30 insertions, 1 deletions

diff --git a/Help/command/foreach.rst b/Help/command/foreach.rst
index 8de6debae4..d9f54ca750 100644
--- a/Help/command/foreach.rst
+++ b/Help/command/foreach.rst
@@ -14,9 +14,12 @@ semicolon or whitespace.
 All commands between ``foreach`` and the matching ``endforeach`` are recorded
 without being invoked.  Once the ``endforeach`` is evaluated, the recorded
 list of commands is invoked once for each item in ``<items>``.
-At the beginning of each iteration the variable ``loop_var`` will be set
+At the beginning of each iteration the variable ``<loop_var>`` will be set
 to the value of the current item.
 
+The scope of ``<loop_var>`` is restricted to the loop scope. See policy
+:policy:`CMP0124` for details.
+
 The commands :command:`break` and :command:`continue` provide means to
 escape from the normal control flow.
 
diff --git a/Help/manual/cmake-policies.7.rst b/Help/manual/cmake-policies.7.rst
index b41ce59fd1..08449a7159 100644
--- a/Help/manual/cmake-policies.7.rst
+++ b/Help/manual/cmake-policies.7.rst
@@ -57,6 +57,7 @@ Policies Introduced by CMake 3.21
 .. toctree::
    :maxdepth: 1
 
+   CMP0124: foreach() loop variables are only available in the loop scope. </policy/CMP0124>
    CMP0123: ARMClang cpu/arch compile and link flags must be set explicitly. </policy/CMP0123>
    CMP0122: UseSWIG use standard library name conventions for csharp language. </policy/CMP0122>
    CMP0121: The list command detects invalid indicies. </policy/CMP0121>
diff --git a/Help/policy/CMP0124.rst b/Help/policy/CMP0124.rst
new file mode 100644
index 0000000000..88d03e35dd
--- /dev/null
+++ b/Help/policy/CMP0124.rst
@@ -0,0 +1,20 @@
+CMP0124
+-------
+
+.. versionadded:: 3.21
+
+The loop variables created by :command:`foreach` command have now their scope
+restricted to the loop scope.
+
+Starting with CMake 3.21, the :command:`foreach` command ensures that the loop
+variables have their scope restricted to the loop scope.
+
+The ``OLD`` behavior for this policy let the loop variables to exist, with an
+empty value, in the outer scope of loop scope.
+
+This policy was introduced in CMake version 3.21. Use the
+:command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.
+Unlike many policies, CMake version |release| does *not* warn when the policy
+is not set and simply uses ``OLD`` behavior.
+
+.. include:: DEPRECATED.txt
diff --git a/Help/release/dev/foreach-variable-scope.rst b/Help/release/dev/foreach-variable-scope.rst
new file mode 100644
index 0000000000..29a57bbc5f
--- /dev/null
+++ b/Help/release/dev/foreach-variable-scope.rst
@@ -0,0 +1,5 @@
+foreach-variable-scope
+----------------------
+
+* The :command:`foreach` command restrict loop variables to the loop scope.
+  See policy :policy:`CMP0124` for details.