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.

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 evulated to ‘major.minor’ of the current rapids-cmake cal-ver value.

git_url

A required 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.

git_tag

A required 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.

Supports the following placeholders:

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

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

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.

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 git_url, git_tag, patches keys exist in the override

patches

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

{
  "patches" : [
    {
      "file" : "Thrust/cub_odr.diff",
      "issue" : "cub kernel dispatch ODR [https://github.com/NVIDIA/cub/issues/545]",
      "fixed_in" : ""
    }
  ]
}

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

file

A required string representing the git diff ( .diff ) or patch ( .patch ) to apply. Absolute and relative paths are supported. 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

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.

proprietary_binary

An optional dictionary of cpu architecture and operating system keys to url values that represents a download for a pre-built proprietary version of the library. This creates a new entry in the search logic for a project:

  • Search for a local version matching the version key

    • disabled by always_download

  • Download proprietary version if a valid OS + CPU Arch exists

    • disabled by USE_PROPRIETARY_BLOB being off

  • Fallback to using git url and tag

To determine the correct key, CMake will query for a key that matches the lower case value of <arch>-<os> where arch maps to CMAKE_SYSTEM_PROCESSOR and os maps to CMAKE_SYSTEM_NAME.

If no such key exists the request to use a proprietary_binary will be ignored.

{
  "proprietary_binary" : {
    "aarch64-linux" : "<url>",
    "x86_64-linux" : "<url>"
  }
}
As this represents a proprietary binary only the following packages support this command:

  • nvcomp

Due to requirements of proprietary binaries, explicit opt-in by the user on usage is required. Therefore for this binary to be used the caller must call the associated rapids_cpm command with the USE_PROPRIETARY_BLOB set to ON.

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.

  • ${cuda-toolkit-version} will be evaluated to ‘major.minor’ of the current CUDA Toolkit version.

  • ${cuda-toolkit-version-major} will be evaluated to ‘major’ of the current CUDA Toolkit version.

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 the git url or proprietary_binary entry in the override will be used.

rapids-cmake package versions

{
  "packages" : {
    "benchmark" : {
      "version" : "1.8.0",
      "git_url" : "https://github.com/google/benchmark.git",
      "git_tag" : "v${version}"
    },
    "CCCL" : {
      "version" : "2.2.0",
      "git_url" : "https://github.com/NVIDIA/cccl.git",
      "git_tag" : "v${version}",
      "patches" : [
        {
          "file" : "cccl/bug_fixes.diff",
          "issue" : "CCCL installs header-search.cmake files in nondeterministic order and has a typo in checking target creation that leads to duplicates",
          "fixed_in" : "2.3"
        },
        {
          "file" : "cccl/hide_kernels.diff",
          "issue" : "Mark all cub and thrust kernels with hidden visibility [https://github.com/nvidia/cccl/pulls/443]",
          "fixed_in" : "2.3"
        },
        {
          "file" : "cccl/revert_pr_211.diff",
          "issue" : "thrust::copy introduced a change in behavior that causes failures with cudaErrorInvalidValue.",
          "fixed_in" : ""
        }
      ]
    },
    "cuco" : {
      "version" : "0.0.1",
      "git_shallow" : false,
      "git_url" : "https://github.com/NVIDIA/cuCollections.git",
      "git_tag" : "f823d30d6b08a60383266db25821074dbdbe5822",
      "patches" : [
        {
          "file" : "cuco/hide_kernels.diff",
          "issue" : "CUCO Mark all kernels with hidden visibility [https://github.com/NVIDIA/cuCollections/pull/422]",
          "fixed_in" : ""
        }
      ]
    },
    "fmt" : {
      "version" : "10.1.1",
      "git_url" : "https://github.com/fmtlib/fmt.git",
      "git_tag" : "${version}"
    },
    "GTest" : {
      "version" : "1.13.0",
      "git_url" : "https://github.com/google/googletest.git",
      "git_tag" : "v${version}"
    },
    "libcudacxx" : {
      "version" : "2.1.0",
      "git_url" : "https://github.com/NVIDIA/libcudacxx.git",
      "git_tag" : "${version}",
      "patches" : [
        {
          "file" : "libcudacxx/install_rules.diff",
          "issue" : "libcudacxx installs incorrect files [https://github.com/NVIDIA/libcudacxx/pull/428]",
          "fixed_in" : "2.2"
        },
        {
          "file" : "libcudacxx/reroot_support.diff",
          "issue" : "Support conda-forge usage of CMake rerooting [https://github.com/NVIDIA/libcudacxx/pull/490], requires libcudacxx/install_rules.diff.",
          "fixed_in" : "2.2"
        },
        {
          "file" : "libcudacxx/proclaim_return_type_nv_exec_check_disable.diff",
          "issue" : "Use pragma to disable execution checks in cuda::proclaim_return_type. [https://github.com/NVIDIA/libcudacxx/pull/448]",
          "fixed_in" : "2.2"
        },
        {
          "file" : "libcudacxx/memory_resource.diff",
          "issue" : "Allow {async_}resource_ref to be constructible from a pointer. [https://github.com/NVIDIA/libcudacxx/pull/439]",
          "fixed_in" : "2.2"
        }
      ]
    },
    "nvbench" : {
      "version" : "0.0",
      "git_shallow" : false,
      "git_url" : "https://github.com/NVIDIA/nvbench.git",
      "git_tag" : "978d81a0cba97e3f30508e3c0e3cd65ce94fb699"
    },
    "nvcomp" : {
      "version" : "3.0.6",
      "git_url" : "https://github.com/NVIDIA/nvcomp.git",
      "git_tag" : "v2.2.0",
      "proprietary_binary" : {
        "x86_64-linux" :  "https://developer.download.nvidia.com/compute/nvcomp/${version}/local_installers/nvcomp_${version}_x86_64_${cuda-toolkit-version-major}.x.tgz",
        "aarch64-linux" : "https://developer.download.nvidia.com/compute/nvcomp/${version}/local_installers/nvcomp_${version}_SBSA_${cuda-toolkit-version-major}.x.tgz"
      }
    },
    "rmm" : {
      "version" : "${rapids-cmake-version}",
      "git_url" : "https://github.com/rapidsai/rmm.git",
      "git_tag" : "branch-${version}"
    },
    "spdlog" : {
      "version" : "1.12.0",
      "git_url" : "https://github.com/gabime/spdlog.git",
      "git_tag" : "v${version}",
      "patches" : [
        {
          "file" : "spdlog/nvcc_constexpr_fix.diff",
          "issue" : "Fix constexpr mismatch between spdlog and fmt [https://github.com/gabime/spdlog/issues/2856]",
                "fixed_in" : "1.13"
        }
      ]
    },
    "Thrust" : {
      "version" : "1.17.2",
      "git_url" : "https://github.com/NVIDIA/thrust.git",
      "git_tag" : "${version}",
      "patches" : [
        {
          "file" : "Thrust/reroot_support.diff",
          "issue" : "Support conda-forge usage of CMake rerooting [https://github.com/NVIDIA/thrust/pull/1969]",
          "fixed_in" : "2.2"
        },
        {
          "file" : "Thrust/transform_iter_with_reduce_by_key.diff",
          "issue" : "Support transform iterator with reduce by key [https://github.com/NVIDIA/thrust/pull/1805]",
          "fixed_in" : "2.1"
        },
        {
          "file" : "Thrust/install_rules.diff",
          "issue" : "Thrust 1.X installs incorrect files [https://github.com/NVIDIA/thrust/issues/1790]",
          "fixed_in" : "2.0"
        }
      ]
    }
  }
}