Browse Source

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.
Matthew Woehlke 7 months ago
parent
commit
76e11bd4ea
1 changed files with 21 additions and 24 deletions
  1. 21 24
      Help/command/find_package.rst

+ 21 - 24
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
 ``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
-``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
 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
 .. versionadded:: 3.24
   The ``REGISTRY_VIEW`` keyword specifies which registry views should be
   The ``REGISTRY_VIEW`` keyword specifies which registry views should be