find_*: ensure consistent behavior for cache variables

Fixes: #22121

3 files changed, 32 insertions, 0 deletions

diff --git a/Help/manual/cmake-policies.7.rst b/Help/manual/cmake-policies.7.rst
index a480473..62ccb01 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
 
+   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>
    CMP0122: UseSWIG use standard library name conventions for csharp language. </policy/CMP0122>
diff --git a/Help/policy/CMP0125.rst b/Help/policy/CMP0125.rst
new file mode 100644
index 0000000..19571dc
--- /dev/null
+++ b/Help/policy/CMP0125.rst
@@ -0,0 +1,25 @@
+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.
+
+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/find_item-consistent-behavior.rst b/Help/release/dev/find_item-consistent-behavior.rst
new file mode 100644
index 0000000..43905e7
--- /dev/null
+++ b/Help/release/dev/find_item-consistent-behavior.rst
@@ -0,0 +1,6 @@
+find_item-consistent-behavior
+-----------------------------
+
+* The :command:`find_file`, :command:`find_path`, :command:`find_program`,
+  and :command:`find_library` commands handle cache variables in the same way
+  regardless how they are defined. See policy :policy:`CMP0125` for details.