find_(library|file|path): Drop PATH-derived search prefixes

Since commit ffc06c1239 (Teach find_(library|file|path) to get prefixes
from PATH, 2015-02-18, v3.3.0-rc1~430^2) we search in `<prefix>/include`
and `<prefix>/lib` directories for prefixes with `bin` directories in
the `PATH` environment variable.  The motivation was to search the
installation prefixes of MSYS and MinGW development environments
automatically.

This behavior can search undesired prefixes that happen to be in the
`PATH` for unrelated reasons.  It was reverted for non-Windows hosts
within a year by commit b30b32a493 (Drop find_(library|file|path)
prefixes from PATH on non-Windows, 2016-05-09, v3.6.0-rc1~82^2) but was
kept on Windows hosts to support its motivating use case.  However,
similar problems have since been observed on Windows.  For example,
commit 955d6245c1 (MSVC: Revert "Teach find_library to consider the
'libfoo.a' naming convention", 2022-11-28, v3.25.1~6^2) was primarily
due to undesired discovery of libraries in `PATH`-derived prefixes.

Since commit 5e5132e1b1 (MinGW: Search for packages in standard MSYSTEM
environment prefixes, 2023-09-11) we search MSYS and MinGW environments'
prefixes explicitly, so `PATH`-derived prefixes are no longer needed for
the original motivating use case.

Fixes: #24216

1 files changed, 17 insertions, 0 deletions

diff --git a/Help/release/dev/find-windows-no-PATH-prefixes.rst b/Help/release/dev/find-windows-no-PATH-prefixes.rst
new file mode 100644
index 0000000..b65c00b
--- /dev/null
+++ b/Help/release/dev/find-windows-no-PATH-prefixes.rst
@@ -0,0 +1,17 @@
+find-windows-no-PATH-prefixes
+-----------------------------
+
+* The :command:`find_library`, :command:`find_path`, and :command:`find_file`
+  commands no longer search in installation prefixes derived from the ``PATH``
+  environment variable.  This behavior was added in CMake 3.3 to support
+  MSYS and MinGW (``MSYSTEM``) development environments on Windows, but
+  it can search undesired prefixes that happen to be in the ``PATH`` for
+  unrelated reasons.  Users that keep some ``<prefix>/bin`` directories in
+  the ``PATH`` just for their tools do not necessarily want any corresponding
+  ``<prefix>/lib`` or ``<prefix>/include`` directories searched.
+  The behavior was reverted for non-Windows platforms by CMake 3.6.
+  Now it has been reverted on Windows platforms too.
+
+  One may set the ``CMAKE_PREFIX_PATH`` environment variable with a
+  :ref:`semicolon-separated list <CMake Language Lists>` of prefixes
+  that are to be searched.