Merge topic 'fix-path-search-doc' into release-3.31

630e4a12a3 Help: Fix find_package search order w.r.t. globs

Acked-by: Kitware Robot <kwrobot@kitware.com>
Acked-by: buildbot <buildbot@kitware.com>
Acked-by: Matthew Woehlke <matthew.woehlke@kitware.com>
Merge-request: !9930

2 files changed, 47 insertions, 24 deletions

diff --git a/Help/command/find_package.rst b/Help/command/find_package.rst
index f555fe4..c26076b 100644
--- a/Help/command/find_package.rst
+++ b/Help/command/find_package.rst
@@ -503,6 +503,42 @@ The :variable:`CMAKE_IGNORE_PATH`, :variable:`CMAKE_IGNORE_PREFIX_PATH`,
 :variable:`CMAKE_SYSTEM_IGNORE_PREFIX_PATH` variables can also cause some
 of the above locations to be ignored.
 
+Paths are searched in the order described above.  The first viable package
+configuration file found is used, even if a newer version of the package
+resides later in the list of search paths.
+
+For search paths which contain ``<name>*``, the order among matching paths
+is unspecified unless the :variable:`CMAKE_FIND_PACKAGE_SORT_ORDER` variable
+is set.  This variable, along with the
+:variable:`CMAKE_FIND_PACKAGE_SORT_DIRECTION` variable, determines the order
+in which CMake considers paths that match a single search path containing
+``<name>*``.  For example, if the file system contains the package
+configuration files
+
+::
+
+  <prefix>/example-1.2/example-config.cmake
+  <prefix>/example-1.10/example-config.cmake
+  <prefix>/share/example-2.0/example-config.cmake
+
+it is unspecified (when the aforementioned variables are unset) whether
+``find_package(example)`` will find ``example-1.2`` or ``example-1.10``
+(assuming that both are viable), but ``find_package`` will *not* find
+``example-2.0``, because one of the other two will be found first.
+
+To control the order in which ``find_package`` searches directories that match
+a glob expression, use :variable:`CMAKE_FIND_PACKAGE_SORT_ORDER` and
+:variable:`CMAKE_FIND_PACKAGE_SORT_DIRECTION`.
+For instance, to cause the above example to select ``example-1.10``,
+one can set
+
+.. code-block:: cmake
+
+  SET(CMAKE_FIND_PACKAGE_SORT_ORDER NATURAL)
+  SET(CMAKE_FIND_PACKAGE_SORT_DIRECTION DEC)
+
+before calling ``find_package``.
+
 .. versionadded:: 3.16
    Added the ``CMAKE_FIND_USE_<CATEGORY>`` variables to globally disable
    various search locations.
@@ -648,22 +684,6 @@ is acceptable the following variables are set:
   Number of version components, 0 to 4
 
 and the corresponding package configuration file is loaded.
-When multiple package configuration files are available whose version files
-claim compatibility with the version requested it is unspecified which
-one is chosen: unless the variable :variable:`CMAKE_FIND_PACKAGE_SORT_ORDER`
-is set no attempt is made to choose a highest or closest version number.
-
-To control the order in which ``find_package`` checks for compatibility use
-the two variables :variable:`CMAKE_FIND_PACKAGE_SORT_ORDER` and
-:variable:`CMAKE_FIND_PACKAGE_SORT_DIRECTION`.
-For instance in order to select the highest version one can set
-
-.. code-block:: cmake
-
-  SET(CMAKE_FIND_PACKAGE_SORT_ORDER NATURAL)
-  SET(CMAKE_FIND_PACKAGE_SORT_DIRECTION DEC)
-
-before calling ``find_package``.
 
 Package File Interface Variables
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
diff --git a/Help/variable/CMAKE_FIND_PACKAGE_SORT_ORDER.rst b/Help/variable/CMAKE_FIND_PACKAGE_SORT_ORDER.rst
index 1725ba1..f1016d9 100644
--- a/Help/variable/CMAKE_FIND_PACKAGE_SORT_ORDER.rst
+++ b/Help/variable/CMAKE_FIND_PACKAGE_SORT_ORDER.rst
@@ -3,23 +3,26 @@ CMAKE_FIND_PACKAGE_SORT_ORDER
 
 .. versionadded:: 3.7
 
-The default order for sorting packages found using :command:`find_package`.
-It can assume one of the following values:
+The default order for sorting directories which match a search path containing
+a glob expression found using :command:`find_package`.  It can assume one of
+the following values:
 
 ``NONE``
-  Default.  No attempt is done to sort packages.
+  Default.  No attempt is done to sort directories.
   The first valid package found will be selected.
 
 ``NAME``
-  Sort packages lexicographically before selecting one.
+  Sort directories lexicographically before searching.
 
 ``NATURAL``
-  Sort packages using natural order (see ``strverscmp(3)`` manual),
+  Sort directories using natural order (see ``strverscmp(3)`` manual),
   i.e. such that contiguous digits are compared as whole numbers.
 
 Natural sorting can be employed to return the highest version when multiple
-versions of the same library are found by :command:`find_package`.  For
-example suppose that the following libraries have been found:
+versions of the same library are available to be found by
+:command:`find_package`.  For example suppose that the following libraries
+have package configuration files on disk, in a directory of the same name,
+with all such directories residing in the same parent directory:
 
 * libX-1.1.0
 * libX-1.2.9
@@ -35,4 +38,4 @@ version number ``libX-1.2.10``.
 
 The sort direction can be controlled using the
 :variable:`CMAKE_FIND_PACKAGE_SORT_DIRECTION` variable
-(by default decrescent, e.g. lib-B will be tested before lib-A).
+(by default descending, e.g. lib-B will be tested before lib-A).