Kitware/CMake
1
0
Fork 0
mirror of https://github.com/Kitware/CMake.git synced 2025-10-23 00:48:55 +08:00
Code Issues Projects Releases Wiki Activity

Help: Clarify find_package() component handling

Browse Source 
Fixes: #22513
This commit is contained in:
Craig Scott
2021-08-08 15:04:23 +10:00
parent cc94429c61
commit b7d4567769
1 changed files with 20 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files

25
Help/command/find_package.rst
View File

@@ -28,11 +28,26 @@ that the package cannot be found if it is not ``REQUIRED``. The ``REQUIRED``
option stops processing with an error message if the package cannot be found.
A package-specific list of required components may be listed after the
``COMPONENTS`` option (or after the ``REQUIRED`` option if present).
``COMPONENTS`` keyword. If any of these components are not able to be
satisfied, the package overall is considered to be not found. If the
``REQUIRED`` option is also present, this is treated as a fatal error,
otherwise execution still continues. As a form of shorthand, if the
``REQUIRED`` option is present, the ``COMPONENTS`` keyword can be omitted
and the required components can be listed directly after ``REQUIRED``.
Additional optional components may be listed after
``OPTIONAL_COMPONENTS``. Available components and their influence on
whether a package is considered to be found are defined by the target
package.
``OPTIONAL_COMPONENTS``. If these cannot be satisfied, the package overall
can still be considered found, as long as all required components are
satisfied.
The set of available components and their meaning are defined by the
target package. Formally, it is up to the target package how to
interpret the component information given to it, but it should follow
the expectations stated above. For calls where no components are specified,
there is no single expected behavior and target packages should clearly
define what occurs in such cases. Common arrangements include assuming it
should find all components, no components or some well-defined subset of the
available components.
.. _FIND_PACKAGE_VERSION_FORMAT:
@@ -486,7 +501,7 @@ restores their original state before returning):
``<PackageName>_FIND_VERSION_EXACT``
True if ``EXACT`` option was given
``<PackageName>_FIND_COMPONENTS``
List of requested components
List of specified components (required and optional)
``<PackageName>_FIND_REQUIRED_<c>``
True if component ``<c>`` is required,
false if component ``<c>`` is optional