echo/CMake
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Help: Fix find_package documentation about CPS and COMPONENTS

Browse Source 
The recent addition of component handling for CPS neglected to update
the documentation of how find_package handles component requests when
importing from CPS. Make those changes now.
This commit is contained in:
Matthew Woehlke 2025-02-28 16:54:36 -05:00
parent 62321f299c
commit 76e11bd4ea
1 changed files with 19 additions and 22 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

41
Help/command/find_package.rst
View File

@ -159,32 +159,29 @@ 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``. If these cannot be satisfied, the package overall
can still be considered found, as long as all required components are
satisfied.
.. TODO Once CPS honors COMPONENTS, note that OPTIONAL_COMPONENTS will cause
CMake to attempt to locate dependencies for optional components. Also note
that CMake will *not* load any appendices that don't include COMPONENTS or
OPTIONAL_COMPONENTS. (That isn't the case now, but will be when we don't
just ignore COMPONENTS.) The following paragraph will also need changes.
Additional optional components may be listed after ``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. For CMake-script package configuration files, it is formally
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.
target package:
.. note::
* For CMake-script package configuration files, it is formally 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.
If the experimental ``CMAKE_EXPERIMENTAL_FIND_CPS_PACKAGES`` is enabled,
CMake currently imports all available components if the located package
configuration file is a |CPS| file. At this time, ``COMPONENTS`` and
``OPTIONAL_COMPONENTS`` have no effect when considering a CPS file.
* |CPS| packages consist of a root configuration file and zero or more
appendices, each of which provide components and may have dependencies.
CMake always attempts to load the root configuration file. Appendices are
only loaded if their dependencies can be satisfied, and if they either
provide requested components, or if no components were requested. If the
dependencies of an appendix providing a required component cannot be
satisfied, the package is considered not found. Otherwise, that appendix
is ignored.
.. versionadded:: 3.24
The ``REGISTRY_VIEW`` keyword specifies which registry views should be