find_package: Use <PACKAGENAME>_ROOT variables as search prefixes

Extend commit eb35d8884b (find_package: Use PackageName_ROOT variables
as search prefixes, 2018-03-15, v3.12.0-rc1~349^2) to also check
upper-case `<PACKAGENAME>_ROOT` variables.  Add policy `CMP0144` to
enable the behavior in a compatible way.

Fixes: #24403

1 files changed, 26 insertions, 0 deletions

diff --git a/Help/policy/CMP0144.rst b/Help/policy/CMP0144.rst
new file mode 100644
index 0000000000..3959d96142
--- /dev/null
+++ b/Help/policy/CMP0144.rst
@@ -0,0 +1,26 @@
+CMP0144
+-------
+
+.. versionadded:: 3.27
+
+:command:`find_package` uses upper-case ``<PACKAGENAME>_ROOT`` variables.
+
+In CMake 3.27 and above the :command:`find_package(<PackageName>)` command now
+searches prefixes specified by the upper-case :variable:`<PACKAGENAME>_ROOT`
+CMake variable and the :envvar:`<PACKAGENAME>_ROOT` environment variable
+in addition to the case-preserved :variable:`<PackageName>_ROOT` and
+:envvar:`<PackageName>_ROOT` variables used since policy :policy:`CMP0074`.
+This policy provides compatibility with projects that have not been
+updated to avoid using ``<PACKAGENAME>_ROOT`` variables for other purposes.
+
+The ``OLD`` behavior for this policy is to ignore ``<PACKAGENAME>_ROOT``
+variables if the original ``<PackageName>`` has lower-case characters.
+The ``NEW`` behavior for this policy is to use ``<PACKAGENAME>_ROOT``
+variables.
+
+This policy was introduced in CMake version 3.27.  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``
+explicitly.
+
+.. include:: DEPRECATED.txt