diff options
Diffstat (limited to 'Help/command/find_package.rst')
-rw-r--r-- | Help/command/find_package.rst | 49 |
1 files changed, 36 insertions, 13 deletions
diff --git a/Help/command/find_package.rst b/Help/command/find_package.rst index 3dfd62f..8388709 100644 --- a/Help/command/find_package.rst +++ b/Help/command/find_package.rst @@ -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: @@ -40,12 +55,13 @@ The ``[version]`` argument requests a version with which the package found should be compatible. There are two possible forms in which it may be specified: - * A single version with the format ``major[.minor[.patch[.tweak]]]``. + * A single version with the format ``major[.minor[.patch[.tweak]]]``, where + each component is a numeric value. * A version range with the format ``versionMin...[<]versionMax`` where - ``versionMin`` and ``versionMax`` have the same format as the single - version. By default, both end points are included. By specifying ``<``, - the upper end point will be excluded. Version ranges are only supported - with CMake 3.19 or later. + ``versionMin`` and ``versionMax`` have the same format and constraints + on components being integers as the single version. By default, both end + points are included. By specifying ``<``, the upper end point will be + excluded. Version ranges are only supported with CMake 3.19 or later. The ``EXACT`` option requests that the version be matched exactly. This option is incompatible with the specification of a version range. @@ -432,7 +448,7 @@ enabled. hard-coded guesses. .. versionadded:: 3.16 - Added the ``CMAKE_FIND_USE_<CATEGORY>_PATH`` variables to globally disable + Added the ``CMAKE_FIND_USE_<CATEGORY>`` variables to globally disable various search locations. .. |FIND_XXX| replace:: find_package @@ -448,8 +464,15 @@ which the file is found. The :variable:`CMAKE_FIND_PACKAGE_RESOLVE_SYMLINKS` variable may be set to ``TRUE`` before calling ``find_package`` in order to resolve symbolic links and store the real path to the file. -Every non-REQUIRED ``find_package`` call can be disabled by setting the -:variable:`CMAKE_DISABLE_FIND_PACKAGE_<PackageName>` variable to ``TRUE``. +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. + +* Setting the :variable:`CMAKE_REQUIRE_FIND_PACKAGE_<PackageName>` variable + to ``TRUE`` makes the package REQUIRED. + +Setting both variables to ``TRUE`` simultaneously is an error. Package File Interface Variables ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -479,7 +502,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 |