CPM Reference

The rapids_cpm functions allow projects to find or build dependencies with built-in tracking of these dependencies for correct export support.

rapids-cmake package defaults

rapids-cmake provides a collection of pre-defined packages to ensure that all consumers use the same version of dependencies. The exact versions that each pre-configured package uses can be found at the bottom of the page.

rapids-cmake package override

rapids-cmake allows projects to override the default values for the pre-defined packages provided by rapids-cmake while also overriding any rapids_cpm_find(), CPM, and FetchContent() package calls.

When an override for a project exists no find_package()<cmake:command:find_package> search for that project will occur. This is done to make sure that the requested modified version is used.

If a project is listed in multiple override files, the first file values will be used, and all later calls for that packaged will be ignored. This “first to record, wins” approach is used to match FetchContent, and allows parent projects to override child projects.

If the override is of an existing default project, it only needs to specify the fields it wants to override.

For example if you wanted to change the version of GTest you would do the following:

{
  "packages": {
    "GTest": {
      "version": "100.1.0"
    }
  }
}

If you want to specify a completely new project, you need to specify at a minimum all the required fields:

{
  "packages": {
    "new_dependency": {
      "version": "1.2.3",
      "git_url": "https://github.com/org/new_dependency.git",
      "git_tag": "${version}"
    }
  }
}

Reproducible rapids-cmake builds

The rapids-cmake default versions.json uses branch names or git tag names for dependencies. This is done so that projects can ‘live at head’ of dependencies. This directly conflicts with the concept of reproducible release packages that each time they are built produce bitwise-identical artifacts.

rapids_cpm_generate_pinned_versions() can be used to generate a set of explicit pinned git SHA1 values corresponding to the set of rapids-cmake dependencies in use. This results in a fully reproducible set of dependencies when building.

To utilize this behavior in your release CI/CD something like the following needs to be set up:

1. Enable generation of a pinned versions file during builds via rapids_cpm_generate_pinned_versions() or by specifying the RAPIDS_CMAKE_CPM_PINNED_VERSIONS_FILE. 2. If the build is good, create the release branch and commit the generated pinned versions.json to the repository 3. Rebuilds of the project using the pinned version are now possible by setting the RAPIDS_CMAKE_CPM_OVERRIDE_VERSION_FILE to the path of the generated pinned versions file.

rapids-cpm command line controls

rapids-cpm offers multiple command line options to control behavior.

Some builds are performed fully offline and the default package and override urls can’t be used. In those cases you can use the variable RAPIDS_CMAKE_CPM_OVERRIDE_VERSION_FILE to provide a new versions.json that will be used instead of ALL overrides specified in that project. This would allow you to specify custom internal urls for all dependencies without modifying the project source code.

` cmake -DRAPIDS_CMAKE_CPM_OVERRIDE_VERSION_FILE=<abs/path/to/custom/override_versions.json> .... `

To request the generation of a pinned package override file without having to modify the project use the RAPIDS_CMAKE_CPM_PINNED_VERSIONS_FILE variable:

` cmake -DRAPIDS_CMAKE_CPM_PINNED_VERSIONS_FILE `

Additional CPM command line controls

In addition any of the CPM options can be used with rapids-cpm. A full list of CPM options can be found in the CPM README.md; we document some of the most important ones below.

If you need to explicitly state a package must be downloaded and not searched for locally you enable the variable CPM_DOWNLOAD_<package_name>.

` cmake -DCPM_DOWNLOAD_<package_name>=ON .... `

If you need to explicitly state all packages must be downloaded and not searched for locally you enable the variable CPM_DOWNLOAD_ALL.

` cmake -DCPM_DOWNLOAD_ALL=ON .... `

Offline and Airgapped Usage

When building in environments with restricted network access, such as airgapped systems or networks with unstable connections, rapids-cmake provides several mechanisms to enable offline builds using CPM’s caching and local override features.

Using CPM_SOURCE_CACHE for Offline Builds

The CPM_SOURCE_CACHE variable enables caching of downloaded dependencies, preventing re-downloads and allowing fully offline builds once the cache is populated.

The cache location can be specified via environment variable:

export CPM_SOURCE_CACHE=$HOME/.cache/CPM
cmake -B build ...

Or passed directly as a CMake configure option (which takes precedence over the environment variable):

