set(CACHE): do not remove normal variable

Fixes: #22038

4 files changed, 33 insertions, 3 deletions

diff --git a/Help/command/set.rst b/Help/command/set.rst
index c0e02e2..af862e4 100644
--- a/Help/command/set.rst
+++ b/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
diff --git a/Help/manual/cmake-policies.7.rst b/Help/manual/cmake-policies.7.rst
index 62ccb01..b9e3d45 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
 
+   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>
diff --git a/Help/policy/CMP0126.rst b/Help/policy/CMP0126.rst
new file mode 100644
index 0000000..4c8e928
--- /dev/null
+++ b/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
diff --git a/Help/release/dev/set-cache-variable.rst b/Help/release/dev/set-cache-variable.rst
new file mode 100644
index 0000000..a96242c
--- /dev/null
+++ b/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`.