Integrating Kokkos into Your Project

This document describes how to integrate the Kokkos library into your CMake project.

Kokkos provides the Kokkos::kokkos target, which simplifies the process by automatically handling necessary include directories, link libraries, compiler options, and other usage requirements.

Here are several integration methods, each with its own advantages:

1. External Kokkos (Recommended for most users)

The recommended approach is to use Kokkos as an external dependency. This allows for easier management and updates. Use CMake’s find_package() command to locate and link against an existing Kokkos installation:

find_package(Kokkos 4.2 REQUIRED CONFIG) # Find Kokkos version 4.2 or later
# ...
target_link_libraries(MyTarget PRIVATE Kokkos::kokkos)

• find_package(Kokkos ...) searches for a KokkosConfig.cmake file, which is generated when Kokkos is built and installed. This file contains the necessary information for linking against Kokkos.

• The 4.2 argument specifies the minimum required Kokkos version. It’s optional but recommended for ensuring compatibility.

• Kokkos::kokkos is the namespaced imported target that provides all necessary build flags.

• The CONFIG keyword tells CMake to use the configuration files.

You can install Kokkos separately and then point CMake to its location using the Kokkos_ROOT variable.

MyProject> cmake -DKokkos_ROOT=/path/to/kokkos/install/dir -B builddir

2. Embedded Kokkos via add_subdirectory() and Git Submodules

This method embeds the Kokkos source code directly into your project. It’s useful when you need very tight control over the Kokkos version or when you can’t install Kokkos separately.

1. Add Kokkos as a Git submodule:

MyProject> git submodule add -b 4.5.01 https://github.com/kokkos/kokkos.git tpls/kokkos
MyProject> git commit -m 'Adding Kokkos v4.5.1 as a submodule'

tpls/kokkos/ should now contain the full Kokkos source tree.

2. Use add_subdirectory() in your CMakeLists.txt:

add_subdirectory(tpls/kokkos)
# ...
target_link_libraries(MyTarget PRIVATE Kokkos::kokkos)

3. Embedded Kokkos via FetchContent

FetchContent simplifies the process of downloading and including Kokkos as a dependency during the CMake configuration stage.

include(FetchContent)
FetchContent_Declare(
    Kokkos
    URL      https://github.com/kokkos/kokkos/releases/download/4.5.01/kokkos-4.5.01.tar.gz
    URL_HASH SHA256=52d003ffbbe05f30c89966e4009c017efb1662b02b2b73190670d3418719564c
)
FetchContent_MakeAvailable(Kokkos)
# ...
target_link_libraries(MyTarget PRIVATE Kokkos::kokkos)

• URL_HASH is highly recommended for verifying the integrity of the downloaded archive. You can find the SHA256 checksums for Kokkos releases in the kokkos-X.Y.Z-SHA-256.txt file on the Kokkos releases page.

4. Supporting Both External and Embedded Kokkos

This approach allows your project to use either an external Kokkos installation or an embedded version, providing flexibility for different build environments.

find_package(Kokkos CONFIG) # Try to find Kokkos externally
if(Kokkos_FOUND)
    message(STATUS "Found Kokkos: ${Kokkos_DIR} (version \"${Kokkos_VERSION}\")")
else()
    message(STATUS "Kokkos not found externally. Fetching via FetchContent.")
    include(FetchContent)
    FetchContent_Declare(
        Kokkos
        URL https://github.com/kokkos/kokkos/archive/refs/tags/4.4.01.tar.gz
    )
    FetchContent_MakeAvailable(Kokkos)
endif()
# ...
target_link_libraries(MyTarget PRIVATE Kokkos::kokkos)

Controlling the Kokkos integration:

• CMAKE_DISABLE_FIND_PACKAGE_Kokkos: Set this variable to TRUE to force the use of the embedded Kokkos, even if an external installation is found.

• CMAKE_REQUIRE_FIND_PACKAGE_Kokkos: Set this variable to TRUE to require an external Kokkos installation. The build will fail if Kokkos is not found.

• Kokkos_ROOT: Use this variable to specify the directory where CMake should search for Kokkos when using find_package().

For example:

cmake -DCMAKE_REQUIRE_FIND_PACKAGE_Kokkos=ON -DKokkos_ROOT=/path/to/kokkos/install/dir

or

cmake -DCMAKE_DISABLE_FIND_PACKAGE_Kokkos=ON