Merge topic 'FetchContent_find_package_integration'

29e31e2825 Packages: Integrate FetchContent and find_package()

Acked-by: Kitware Robot <kwrobot@kitware.com>
Acked-by: buildbot <buildbot@kitware.com>
Acked-by: huangqinjin <huangqinjin@gmail.com>
Merge-request: !5688

4 files changed, 76 insertions, 9 deletions

diff --git a/Help/command/find_package.rst b/Help/command/find_package.rst
index 0d8a166..8ce6529 100644
--- a/Help/command/find_package.rst
+++ b/Help/command/find_package.rst
@@ -17,7 +17,7 @@ and load its package-specific details.
 Search Modes
 ^^^^^^^^^^^^
 
-The command has two very distinct ways of conducting the search:
+The command has a few modes by which it searches for packages:
 
 **Module mode**
   In this mode, CMake searches for a file called ``Find<PackageName>.cmake``,
@@ -60,7 +60,17 @@ The command has two very distinct ways of conducting the search:
   Config mode is supported by both the :ref:`basic <Basic Signature>` and
   :ref:`full <Full Signature>` command signatures.
 
-The command arguments determine which of the above modes is used.  When the
+**FetchContent redirection mode**
+  .. versionadded:: 3.24
+    A call to ``find_package()`` can be redirected internally to a package
+    provided by the :module:`FetchContent` module.  To the caller, the behavior
+    will appear similar to Config mode, except that the search logic is
+    by-passed and the component information is not used.  See
+    :command:`FetchContent_Declare` and :command:`FetchContent_MakeAvailable`
+    for further details.
+
+When not redirected to a package provided by :module:`FetchContent`, the
+command arguments determine whether Module or Config mode is used.  When the
 `basic signature`_ is used, the command searches in Module mode first.
 If the package is not found, the search falls back to Config mode.
 A user may set the :variable:`CMAKE_FIND_PACKAGE_PREFER_CONFIG` variable
@@ -70,7 +80,7 @@ forced to use only Module mode with a ``MODULE`` keyword.  If the
 `full signature`_ is used, the command only searches in Config mode.
 
 Where possible, user code should generally look for packages using the
-`basic signature`_, since that allows the package to be found with either mode.
+`basic signature`_, since that allows the package to be found with any mode.
 Project maintainers wishing to provide a config package should understand
 the bigger picture, as explained in :ref:`Full Signature` and all subsequent
 sections on this page.
@@ -203,9 +213,12 @@ proceeds at once with Config mode search.
 
 Config mode search attempts to locate a configuration file provided by the
 package to be found.  A cache entry called ``<PackageName>_DIR`` is created to
-hold the directory containing the file.  By default the command
-searches for a package with the name ``<PackageName>``.  If the ``NAMES`` option
-is given the names following it are used instead of ``<PackageName>``.
+hold the directory containing the file.  By default, the command searches for
+a package with the name ``<PackageName>``.  If the ``NAMES`` option is given,
+the names following it are used instead of ``<PackageName>``.  The names are
+also considered when determining whether to redirect the call to a package
+provided by :module:`FetchContent`.
+
 The command searches for a file called ``<PackageName>Config.cmake`` or
 ``<lowercasePackageName>-config.cmake`` for each name specified.
 A replacement set of possible configuration file names may be given
@@ -242,6 +255,14 @@ Config Mode Search Procedure
   whether the :ref:`full <full signature>` or :ref:`basic <basic signature>`
   signature was given.
 
+.. versionadded:: 3.24
+  All calls to ``find_package()`` (even in Module mode) first look for a config
+  package file in the :variable:`CMAKE_FIND_PACKAGE_REDIRECTS_DIR` directory.
+  The :module:`FetchContent` module, or even the project itself, may write files
+  to that location to redirect ``find_package()`` calls to content already
+  provided by the project.  If no config package file is found in that location,
+  the search proceeds with the logic described below.
+
 CMake constructs a set of possible installation prefixes for the
 package.  Under each prefix several directories are searched for a
 configuration file.  The tables below show the directories searched.
@@ -420,7 +441,8 @@ to resolve symbolic links and store the real path to the file.
 Every non-REQUIRED ``find_package`` call can be disabled or made REQUIRED:
 
 * Setting the :variable:`CMAKE_DISABLE_FIND_PACKAGE_<PackageName>` variable
-  to ``TRUE`` disables the package.
+  to ``TRUE`` disables the package.  This also disables redirection to a
+  package provided by :module:`FetchContent`.
 
 * Setting the :variable:`CMAKE_REQUIRE_FIND_PACKAGE_<PackageName>` variable
   to ``TRUE`` makes the package REQUIRED.
