rapids_export

Added in version v21.06.00.

Generate a projects -Config.cmake module and all related information

rapids_export( (BUILD|INSTALL) <project_name>
    EXPORT_SET <export_set>
    [ GLOBAL_TARGETS <targets...> ]
    [ COMPONENTS <components...> ]
    [ COMPONENTS_EXPORT_SET <component 1 export set, component 2 export set...> ]
    [ VERSION <X.Y.Z> ]
    [ NAMESPACE <name_space> ]
    [ DOCUMENTATION <doc_variable> ]
    [ FINAL_CODE_BLOCK <code_block_variable> ]
    [ LANGUAGES <langs...> ]
    )

The rapids_export() function allow projects to easily generate a fully correct build and install tree Project-Config.cmake module including any necessary calls to find_dependency(), or CPMFindPackage().

Note

The files generated by rapids_export() are completely standalone and don’t require the consuming package to use rapids-cmake

project_name

Name of the project, to be used by consumers when using find_package

GLOBAL_TARGETS

Explicitly list what targets should be made globally visible to the consuming project.

COMPONENTS .. versionadded:: v23.04.00

A list of the optional COMPONENTS that are offered by this exported package. The names listed here will be what consumers calling find_package() will use to enable these components.

For each entry in COMPONENTS it is required to have an entry in COMPONENTS_EXPORT_SET at the same positional location.

rapids_export(BUILD example
  EXPORT_SET example-targets
  COMPONENTS A B
  COMPONENTS A-export B-export
  )

This is needed so that rapids_export() can correctly establish the dependency and import target information for each component.

COMPONENTS_EXPORT_SET .. versionadded:: v23.04.00

A list of the associated export set for each optional COMPONENT.

Each entry in COMPONENTS_EXPORT_SET is associated to the component as the same position in the COMPONENTS list.

VERSION

Explicitly list the version of the package being exported. By default rapids_export() uses the version specified by the root level project call. If no version has been specified either way or OFF is provided as the VERSION value, no version compatibility checks will be generated.

Depending on the version string different compatibility modes will be used.

Version String	Compatibility Type
None	No checks performed
X	SameMajorVersion
X.Y	SameMinorVersion
X.Y.Z	SameMinorVersion

Note

It can be useful to explicitly specify a version string when generating export rules for a sub-component of alarger project, or an external project that doesn’t have export rules.

NAMESPACE

Optional value to specify what namespace all targets from the EXPORT_SET will be placed into. When provided must match the pattern of <name>::. A recommended namespace could be <project_name>::. If not provided, no namespace is used.

Note: - When exporting with BUILD type, only GLOBAL_TARGETS will be placed in the namespace. - The namespace can be configured on a per-target basis instead using the EXPORT_NAME property.

DOCUMENTATION

Optional value of the variable that holds the documentation for this config file.

Note: This requires the documentation variable instead of the contents so we can handle having CMake code inside the documentation

FINAL_CODE_BLOCK

Optional value of the variable that holds a string of code that will be executed at the last step of this config file.

Note: This requires the code block variable instead of the contents so that we can properly insert CMake code

LANGUAGES

Non default languages, such as CUDA that are required by consumers of your package. This makes sure all consumers properly setup these languages correctly.

This is required as CMake’s enable_language only supports enabling languages for the current directory scope, and doesn’t support being called from within functions. Marking languages here overcomes these limitations and makes it possible for packages included via CPM to enable languages.

Example on how to properly use rapids_export():

...

add_library(example STATIC source.cu)
target_compile_features(example PUBLIC $<BUILD_INTERFACE:cuda_std_17>)

rapids_cmake_install_lib_dir(lib_dir)
install(TARGETS example
        DESTINATION ${lib_dir}
        EXPORT example-targets
        )

set(doc_string [=[Provide targets for the example library.]=])

set(code_string [=[ message(STATUS "hi from example-config")]=])

 rapids_export(INSTALL example
    EXPORT_SET example-targets
    GLOBAL_TARGETS example # Need to list all targets from `install(TARGETS`
    NAMESPACE example::
    DOCUMENTATION doc_string
    FINAL_CODE_BLOCK code_string
    )

rapids_export(BUILD example
    EXPORT_SET example-targets
    GLOBAL_TARGETS example # Need to list all targets from `install(TARGETS`
    # CUDA language support is a build detail only, as target_compile_features
    # guards the language behind `BUILD_INTERFACE` generator expression
    LANGUAGES CUDA
    NAMESPACE example::
    DOCUMENTATION doc_string
    FINAL_CODE_BLOCK code_string
    )