Merge topic 'set-cache-keep-normal-variable'

d96eb55282 set(CACHE): do not remove normal variable

Acked-by: Kitware Robot <kwrobot@kitware.com>
Reviewed-by: Ben Boeckel <ben.boeckel@kitware.com>
Merge-request: !6146

Help/command/set.rst

@@ -68,9 +68,13 @@ users.
 
 If the cache entry does not exist prior to the call or the ``FORCE``
 option is given then the cache entry will be set to the given value.
-Furthermore, any normal variable binding in the current scope will
-be removed to expose the newly cached value to any immediately
-following evaluation.
+
+.. note::
+
+  The content of the cache variable will not be directly accessible if a normal
+  variable of the same name already exists (see :ref:`rules of variable
+  evaluation <CMake Language Variables>`). If policy :policy:`CMP0126` is set
+  to ``OLD``, any normal variable binding in the current scope will be removed.
 
 It is possible for the cache entry to exist prior to the call but
 have no type set if it was created on the :manual:`cmake(1)` command

Help/manual/cmake-policies.7.rst

@@ -57,6 +57,7 @@ Policies Introduced by CMake 3.21
 .. toctree::
    :maxdepth: 1
 
+   CMP0126: set(CACHE) does not remove a normal variable of the same name. </policy/CMP0126>
    CMP0125: find_(path|file|library|program) have consistent behavior for cache variables. </policy/CMP0125>
    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>

Help/policy/CMP0126.rst

@@ -0,0 +1,20 @@
+CMP0126
+-------
+
+.. versionadded:: 3.21
+
+The :command:`set(CACHE)` does not remove a normal variable of the same name.
+
+Starting with CMake 3.21, the :command:`set(CACHE)` does not remove, in the
+current scope, any normal variable with the same name.
+
+The ``OLD`` behavior for this policy is to have the :command:`set(CACHE)`
+command removing the normal variable of the same name, if any. The ``NEW``
+behavior for this policy is to keep the normal variable of the same name.
+
+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

Help/release/dev/set-cache-variable.rst

@@ -0,0 +1,5 @@
+set-cache-variable
+------------------
+
+* The :command:`set(CACHE)` command no longer removes a normal variable of the
+  same name, if any. See policy :policy:`CMP0126`.