cmake -B build -DCPM_SOURCE_CACHE=/path/to/cache ...

Once dependencies are downloaded to the cache directory, subsequent builds can be performed completely offline as long as all required packages exist locally.

Workflow for preparing an offline environment:

On a machine with network access, configure with CPM_SOURCE_CACHE to populate the dependency cache:
```
cmake -B build -DCPM_SOURCE_CACHE=/path/to/cache ...
```
Copy the rapids-cmake source tree from the build directory into the cache so it is available on the offline system alongside the other dependencies:
```
cp -r build/_deps/rapids-cmake-src /path/to/cache/rapids-cmake
```
Transfer the directory specified in step 1 in -DCPM_SOURCE_CACHE= to the airgapped system.
Build offline using the populated cache. Pass FETCHCONTENT_SOURCE_DIR_RAPIDS-CMAKE so that dependencies that use rapids-cmake do not attempt to download it from the network:
```
cmake -B build \
      -DCPM_SOURCE_CACHE=/path/to/cache \
      -DFETCHCONTENT_SOURCE_DIR_RAPIDS-CMAKE=/path/to/cache/rapids-cmake \
      -Drapids-cmake-dir=/path/to/cache/rapids-cmake \
      ...
cmake --build build
```
Setting FETCHCONTENT_SOURCE_DIR_RAPIDS-CMAKE causes CMake’s FetchContent to treat rapids-cmake as already populated from the given path, bypassing any network fetch for dependencies that use rapids-cmake.

Note

A fully worked example of this workflow is provided in examples/offline_build. It contains shell scripts that automate both the cache-population step (generate_offline_source_cache.sh) and the offline build step (use_offline_source_cache.sh).

Using Local Package Overrides

For development workflows where you need to use a locally modified version of a dependency, or when you have pre-downloaded sources, use the CPM_<PackageName>_SOURCE variable to override the source location for individual packages:

cmake -B build -DCPM_fmt_SOURCE=/local/path/to/fmt ...

This replaces the remote source entirely with your local directory for that build, enabling simultaneous development on both the consumer project and its dependencies.

Using Package Lock Files

For managing complex transitive dependency sets, CPM provides lock file support through CPMUsePackageLock(). This is an upstream CPM feature (not rapids-cmake specific) that centralizes dependency version management:

include(cmake/CPM.cmake)
CPMUsePackageLock(package-lock.cmake)

To update the lock file after adding or modifying dependencies:

cmake -B build
cmake --build build --target cpm-update-package-lock

This generates a complete lockfile of all transitive dependencies that can be committed to your repository for reproducible builds. See the CPM documentation for details.

Additional Offline Options

CPM_USE_LOCAL_PACKAGES: Instructs CPM to attempt find_package()<cmake:command:find_package>() first before downloading sources. This is useful in airgapped environments where dependencies are pre-installed via system package managers:

cmake -B build -DCPM_USE_LOCAL_PACKAGES=ON ...

CPM_LOCAL_PACKAGES_ONLY: Enforces strictly offline operation by emitting errors if any dependency cannot be found locally:

cmake -B build -DCPM_LOCAL_PACKAGES_ONLY=ON ...

Integration with rapids-cmake Reproducibility Features

For reproducible builds, combine offline caching with rapids_cpm_generate_pinned_versions() to generate exact git SHA pinning. This ensures bitwise-identical builds across environments:

Generate pinned versions:

cmake -B build -DRAPIDS_CMAKE_CPM_PINNED_VERSIONS_FILE=pinned_versions.json \
               -DCPM_SOURCE_CACHE=/path/to/cache ...

Transfer both the pinned_versions.json and cache directory to the offline environment

Build offline with pinned versions:

cmake -B build -DRAPIDS_CMAKE_CPM_OVERRIDE_VERSION_FILE=pinned_versions.json \
               -DCPM_SOURCE_CACHE=/path/to/cache ...

This workflow provides both reproducibility (via pinned SHA values) and offline capability (via source cache).

rapids-cmake package version format

rapids-cmake uses a JSON file to encode the version of a project and how to download the project.

The JSON format is a root object that contains the packages object.

The packages object contains a key/value map of all supported packages where the key is the case-sensitive name of the project and the value is a project object, as seen in this example:

{
  "packages": {
    "Thrust": {
      "version": "1.12.0",
      "git_url": "https://github.com/NVIDIA/thrust.git",
      "git_tag": "${version}",
      "git_shallow": true,
      "always_download": true,
      "exclude_from_all": false
    }
  }
}

Project Object Fields

Each project object must contain the following fields so that rapids-cmake can properly use CPM to find or download the project as needed. Each project must define version and one of the following: (git_url + git_tag) or (url + url_hash).

version

A required string representing the version of the project to be used by rapids_cpm_find() when looking for a local installed copy of the project.

Supports the following placeholders:

${rapids-cmake-version} will be evaluated to ‘major.minor’ of the current rapids-cmake cal-ver value.

$ENV{variable} will be evaluated to the contents of the listed environment variable

git_url

A string representing the git url to be used when cloning the project locally by the rapids_cpm_find() when a locally installed copy of the project can’t be found. Required unless url/url_hash is provided. When git_url is provided, git_tag must also be supplied and url/url_hash must not be present.

Supports the following placeholders:

${rapids-cmake-version} will be evaluated to ‘major.minor’ of the current rapids-cmake cal-ver value.

${version} will be evaluated to the contents of the version field.

$ENV{variable} will be evaluated to the contents of the listed environment variable

git_tag

A string representing the git tag to be used when cloning the project locally by the rapids_cpm_find() when a locally installed copy of the project can’t be found. Required when git_url is provided.

Supports the following placeholders:

${rapids-cmake-checkout-tag} will be evaluated to main when using rapids-cmake main branch, or release/<major>.<minor> when not on the ‘main’ branch, using the rapids-cmake CalVer values.

${rapids-cmake-version} will be evaluated to ‘major.minor’ of the current rapids-cmake cal-ver value.

${version} will be evaluated to the contents of the version field.

$ENV{variable} will be evaluated to the contents of the listed environment variable

url

A string representing a URL to a source tarball. Required unless git_url/git_tag is provided. When url is provided, url_hash must also be supplied and git_url/git_tag must not be present.

Supports the following placeholders:

${rapids-cmake-version} will be evaluated to ‘major.minor’ of the current rapids-cmake cal-ver value.

${version} will be evaluated to the contents of the version field.

$ENV{variable} will be evaluated to the contents of the listed environment variable

url_hash

A required string representing the URL_HASH value used by CPM when downloading the tarball (for example SHA256=<hash>).

git_shallow

An optional boolean value that represents if we should do a shallow git clone or not.

If no such field exists the default is true.

src_dir

An optional string value that represents the source directory under the root of the project that contains the CMakeLists.txt to use

If no such field exists the default is presuming the root directory has the CMakeLists.txt to use

exclude_from_all

An optional boolean value that represents the CMake `EXCLUDE_FROM_ALL` property. If this is set to true, and the project is built from source all targets of that project will be excluded from the ALL build rule. This means that any target that isn’t used by the consuming project will not be compiled. This is useful when a project generates multiple targets that aren’t required and the cost of building them isn’t desired.

If no such field exists the default is false.

always_download

An optional boolean value that represents if CPM should just download the package ( CPM_DOWNLOAD_ALL ) instead of first searching for it on the machine.

The default value for this field is false unless all of the following criteria is met.

The projects exists in both the default and override files

The fetch keys (git_url/git_tag or url/url_hash) and patches exist in the override

Existence of a patch entry in the definition

patches

An optional list of dictionary sets of git patches to apply to the project when it is built from source.

If this field exists in the default package, the value will be ignored when an override file entry exists for the package. This ensures that patches only the git url entry in the override will be used.

The existence of a patch entry in the package definition being used will cause the always_download value always to be true.

Each dictionary in the array of patches contains the following fields:

file
{
  "patches": [
    {
      "file": "Thrust/cub_odr.diff",
      "issue": "cub kernel dispatch ODR [https://github.com/NVIDIA/cub/issues/545]",
      "fixed_in": ""
    }
  ]
}
Mutually exclusive string field with inline_patch. Only one of these fields may be provided.

Absolute or relative path to the git diff ( .diff ) or patch ( .patch ) to apply. Relative paths are evaluated in relation to the rapids-cmake/cpm/patches directory.

Supports the following placeholders:

