rapids_cpm_find

Added in version v21.06.00.

Allow projects to find or build arbitrary projects via CPM with built-in tracking of these dependencies for correct export support.

rapids_cpm_find(<PackageName> <version>
                [COMPONENTS <components...>]
                [GLOBAL_TARGETS <targets...>]
                [BUILD_EXPORT_SET <export-name>]
                [INSTALL_EXPORT_SET <export-name>]
                <CPM_ARGS>
                  all normal CPM options
              )

Generate a CPM FindPackage call and associate this with the listed build and install export set for correct export generation.

Since the visibility of CMake’s targets differ between targets built locally and those imported, rapids_cpm_find() promotes imported targets to be global so users have consistency. List all targets used by your project in GLOBAL_TARGET.

Note

Requires rapids_cpm_init() to be called before usage

PackageName

Name of the package to find.

version

Version of the package you would like CPM to find.

COMPONENTS

Added in version v22.10.00.

A list of required components that are required to be found for this package to be considered valid when doing a local search.

GLOBAL_TARGETS

Which targets from this package should be made global. This information will be propagated to any associated export set.

Changed in version v21.10.00: If any targets listed in GLOBAL_TARGET exist when rapids_cpm_find() is called no calls to CPM will be executed. This is done for the following reasons:

• Removes the need for the calling code to do the conditional checks

• Allows BUILD_EXPORT_SET and INSTALL_EXPORT_SET tracking to happen correctly when targets had already been brought it by non-CPM means.

BUILD_EXPORT_SET

Record that a CPMFindPackage(<PackageName> ...) call needs to occur as part of our build directory export set.

INSTALL_EXPORT_SET

Record a find_dependency(<PackageName> ...) call needs to occur as part of our install directory export set.

BUILD_PATCH_ONLY

Do not require the package to be downloaded even if a patch command is present. This is to enable patches that only affect the build process and not runtime functionality.

CPM_ARGS

Required placeholder to be provided before any extra arguments that need to be passed down to CPMFindPackage().

Note

A PATCH_COMMAND will always trigger usage of CPMAddPackage() instead of CPMFindPackage(), unless BUILD_PATCH_ONLY is specified. This is true even if the patch command is empty.

Result Variables

<PackageName>_SOURCE_DIR is set to the path to the source directory of <PackageName>. <PackageName>_BINARY_DIR is set to the path to the build directory of <PackageName>. <PackageName>_ADDED is set to a true value if <PackageName> has not been added before.

Note

Adding an export set to rapids_cpm_find() has different behavior for build and install. Build exports a respective CPM call, since we presume other CPM packages don’t generate a correct build directory config module. While install exports a find_dependency call as we expect projects to have a valid install setup.

If you need different behavior you will need to use rapids_export_package() or rapids_export_cpm().

If CPM_<PackageName>_SOURCE is set, we use CPMAddPackage() instead of CPMFindPackage(). CPMAddPackage() always adds the package at the desired CPM_<PackageName>_SOURCE location, and won’t attempt to locate it via find_package() first.

Examples

Example on how to use rapids_cpm_find() to include common projects

# fmt
rapids_cpm_find(fmt 8.0.1
  GLOBAL_TARGETS fmt::fmt
  CPM_ARGS
    GITHUB_REPOSITORY fmtlib/fmt
    GIT_TAG 8.0.1
    GIT_SHALLOW TRUE
)

# google benchmark, no GIT_TAG required since it uses `v<Version>` tags
rapids_cpm_find(benchmark 1.5.2
  CPM_ARGS
      GIT_REPOSITORY  https://github.com/google/benchmark.git
      GIT_SHALLOW     TRUE
      OPTIONS         "BENCHMARK_ENABLE_TESTING OFF"
                      "BENCHMARK_ENABLE_INSTALL OFF"
)

Overriding

The rapids_cpm_package_override() command provides a way for projects to override the default values for any rapids_cpm_find(), rapids_cpm_*, CPM, and FetchContent() package.

By default when an override for a project is provided no local search for that project will occur. This is done to make sure that the requested modified version is used.