@@ -443,8 +465,8 @@ version (see :ref:`format specification <FIND_PACKAGE_VERSION_FORMAT>`). If the
 ``EXACT`` option is given, only a version of the package claiming an exact match
 of the requested version may be found.  CMake does not establish any
 convention for the meaning of version numbers.  Package version
-numbers are checked by "version" files provided by the packages
-themselves.  For a candidate package configuration file
+numbers are checked by "version" files provided by the packages themselves
+or by :module:`FetchContent`.  For a candidate package configuration file
 ``<config-file>.cmake`` the corresponding version file is located next
 to it and named either ``<config-file>-version.cmake`` or
 ``<config-file>Version.cmake``.  If no such version file is available
diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst
index 70dfc35..98fc228 100644
--- a/Help/manual/cmake-variables.7.rst
+++ b/Help/manual/cmake-variables.7.rst
@@ -59,6 +59,7 @@ Variables that Provide Information
    /variable/CMAKE_EXTRA_SHARED_LIBRARY_SUFFIXES
    /variable/CMAKE_FIND_DEBUG_MODE
    /variable/CMAKE_FIND_PACKAGE_NAME
+   /variable/CMAKE_FIND_PACKAGE_REDIRECTS_DIR
    /variable/CMAKE_FIND_PACKAGE_SORT_DIRECTION
    /variable/CMAKE_FIND_PACKAGE_SORT_ORDER
    /variable/CMAKE_GENERATOR
diff --git a/Help/release/dev/FetchContent_find_package_integration.rst b/Help/release/dev/FetchContent_find_package_integration.rst
new file mode 100644
index 0000000..4ca7afc
--- /dev/null
+++ b/Help/release/dev/FetchContent_find_package_integration.rst
@@ -0,0 +1,17 @@
+FetchContent_find_package_integration
+-------------------------------------
+
+* Integration has been added between the :module:`FetchContent` module and the
+  :command:`find_package` command, enabling the following new capabilities:
+
+  * :command:`FetchContent_MakeAvailable` can now try to satisfy a dependency
+    by calling :command:`find_package` first.  A new
+    :variable:`FETCHCONTENT_TRY_FIND_PACKAGE_MODE` variable controls whether
+    this is done by default for all dependencies, is opt-in per dependency,
+    or is disabled entirely.
+
+  * :command:`find_package` can be re-routed to call
+    :command:`FetchContent_MakeAvailable` instead.  A new read-only
+    :variable:`CMAKE_FIND_PACKAGE_REDIRECTS_DIR` variable points to a
+    directory where config package files can be located to facilitate these
+    re-routed calls.
diff --git a/Help/variable/CMAKE_FIND_PACKAGE_REDIRECTS_DIR.rst b/Help/variable/CMAKE_FIND_PACKAGE_REDIRECTS_DIR.rst
new file mode 100644
index 0000000..fa414e4
--- /dev/null
+++ b/Help/variable/CMAKE_FIND_PACKAGE_REDIRECTS_DIR.rst
@@ -0,0 +1,27 @@
+CMAKE_FIND_PACKAGE_REDIRECTS_DIR
+--------------------------------
+
+.. versionadded:: 3.24
+
+This read-only variable specifies a directory that the :command:`find_package`
+command will check first before searching anywhere else for a module or config
+package file.  A config package file in this directory will always be found in
+preference to any other Find module file or config package file.
+
+The primary purpose of this variable is to facilitate integration between
+:command:`find_package` and :command:`FetchContent_MakeAvailable`.  The latter
+command may create files in the ``CMAKE_FIND_PACKAGE_REDIRECTS_DIR`` directory
+when it populates a dependency.  This allows subsequent calls to
+:command:`find_package` for the same dependency to re-use the populated
+contents instead of trying to satisfy the dependency from somewhere external
+to the build.  Projects may also want to write files into this directory in
+some situations (see :ref:`FetchContent-find_package-integration` for examples).
+
+The directory that ``CMAKE_FIND_PACKAGE_REDIRECTS_DIR`` points to will always
+be erased and recreated empty at the start of every CMake run.  Any files
+written into this directory during the CMake run will be lost the next time
+CMake configures the project.
+
+``CMAKE_FIND_PACKAGE_REDIRECTS_DIR`` is only set in CMake project mode.
+It is not set when CMake is run in script mode
+(i.e. :manual:`cmake -P ... <cmake(1)>`).