Kitware/CMake
1
0
Fork 0
mirror of https://github.com/Kitware/CMake.git synced 2025-10-18 08:51:52 +08:00
Code Issues 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
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 ``REQUIRED`` option is present, the ``COMPONENTS`` keyword can be omitted
and the required components can be listed directly after ``REQUIRED``. and the required components can be listed directly after ``REQUIRED``.
Additional optional components may be listed after Additional optional components may be listed after ``OPTIONAL_COMPONENTS``.
``OPTIONAL_COMPONENTS``. If these cannot be satisfied, the package overall If these cannot be satisfied, the package overall can still be considered
can still be considered found, as long as all required components are found, as long as all required components are satisfied.
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.
The set of available components and their meaning are defined by the The set of available components and their meaning are defined by the
target package. For CMake-script package configuration files, it is formally target package:
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.
.. 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, * |CPS| packages consist of a root configuration file and zero or more
CMake currently imports all available components if the located package appendices, each of which provide components and may have dependencies.
configuration file is a |CPS| file. At this time, ``COMPONENTS`` and CMake always attempts to load the root configuration file. Appendices are
``OPTIONAL_COMPONENTS`` have no effect when considering a CPS file. 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 .. versionadded:: 3.24
The ``REGISTRY_VIEW`` keyword specifies which registry views should be The ``REGISTRY_VIEW`` keyword specifies which registry views should be