find_*: Disable the PACKAGE_ROOT search path group for CMake 3.9

Disable the feature added by commit v3.9.0-rc1~71^2~2 (find_*: Add a new
PackageRoot search path group, 2017-05-03) and remove documentation
added by commit v3.9.0-rc1~71^2 (find_*: Add docs for PackageRoot search
path group, 2017-05-03).  Unfortunately the name `<pkg>_ROOT` may
already be set by projects for their own incompatible purposes.  Disable
the behavior change for now to fix the regression for CMake 3.9.  We can
restore it later with a policy.

In order to keep the implementation and tests working, add an
undocumented variable we can use in the tests to enable the behavior
before the policy is introduced.

Fixes: #17144

Help/command/FIND_XXX.txt

@@ -16,7 +16,6 @@ The general signature is:
              [PATH_SUFFIXES suffix1 [suffix2 ...]]
              [DOC "cache documentation string"]
              [NO_DEFAULT_PATH]
-             [NO_PACKAGE_ROOT_PATH]
              [NO_CMAKE_PATH]
              [NO_CMAKE_ENVIRONMENT_PATH]
              [NO_SYSTEM_ENVIRONMENT_PATH]
@@ -61,10 +60,6 @@ If ``NO_DEFAULT_PATH`` is specified, then no additional paths are
 added to the search.
 If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows:
 
-.. |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX_SUBDIR| replace::
-   |prefix_XXX_SUBDIR| for each ``<prefix>`` in ``PackageName_ROOT`` if called
-   from within a find module
-
 .. |CMAKE_PREFIX_PATH_XXX_SUBDIR| replace::
    |prefix_XXX_SUBDIR| for each ``<prefix>`` in :variable:`CMAKE_PREFIX_PATH`
 
@@ -76,18 +71,7 @@ If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows:
    |prefix_XXX_SUBDIR| for each ``<prefix>`` in
    :variable:`CMAKE_SYSTEM_PREFIX_PATH`
 
-1. If called from within a find module, search prefix paths unique to the
+1. Search paths specified in cmake-specific cache variables.
-   current package being found.  Specifically look in the ``PackageName_ROOT``
-   CMake and environment variables.  The package root variables are maintained
-   as a stack so if called from nested find modules, root paths from the
-   parent's find module will be searchd after paths from the current module,
-   i.e. ``CurrentPackage_ROOT``, ``ENV{CurrentPackage_ROOT}``,
-   ``ParentPackage_ROOT``, ``ENV{ParentPacakge_ROOT}``, etc.
-   This can be skipped if ``NO_PACKAGE_ROOT_PATH`` is passed.
-
-   * |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX|
-
-2. Search paths specified in cmake-specific cache variables.
    These are intended to be used on the command line with a ``-DVAR=value``.
    The values are interpreted as :ref:`;-lists <CMake Language Lists>`.
    This can be skipped if ``NO_CMAKE_PATH`` is passed.
@@ -96,7 +80,7 @@ If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows:
    * |CMAKE_XXX_PATH|
    * |CMAKE_XXX_MAC_PATH|
 
-3. Search paths specified in cmake-specific environment variables.
+2. Search paths specified in cmake-specific environment variables.
    These are intended to be set in the user's shell configuration,
    and therefore use the host's native path separator
    (``;`` on Windows and ``:`` on UNIX).
@@ -106,17 +90,17 @@ If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows:
    * |CMAKE_XXX_PATH|
    * |CMAKE_XXX_MAC_PATH|
 
-4. Search the paths specified by the ``HINTS`` option.
+3. Search the paths specified by the ``HINTS`` option.
    These should be paths computed by system introspection, such as a
    hint provided by the location of another item already found.
    Hard-coded guesses should be specified with the ``PATHS`` option.
 
-5. Search the standard system environment variables.
+4. Search the standard system environment variables.
    This can be skipped if ``NO_SYSTEM_ENVIRONMENT_PATH`` is an argument.
 
    * |SYSTEM_ENVIRONMENT_PATH_XXX|
 
-6. Search cmake variables defined in the Platform files
+5. Search cmake variables defined in the Platform files
    for the current system.  This can be skipped if ``NO_CMAKE_SYSTEM_PATH``
    is passed.
 
@@ -124,7 +108,7 @@ If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows:
    * |CMAKE_SYSTEM_XXX_PATH|
    * |CMAKE_SYSTEM_XXX_MAC_PATH|
 
-7. Search the paths specified by the PATHS option
+6. Search the paths specified by the PATHS option
    or in the short-hand version of the command.
    These are typically hard-coded guesses.
 

Help/command/find_file.rst

