cmake/0005-Help-Document-CMP0124-behavior-on-already-set-variab.patch

77 lines
2.6 KiB
Diff
Raw Normal View History

2023-10-03 14:32:06 +00:00
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