From 76e11bd4ea5cbd9651110b9bf3a9fc0f50e6b840 Mon Sep 17 00:00:00 2001 From: Matthew Woehlke Date: Fri, 28 Feb 2025 16:54:36 -0500 Subject: Help: Fix find_package documentation about CPS and COMPONENTS 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. --- Help/command/find_package.rst | 45 ++++++++++++++++++++----------------------- 1 file changed, 21 insertions(+), 24 deletions(-) diff --git a/Help/command/find_package.rst b/Help/command/find_package.rst index cae7150..123675c 100644 --- a/Help/command/find_package.rst +++ b/Help/command/find_package.rst @@ -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. - -.. note:: - - 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. +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. + +* |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 -- cgit v0.12