mirror/CMake
1
0
Fork 0
mirror of https://github.com/Kitware/CMake.git synced 2026-01-06 05:40:54 -06:00
Code Issues Packages Projects Releases Wiki Activity

Merge topic 'FetchContent_find_package_integration'

Browse Source 
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
This commit is contained in:
Craig Scott
2022-05-06 12:33:22 +00:00
committed by Kitware Robot
parent 30f9159667 29e31e2825
commit c5dff5ace2
51 changed files with 1010 additions and 60 deletions
Download Patch File Download Diff File Expand all files Collapse all files

40
Help/command/find_package.rst
View File

@@ -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

1
Help/manual/cmake-variables.7.rst
View File

@@ -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

17
Help/release/dev/FetchContent_find_package_integration.rst Normal file
View File

@@ -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.

27
Help/variable/CMAKE_FIND_PACKAGE_REDIRECTS_DIR.rst Normal file
View File

@@ -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)>`).