Merge topic 'doc-policies-3.21' into release-3.21

7b5fa0f7 Help: Make policy CMP0126 wording more accurate
c4bc250f Help: Explain policy CMP0125 in more detail
6d5f74fc Help: Clarify wording of CMP0124

Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !6360

Help/policy/CMP0077.rst

@@ -46,6 +46,10 @@ name:
   variable of the same name exists.  The normal variable is not removed.
   The cache entry is not created or updated and is ignored if it exists.
 
+See :policy:`CMP0126` for a similar policy for the :command:`set(CACHE)`
+command, but note that there are some differences in ``NEW`` behavior
+between the two policies.
+
 This policy was introduced in CMake version 3.13.  CMake version
 |release| warns when the policy is not set and uses ``OLD`` behavior.
 Use the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW``

Help/policy/CMP0124.rst

@@ -3,14 +3,12 @@ CMP0124
 
 .. versionadded:: 3.21
 
-The loop variables created by :command:`foreach` command have now their scope
-restricted to the loop scope.
+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.
 
-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.
+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.
 
 This policy was introduced in CMake version 3.21. Use the
 :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.

Help/policy/CMP0125.rst

@@ -4,18 +4,35 @@ CMP0125
 .. versionadded:: 3.21
 
 The :command:`find_file`, :command:`find_path`, :command:`find_library` and
-:command:`find_program` commands handle cache variables in the same way
-regardless of whether they are defined on the command line, with or without a
-type, or using the :command:`set` command.
-
-Starting with CMake 3.21, the :command:`find_file`, :command:`find_path`,
-:command:`find_library`, and :command:`find_program` commands ensure that the
-cache variables will be used in the same way regardless how they were defined
-and the result will be always successful if the searched artifact exists.
-
-The ``OLD`` behavior for this policy is to have the find commands' behaviors
-differ depending on how the cache variable is defined. The ``NEW`` behavior for
-this policy is to have consistent behavior.
+:command:`find_program` commands cache their result in the variable specified
+by their first argument.  Prior to CMake 3.21, if a cache variable of that
+name already existed before the call but the cache variable had no type, any
+non-cache variable of the same name would be discarded and the cache variable
+was always used (see also :policy:`CMP0126` for a different but similar
+behavior).  This contradicts the convention that a non-cache variable should
+take precedence over a cache variable of the same name.  Such a situation can
+arise if a user sets a cache variable on the command line without specifying
+a type, such as ``cmake -DMYVAR=blah ...`` instead of
+``cmake -DMYVAR:FILEPATH=blah``.
+
+Related to the above, if a cache variable of the specified name already exists
+and it *does* have a type, the various ``find_...()`` commands would return
+that value unchanged.  In particular, if it contained a relative path, it
+would not be converted to an absolute path in this situation.
+
+When policy ``CMP0125`` is set to ``OLD`` or is unset, the behavior is as
+described above.  When it is set to ``NEW``, the behavior is as follows:
+
+* If a non-cache variable of the specified name exists when the ``find_...()``
+  command is called, its value will be used regardless of whether a cache
+  variable of the same name already exists or not.  A cache variable will not
+  be created in this case if no such cache variable existed before.
+  If a cache variable of the specified name did already exist, the cache will
+  be updated to match the non-cache variable.
+
+* The various ``find...()`` commands will always provide an absolute path in
+  the result variable, except where a relative path provided by a cache or
+  non-cache variable cannot be resolved to an existing path.
 
 This policy was introduced in CMake version 3.21. Use the
 :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.

Help/policy/CMP0126.rst

@@ -3,16 +3,25 @@ CMP0126
 
 .. versionadded:: 3.21
 
-The :command:`set(CACHE)` does not remove a normal variable of the same name.
+When this policy is set to ``NEW``, the :command:`set(CACHE)` command does not
+remove any normal variable of the same name from the current scope.
+The ``OLD`` behavior removes any normal variable of the same name from the
+current scope in the following situations:
 
-Starting with CMake 3.21, the :command:`set(CACHE)` does not remove, in the
-current scope, any normal variable with the same name.
+* No cache variable of that name existed previously.
 
-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.
+* A cache variable of that name existed previously, but it had no type.
+  This can occur when the variable was set on the command line using a form
+  like ``cmake -DMYVAR=blah`` instead of ``cmake -DMYVAR:STRING=blah``.
 
-This policy was introduced in CMake version 3.21. Use the
+Note that the ``NEW`` behavior has an important difference to the similar
+``NEW`` behavior of policy :policy:`CMP0077`.  The :command:`set(CACHE)`
+command always sets the cache variable if it did not exist previously,
+regardless of the ``CMP0126`` policy setting.  The :command:`option` command
+will *not* set the cache variable if a non-cache variable of the same name
+already exists and :policy:`CMP0077` is set to ``NEW``.
+
+Policy ``CMP0126`` 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.  See documentation of the