@@ -8,9 +8,6 @@ find_file
 .. |prefix_XXX_SUBDIR| replace:: ``<prefix>/include``
 .. |entry_XXX_SUBDIR| replace:: ``<entry>/include``
 
-.. |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX| replace::
-   ``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE`
-   is set, and |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX_SUBDIR|
 .. |CMAKE_PREFIX_PATH_XXX| replace::
    ``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE`
    is set, and |CMAKE_PREFIX_PATH_XXX_SUBDIR|

Help/command/find_library.rst

@@ -8,9 +8,6 @@ find_library
 .. |prefix_XXX_SUBDIR| replace:: ``<prefix>/lib``
 .. |entry_XXX_SUBDIR| replace:: ``<entry>/lib``
 
-.. |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX| replace::
-   ``<prefix>/lib/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` is set,
-   and |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX_SUBDIR|
 .. |CMAKE_PREFIX_PATH_XXX| replace::
    ``<prefix>/lib/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` is set,
    and |CMAKE_PREFIX_PATH_XXX_SUBDIR|

Help/command/find_package.rst

@@ -64,7 +64,6 @@ The complete Config mode command signature is::
                [PATHS path1 [path2 ... ]]
                [PATH_SUFFIXES suffix1 [suffix2 ...]]
                [NO_DEFAULT_PATH]
-               [NO_PACAKGE_ROOT_PATH]
                [NO_CMAKE_PATH]
                [NO_CMAKE_ENVIRONMENT_PATH]
                [NO_SYSTEM_ENVIRONMENT_PATH]
@@ -250,13 +249,7 @@ The set of installation prefixes is constructed using the following
 steps.  If ``NO_DEFAULT_PATH`` is specified all ``NO_*`` options are
 enabled.
 
-1. Search paths specified in the ``PackageName_ROOT`` CMake and environment
+1. Search paths specified in cmake-specific cache variables.  These
-   variables.  The package root variables are maintained as a stack so if
-   called from within a find module, root paths from the parent's find
-   module will also be searched after paths for the current package.  This can
-   be skipped if ``NO_PACKAGE_ROOT_PATH`` is passed.
-
-2. Search paths specified in cmake-specific cache variables.  These
    are intended to be used on the command line with a ``-DVAR=value``.
    The values are interpreted as :ref:`;-lists <CMake Language Lists>`.
    This can be skipped if ``NO_CMAKE_PATH`` is passed::
@@ -265,7 +258,7 @@ enabled.
      CMAKE_FRAMEWORK_PATH
      CMAKE_APPBUNDLE_PATH
 
-3. Search paths specified in cmake-specific environment variables.
+2. Search paths specified in cmake-specific environment variables.
    These are intended to be set in the user's shell configuration,
    and therefore use the host's native path separator
    (``;`` on Windows and ``:`` on UNIX).
@@ -276,26 +269,26 @@ enabled.
      CMAKE_FRAMEWORK_PATH
      CMAKE_APPBUNDLE_PATH
 
-4. Search paths specified by the ``HINTS`` option.  These should be paths
+3. Search paths specified by the ``HINTS`` option.  These should be paths
    computed by system introspection, such as a hint provided by the
    location of another item already found.  Hard-coded guesses should
    be specified with the ``PATHS`` option.
 
-5. Search the standard system environment variables.  This can be
+4. Search the standard system environment variables.  This can be
    skipped if ``NO_SYSTEM_ENVIRONMENT_PATH`` is passed.  Path entries
    ending in ``/bin`` or ``/sbin`` are automatically converted to their
    parent directories::
 
      PATH
 
-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::
 
@@ -303,14 +296,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

Help/command/find_path.rst

@@ -8,9 +8,6 @@ find_path
 .. |prefix_XXX_SUBDIR| replace:: ``<prefix>/include``
 .. |entry_XXX_SUBDIR| replace:: ``<entry>/include``
 
-.. |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX| replace::
-   ``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE`
-   is set, and |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX_SUBDIR|
 .. |CMAKE_PREFIX_PATH_XXX| replace::
    ``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE`
    is set, and |CMAKE_PREFIX_PATH_XXX_SUBDIR|

Help/command/find_program.rst

@@ -8,8 +8,6 @@ find_program
 .. |prefix_XXX_SUBDIR| replace:: ``<prefix>/[s]bin``
 .. |entry_XXX_SUBDIR| replace:: ``<entry>/[s]bin``
 
-.. |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX| replace::
-   |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX_SUBDIR|
 .. |CMAKE_PREFIX_PATH_XXX| replace::
    |CMAKE_PREFIX_PATH_XXX_SUBDIR|
 .. |CMAKE_XXX_PATH| replace:: :variable:`CMAKE_PROGRAM_PATH`

Help/release/3.9.rst