${current_json_dir} will be evaluated to the absolute path to the directory holding the current json file
inline_patch
{
  "patches": [
    {
      "inline_patch": {
        "type": "patch",
        "content": [
          "From deacd3fafd7fcfee954ae3044ae3ab60d36a9f3a Mon Sep 17 00:00:00 2001",
          "From: Robert Maynard <rmaynard@nvidia.com>",
          "Date: Wed, 31 Jan 2024 15:00:47 -0500",
          "Subject: [PATCH 1/2] Move GIT SHA1",
          "",
          "---",
          " git_file_1.txt | 1 +",
          " 1 file changed, 1 insertion(+)",
          " create mode 100644 git_file_1.txt",
          "",
          "diff --git a/git_file_1.txt b/git_file_1.txt",
          "new file mode 100644",
          "index 00000000..b242c360",
          "--- /dev/null",
          "+++ b/git_file_1.txt",
          "@@ -0,0 +1 @@",
          "+added file",
          "--",
          "2.43.0",
          ""
        ]
      },
      "issue": "Example of an inline patch",
      "fixed_in": ""
    }
  ]
}
Mutually exclusive dictionary field with file. Only one of these fields may be provided.

Required keys for inline_patch are:

type the format of the patch, either diff ( git diff ) or patch ( git format-patch ).

content the lines of the patch file represented as an array of strings ( each element is a line ).
issue
A required string that explains the need for the patch. Preference is for the string to also contain the URL to the upstream issue or PR that this patch addresses.

fixed_in
A required entry that represents which version this patch is no longer needed in. If this patch is required for all versions an empty string should be supplied.

required
An optional boolean value that represents if it is required that the patch apply correctly.

The default value for this field is false.

build
An optional boolean value that specifies whether or not this patch is a build patch. Build patches only affect the build process, not the runtime functionality or exported headers. If all patches are build patches, the project is not required to be downloaded and can be found with find_package().

The default value for this field is false.

rapids-cmake package versions

{
  "packages": {
    "benchmark": {
      "version": "1.9.5",
      "git_url": "https://github.com/google/benchmark.git",
      "git_tag": "192ef10025eb2c4cdd392bc502f0c852196baa48"
    },
    "bs_thread_pool": {
      "version": "4.1.0",
      "git_shallow": false,
      "git_url": "https://github.com/bshoshany/thread-pool.git",
      "git_tag": "097aa718f25d44315cadb80b407144ad455ee4f9"
    },
    "CCCL": {
      "version": "3.4.0",
      "url": "https://github.com/NVIDIA/cccl/archive/2b7188d2b5e4f2671f68078abc7d842e6b1e3d22.tar.gz",
      "url_hash": "SHA256=76905e6564507911f2c845156ae6c0c16a4b011227c80fbe4e42c41dbe2093ac"
    },
    "cuco": {
      "version": "0.0.1",
      "git_shallow": false,
      "always_download": true,
      "git_url": "https://github.com/NVIDIA/cuCollections.git",
      "git_tag": "f517bbb1277753b1852dfd388993383e401eaa38"
    },
    "rapids_logger": {
      "version": "0.2.3",
      "git_url": "https://github.com/rapidsai/rapids-logger.git",
      "git_tag": "4c72b598f99c8aa06af49468b3fc82f3931c6bf6"
    },
    "GTest": {
      "version": "1.16.0",
      "git_shallow": false,
      "git_url": "https://github.com/google/googletest.git",
      "git_tag": "6910c9d9165801d8827d628cb72eb7ea9dd538c5"
    },
    "nvbench": {
      "version": "0.0",
      "git_shallow": false,
      "git_url": "https://github.com/NVIDIA/nvbench.git",
      "git_tag": "b88a45f4170af4e907e69af22a55af67859d3b49"
    },
    "nvtx3": {
      "version": "3.2.0",
      "git_shallow": false,
      "git_url": "https://github.com/NVIDIA/NVTX.git",
      "git_tag": "69c9949150ac1c310758a304082228a36d5e4758",
      "source_subdir": "c"
    },
    "rmm": {
      "version": "${rapids-cmake-version}",
      "git_url": "https://github.com/rapidsai/rmm.git",
      "git_tag": "${rapids-cmake-checkout-tag}",
      "source_subdir": "cpp"
    }
  }
}