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

Merge topic 'document-cps-components-resolution'

Browse Source 
dd8bf95271 Help: Document handling of CPS transitive components

Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !10434
This commit is contained in:
Brad King 2025-03-10 14:18:40 +00:00 committed by Kitware Robot
commit f65fcde174
1 changed files with 34 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

34
Help/command/find_package.rst
View File

@ -956,3 +956,37 @@ requirements are not satisfied.
.. _cps-version_schema: https://cps-org.github.io/cps/schema.html#version-schema
.. |cps-version_schema| replace:: ``version_schema``
CPS Transitive Requirements
^^^^^^^^^^^^^^^^^^^^^^^^^^^
A |CPS| package description consists of one or more components which may in
turn depend on other components either internal or external to the package.
When external components are required, the providing package is noted as
a package-level requirement of the package. Additionally, the set of required
components is typically noted in said external package requirement.
Where a CMake-script package description would use the
:command:`find_dependency` command to handle transitive dependencies, CMake
handles transitive dependencies for CPS itself using an internally nested
``find_package`` call. This call can resolve CPS package dependencies via
*either* another CPS package, or via a CMake-script package. The manner in
which the CPS component dependencies are handled is subject to some caveats.
When the candidate for resolving a transitive dependency is another CPS
package, things are simple; ``COMPONENTS`` and CPS "components" are directly
comparable (and are effectively synonymous with CMake "imported targets").
CMake-script packages, however, are encouraged to (and often do) check that
required components were found, whether or not the package describes separate
components. Additionally, even those that do describe components typically do
not have the same correlation to imported targets that is normal for CPS. As
a result, passing the set of required components declared by a CPS package to
``COMPONENTS`` would result in spurious failures to resolve dependencies.
To address this, if a candidate for resolving a CPS transitive dependency is a
CMake-script package, CMake passes the required components as declared by the
consuming CPS package as ``OPTIONAL_COMPONENTS`` and performs a separate,
internal check that the candidate package supplied the required imported
targets. Those targets must be named ``<PackageName>::<ComponentName>``, in
conformance with CPS convention, or the check will consider the package not
found.