rapids_export

New 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...> ]
    [ 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.

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>::. If not provided all targets will be placed in the <project_name>:: namespace

Note: When exporting with BUILD type, only GLOBAL_TARGETS will be placed in the namespace.

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
    )