@@ -42,12 +42,6 @@ Commands
 * The :command:`add_library` command ``IMPORTED`` option learned to support
   :ref:`Object Libraries`.
 
-* All ``find_`` commands now have a ``PACKAGE_ROOT`` search path group that
-  is first in the search heuristics.  If a ``find_`` command is called from
-  inside a find module, then the CMake variable and environment variable named
-  ``<PackageName>_ROOT`` are used as prefixes and are the first set of paths
-  to be searched.
-
 * The :command:`find_library` command learned to search ``libx32`` paths
   when the build targets the ``x32`` ABI.  See the
   :prop_gbl:`FIND_LIBRARY_USE_LIBX32_PATHS` global property.
@@ -326,3 +320,16 @@ Other Changes
   a change to the ``v140`` toolset made by a VS 2015 update.  VS changed
   the set of values it understands for the ``GenerateDebugInformation``
   linker setting that produces the ``-DEBUG`` linker flag variants.
+
+Updates
+=======
+
+Changes made since CMake 3.9.0 include the following.
+
+3.9.1
+-----
+
+* The ``find_`` command ``PACKAGE_ROOT`` search path group added by
+  CMake 3.9.0 has been removed for the 3.9 series due to regressions
+  caused by new use of ``<PackageName>_ROOT`` variables.  The behavior
+  may be re-introduced in the future in a more-compatible way.

Source/cmFindBase.cxx

@@ -68,6 +68,8 @@ bool cmFindBase::ParseArguments(std::vector<std::string> const& argsIn)
   }
   this->AlreadyInCache = false;
 
+  this->SelectDefaultNoPackageRootPath();
+
   // Find the current root path mode.
   this->SelectDefaultRootPathMode();
 

Source/cmFindCommon.cxx

@@ -88,6 +88,13 @@ void cmFindCommon::InitializeSearchPathGroups()
     std::make_pair(PathLabel::Guess, cmSearchPath(this)));
 }
 
+void cmFindCommon::SelectDefaultNoPackageRootPath()
+{
+  if (!this->Makefile->IsOn("__UNDOCUMENTED_CMAKE_FIND_PACKAGE_ROOT")) {
+    this->NoPackageRootPath = true;
+  }
+}
+
 void cmFindCommon::SelectDefaultRootPathMode()
 {
   // Check the policy variable for this find command type.

Source/cmFindCommon.h

@@ -84,6 +84,9 @@ protected:
   /** Compute final search path list (reroot + trailing slash).  */
   void ComputeFinalPaths();
 
+  /** Decide whether to enable the PACKAGE_ROOT search entries.  */
+  void SelectDefaultNoPackageRootPath();
+
   /** Compute the current default root path mode.  */
   void SelectDefaultRootPathMode();
 

Source/cmFindPackageCommand.cxx

@@ -209,6 +209,8 @@ bool cmFindPackageCommand::InitialPass(std::vector<std::string> const& args,
     this->SortDirection = strcmp(sd, "ASC") == 0 ? Asc : Dec;
   }
 
+  this->SelectDefaultNoPackageRootPath();
+
   // Find the current root path mode.
   this->SelectDefaultRootPathMode();
 

Tests/RunCMake/find_package/PackageRoot.cmake

@@ -1,3 +1,4 @@
+set(__UNDOCUMENTED_CMAKE_FIND_PACKAGE_ROOT 1)
 cmake_policy(SET CMP0057 NEW)
 list(INSERT CMAKE_MODULE_PATH 0 ${CMAKE_CURRENT_SOURCE_DIR}/PackageRoot)
 set(PackageRoot_BASE ${CMAKE_CURRENT_SOURCE_DIR}/PackageRoot)

Tests/RunCMake/find_package/PackageRootNestedConfig.cmake

@@ -1,3 +1,4 @@
+set(__UNDOCUMENTED_CMAKE_FIND_PACKAGE_ROOT 1)
 cmake_policy(SET CMP0057 NEW)
 list(INSERT CMAKE_MODULE_PATH 0 ${CMAKE_CURRENT_SOURCE_DIR}/PackageRoot)
 set(PackageRoot_BASE ${CMAKE_CURRENT_SOURCE_DIR}/PackageRoot)

Tests/RunCMake/find_package/PackageRootNestedModule.cmake

@@ -1,3 +1,4 @@
+set(__UNDOCUMENTED_CMAKE_FIND_PACKAGE_ROOT 1)
 cmake_policy(SET CMP0057 NEW)
 list(INSERT CMAKE_MODULE_PATH 0 ${CMAKE_CURRENT_SOURCE_DIR}/PackageRoot)
 set(PackageRoot_BASE ${CMAKE_CURRENT_SOURCE_DIR}/PackageRoot)