77 lines
2.6 KiB
Diff
77 lines
2.6 KiB
Diff
From 55bf2a34948a01329f075d2da692c0eba49d45f4 Mon Sep 17 00:00:00 2001
|
|
From: Brad King <brad.king@kitware.com>
|
|
Date: Fri, 29 Sep 2023 10:10:39 -0400
|
|
Subject: [PATCH 5/6] Help: Document CMP0124 behavior on already-set variables
|
|
MIME-Version: 1.0
|
|
Content-Type: text/plain; charset=UTF-8
|
|
Content-Transfer-Encoding: 8bit
|
|
|
|
Improve the documentation from commit 46896d98bb (foreach(): loop
|
|
variables are only available in the loop scope, 2021-04-25,
|
|
v3.21.0-rc1~245^2) to follow policy documentation convention.
|
|
|
|
Fixes: #25224
|
|
Inspired-by: Marius Messerschmidt <marius.messerschmidt@googlemail.com>
|
|
Signed-off-by: Björn Esser <besser82@fedoraproject.org>
|
|
---
|
|
Help/policy/CMP0124.rst | 42 ++++++++++++++++++++++++++++++++++++-----
|
|
1 file changed, 37 insertions(+), 5 deletions(-)
|
|
|
|
diff --git a/Help/policy/CMP0124.rst b/Help/policy/CMP0124.rst
|
|
index 3935166ad5..d5cde64d42 100644
|
|
--- a/Help/policy/CMP0124.rst
|
|
+++ b/Help/policy/CMP0124.rst
|
|
@@ -3,12 +3,44 @@ CMP0124
|
|
|
|
.. versionadded:: 3.21
|
|
|
|
-When this policy is set to ``NEW``, the scope of loop variables defined by the
|
|
-:command:`foreach` command is restricted to the loop only. They will be unset
|
|
-at the end of the loop.
|
|
+:command:`foreach` loop variables are only available in the loop scope.
|
|
|
|
-The ``OLD`` behavior for this policy still clears the loop variables at the end
|
|
-of the loop, but does not unset them. This leaves them as defined, but empty.
|
|
+CMake 3.20 and below always leave the loop variable set at the end of the
|
|
+loop, either to the value it had before the loop, if any, or to the empty
|
|
+string. CMake 3.21 and above prefer to leave the loop variable in the
|
|
+state it had before the loop started, either set or unset. This policy
|
|
+provides compatibility for projects that expect the loop variable to always
|
|
+be left set.
|
|
+
|
|
+The ``OLD`` behavior for this policy is to set the loop variable at the
|
|
+end of the loop, either to its original value, or to an empty value.
|
|
+The ``NEW`` behavior for this policy is to restore the loop variable to
|
|
+the state it had before the loop started, either set or unset.
|
|
+
|
|
+For example:
|
|
+
|
|
+.. code-block:: cmake
|
|
+
|
|
+ set(items a b c)
|
|
+
|
|
+ set(var1 "value")
|
|
+ unset(var2)
|
|
+
|
|
+ foreach(var1 IN LISTS items)
|
|
+ endforeach()
|
|
+
|
|
+ foreach(var2 IN LISTS items)
|
|
+ endforeach()
|
|
+
|
|
+ if(DEFINED var1)
|
|
+ message("var1: ${var1}")
|
|
+ endif()
|
|
+ if(DEFINED var2)
|
|
+ message("var2: ${var2}")
|
|
+ endif()
|
|
+
|
|
+Under the ``OLD`` behavior, this code prints ``var1: value`` and ``var2:``.
|
|
+Under the ``NEW`` behavior, this code prints only ``var1: value``.
|
|
|
|
This policy was introduced in CMake version 3.21. Use the
|
|
:command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.
|
|
--
|
|
2.41.0
|
|
|