From b7d45677691cda2defdccd9272e595973f766162 Mon Sep 17 00:00:00 2001 From: Craig Scott Date: Sun, 8 Aug 2021 15:04:23 +1000 Subject: Help: Clarify find_package() component handling Fixes: #22513 --- Help/command/find_package.rst | 25 ++++++++++++++++++++----- 1 file changed, 20 insertions(+), 5 deletions(-) diff --git a/Help/command/find_package.rst b/Help/command/find_package.rst index 7febd5d..bd26010 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: @@ -486,7 +501,7 @@ restores their original state before returning): ``_FIND_VERSION_EXACT`` True if ``EXACT`` option was given ``_FIND_COMPONENTS`` - List of requested components + List of specified components (required and optional) ``_FIND_REQUIRED_`` True if component ```` is required, false if component ```` is optional -- cgit v0.12