find_package: Drop search in recent cmake-gui locations

The find_package command, on Windows, has always searched build trees
recently visited by cmake-gui (or CMakeSetup at one time).  This was
done when the command was created with the intention of simplifying
workflows involving building multiple dependent projects.  However,
this behavior depends on recent developer interaction and therefore
can create different find results based on transient system states.
It can lead to surprising results and user confusion.

Since this behavior was first added CMake has gained many more search
options, better error messages when a package is not found, and a
package registry.  The latter in particular allows projects to make
their build trees available for dependent projects to find without
user intervention.  Therefore the originally intended workflow can
be achieved in other, more stable ways.

After the above evoluion of find_package we have now decided that
the magic search-where-cmake-gui-was behavior does more harm than
good.  Drop it.  We do not need a policy for this behavior change
because it only affects interactive use.

1 files changed, 5 insertions, 11 deletions

diff --git a/Help/command/find_package.rst b/Help/command/find_package.rst
index 7f518a6..a5efba6 100644
--- a/Help/command/find_package.rst
+++ b/Help/command/find_package.rst
@@ -68,7 +68,7 @@ The complete Config mode command signature is::
                [NO_CMAKE_PATH]
                [NO_SYSTEM_ENVIRONMENT_PATH]
                [NO_CMAKE_PACKAGE_REGISTRY]
-               [NO_CMAKE_BUILDS_PATH]
+               [NO_CMAKE_BUILDS_PATH] # Deprecated; does nothing.
                [NO_CMAKE_SYSTEM_PATH]
                [NO_CMAKE_SYSTEM_PACKAGE_REGISTRY]
                [CMAKE_FIND_ROOT_PATH_BOTH |
@@ -265,20 +265,14 @@ enabled.
 
      PATH
 
-5. Search project build trees recently configured in a :manual:`cmake-gui(1)`.
-   This can be skipped if ``NO_CMAKE_BUILDS_PATH`` is passed.  It is intended
-   for the case when a user is building multiple dependent projects one
-   after another.
-   (This step is implemented only on Windows.)
-
-6. Search paths stored in the CMake :ref:`User Package Registry`.
+5. Search paths stored in the CMake :ref:`User Package Registry`.
    This can be skipped if ``NO_CMAKE_PACKAGE_REGISTRY`` is passed or by
    setting the :variable:`CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY`
    to ``TRUE``.
    See the :manual:`cmake-packages(7)` manual for details on the user
    package registry.
 
-7. Search cmake variables defined in the Platform files for the
+6. Search cmake variables defined in the Platform files for the
    current system.  This can be skipped if ``NO_CMAKE_SYSTEM_PATH`` is
    passed::
 
@@ -286,14 +280,14 @@ enabled.
      CMAKE_SYSTEM_FRAMEWORK_PATH
      CMAKE_SYSTEM_APPBUNDLE_PATH
 
-8. Search paths stored in the CMake :ref:`System Package Registry`.
+7. Search paths stored in the CMake :ref:`System Package Registry`.
    This can be skipped if ``NO_CMAKE_SYSTEM_PACKAGE_REGISTRY`` is passed
    or by setting the
    :variable:`CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY` to ``TRUE``.
    See the :manual:`cmake-packages(7)` manual for details on the system
    package registry.
 
-9. Search paths specified by the ``PATHS`` option.  These are typically
+8. Search paths specified by the ``PATHS`` option.  These are typically
    hard-coded guesses.
 
 .. |FIND_XXX| replace:: find_package