Installation

Note

You will find in the documentation very often the name alpaka and for directories alpaka3, you will maybe wonder why we are not consequent using alpaka3 everywhere. The reason for this is that the complete code base will be copied to https://github.com/alpaka-group/alpaka after the first release, therefore options are already named alpaka.

Installing dependencies

alpaka requires a modern C++ compiler (g++, clang++, nvcc, icpx). CMake is the preferred system for configuration the build tree, building and installing.

In order to install CMake:

On Linux:

# RPM
sudo dnf install cmake
# DEB
sudo apt install cmake

On macOS or Windows:

Download the installer from https://cmake.org/download/

Dependencies to use specific backends: Depending on your target platform you may need additional packages to compile and run alpaka.

NVIDIA GPUs: CUDA Toolkit (https://developer.nvidia.com/cuda-toolkit)
AMD GPUs: ROCm / HIP (https://rocmdocs.amd.com/en/latest/index.html)
Intel GPUs: OneAPI Toolkit (https://www.intel.com/content/www/us/en/developer/tools/oneapi/base-toolkit.html#gs.9x3lnh)

alpaka as Dependency in Your Application

There are two ways to integrate alpaka as dependency with CMake into your project.

Install alpaka

The installation must be performed once and can be reused until you require a new version of alpaka. If you only install alpaka without enabling tests, examples or benchmarks CMake will not check for compilers, this is postponed to the usage of the installation together with our application.

# Clone alpaka from github.com
git clone --branch dev https://github.com/alpaka-group/alpaka3.git
mkdir build && cd build
# assumed folder structure
# ├── alpaka3
# └── build
# if not set, the default is CMAKE_INSTALL_PREFIX=/usr/local
cmake -DCMAKE_INSTALL_PREFIX=/install/alpaka3 ..
cmake --install .

The next CMake code snipped shows you to integrate the installed alpaka library in your application. You have now the possibility to select the compiler, enable dependency’s to target different compute devices. Examples and brief description can be found in the follow up section Tests and Examples

find_package(alpaka REQUIRED)
# ...
add_executable(myTarget src/my.cpp)
target_link_libraries(myTarget PUBLIC alpaka::alpaka)
alpaka_finalize(myTarget)
# ...

The next commands should be executed in the terminal and assumes that you prepend the environment variable CMAKE_PREFIX_PATH with the path /install/alpaka3, that CMake knows where alpaka can be found.

cmake <path_to_you_appliction>
cmake --build . --parallel

Use the Source Code Without Installation

With CMake it is possible to use alpaka without installation, you can simply point to the cloned folder.

# Clone alpaka from github.com
git clone --branch dev https://github.com/alpaka-group/alpaka3.git

The next CMake code is very similar to the usage of a installed alpaka version with the difference that you should use add_subdirectory() instead of CMake’s find_package()

# `${CMAKE_BINARY_DIR}/alpaka` places the alpaka code in your build directory in the sub directory `alpaka`
add_subdirectory("<path_to_cloned_alpaka3>" "${CMAKE_BINARY_DIR}/alpaka")
# ...
add_executable(myTarget src/my.cpp)
target_link_libraries(myTarget PUBLIC alpaka::alpaka)
alpaka_finalize(myTarget)
# ...

You should prepend the environment variable CMAKE_PREFIX_PATH with the path to the cloned alpaka folder.

cmake <path_to_you_appliction>
cmake --build . --parallel

Use FetchContent to Download alpaka Automatically

CMake’s FetchContent module provides a convenient way to automatically download and integrate alpaka into your project at configure time, without requiring manual cloning or installation.

This approach is ideal for:

Jumpstarting a new alpaka project
Quick prototyping and testing
Projects that want to ensure consistent alpaka versions
CI/CD pipelines where automatic dependency management is preferred

Warning

When using FetchContent, alpaka will be downloaded each time you run CMake in a clean build directory. For faster builds in development, consider using the installation method or adding the alpaka source subdirectory (for example to your version control system as a submodule/subtree).

Note

Users can directly copy and take over the CMakeLists.txt and main.cpp provided below, to start using alpaka in their project with FetchContent.

Complete CMakeLists.txt Example

The following CMakeLists.txt demonstrates how to use FetchContent with alpaka and one possible way to configure device specifications:

CMakeLists.txt

#
# Copyright 2025 Tapish Narwal
# SPDX-License-Identifier: ISC
#

cmake_minimum_required(VERSION 3.25)

project(fetchContent LANGUAGES CXX VERSION 1.0)

# Use CMake's FetchContent to download and integrate alpaka3 directly from GitHub
include(FetchContent)

# Declare where to fetch alpaka3 from
# This will download the library at configure time
FetchContent_Declare(alpaka3 GIT_REPOSITORY https://github.com/alpaka-group/alpaka3.git GIT_TAG dev)

# Make alpaka3 available for use in this project
# This downloads, configures, and makes the library targets available
FetchContent_MakeAvailable(alpaka3)

# Define the device specification for your application
# Format: "api:deviceKind" where:
#   - api: The parallel programming interface (host, cuda, hip, oneApi)
#   - deviceKind: The type of device (cpu, nvidiaGpu, amdGpu, intelGpu)
# Default is set to "host:cpu" for CPU-only execution
set(myApp_DEVICE_SPEC "host:cpu" CACHE STRING "Selected alpaka Device Specification")

# Define all available device specifications for the cache variable
# This creates a dropdown menu in CMake GUIs for easy selection
set_property(
    CACHE myApp_DEVICE_SPEC
    PROPERTY STRINGS "host:cpu;cuda:nvidiaGpu;hip:amdGpu;oneApi:cpu;oneApi:intelGpu;oneApi:nvidiaGpu;oneApi:amdGpu"
)

# Parse the device specification string into separate API and device kind components
# Split the string at the colon delimiter
string(REPLACE ":" ";" _myAPP_DEVICE_SPEC_LIST "${myApp_DEVICE_SPEC}")

# Extract the API (first element) and device kind (second element) components from the list
list(GET _myAPP_DEVICE_SPEC_LIST 0 _myApp_API)
list(GET _myAPP_DEVICE_SPEC_LIST 1 _myApp_DEVICE_KIND)

# Create the executable target from the source file
add_executable(fetchContentExample main.cpp)

# Link the alpaka library to the executable
target_link_libraries(fetchContentExample PRIVATE alpaka::alpaka)

# Pass the device specification to the C++ code as compile-time definitions
# These will be available as MYAPP_API and MYAPP_DEVICE_KIND macros in the code
target_compile_definitions(fetchContentExample PRIVATE MYAPP_API=${_myApp_API} MYAPP_DEVICE_KIND=${_myApp_DEVICE_KIND})

# Finalize the alpaka configuration for this target
# This sets up backend-specific compiler flags and dependencies
alpaka_finalize(fetchContentExample)

Example Source Code

Create a main.cpp file that uses the device specification passed from CMake:

main.cpp

/* Copyright 2025 Simeon Ehrig, Tapish Narwal
 * SPDX-License-Identifier: ISC
 */

#include <alpaka/alpaka.hpp>

#include <cstdlib>
#include <iostream>

// Helper function to create a device specification
// Uses the compile-time definitions MYAPP_API and MYAPP_DEVICE_KIND
// that were set in CMakeLists.txt
auto getDeviceSpec()
{
    return alpaka::onHost::DeviceSpec{alpaka::api::MYAPP_API, alpaka::deviceKind::MYAPP_DEVICE_KIND};
}

int main(int argc, char** argv)
{
    alpaka::onHost::DeviceSpec devSpec = getDeviceSpec();
    auto deviceSelector = alpaka::onHost::makeDeviceSelector(devSpec);

    auto num_devices = deviceSelector.getDeviceCount();
    std::cout << "Number of available Devices: " << num_devices << "\n";

    if(num_devices == 0)
    {
        return EXIT_FAILURE;
    }

    auto device = deviceSelector.makeDevice(0);
    std::cout << "Device 0: " << device.getName() << "\n";

    return EXIT_SUCCESS;
}

Building Your Application

Note

If the main.cpp and CMakeLists.txt are placed in an empty directory, then from inside this directory, users can directly follow the code below to build and run the example.

To build and run your application with the default CPU backend:

mkdir build && cd build
cmake ..
cmake --build . --parallel
./fetchContentExample

Selecting Different Devices

You can select different device specifications at CMake configuration time using the myApp_DEVICE_SPEC cache variable, for example

# NVIDIA CUDA DEVIC SPEC
cmake .. -DmyApp_DEVICE_SPEC="cuda:nvidiaGpu"
# build and run
cmake --build . --parallel
./fetchContentExample

Note

The device specification system allows you to select the target device at CMake configuration time. The format is "api:deviceKind", where:

api: The parallel programming interface (host, cuda, hip, oneApi)
deviceKind: The type of device (cpu, nvidiaGpu, amdGpu, intelGpu)

Available combinations are: host:cpu, cuda:nvidiaGpu, hip:amdGpu, oneApi:cpu, oneApi:intelGpu, oneApi:nvidiaGpu, oneApi:amdGpu

Warning

The CUDA, HIP, or Intel backends are only working if the CUDA SDK, HIP SDK, or OneAPI SDK are available respectively

Tests and Examples

The examples and tests can be compiled before the installation of alpaka see Install alpaka. They will use alpaka headers from the source directory. The recipies shown here assume you have installed spack packages for specific compiler versions and that alpaka is relative to the build folder available.

Load dependencies

spack load gcc@14.1.0
spack load cmake@3.29.1

Build and run examples:

# In a directory beside the alpaka source directory (for example in "build-alpaka3")
# ├── alpaka3
# └── build-alpaka3
# ..
cmake ../alpaka3 -Dalpaka_EXAMPLES=ON
cmake --build . --parallel -t vectorAdd
./example/vectorAdd/vectorAdd # execution

Build and run tests:

# ..
cmake ../alpaka3 -Dalpaka_TESTS=ON
cmake --build . --parallel
ctest

Enable accelerators:

alpaka uses different api’s and executors to run kernels on different processors. To use a specific accelerator in alpaka, two steps are required.

Enable the accelerator during the CMake configuration time of the project.
Select a specific accelerator in the source code.

By default, only the host API is available which allows to use the executors ‘serial’ to running on CPUs without using multithreading. If OpenMP is available on the system, additionally the executor cpuOmpBlocks can be used to run on all cores of the CPU. If oneAPI TBB is available on the system, additionally the executor cpuTbbBlocks can be used to run on all cores of the CPU. CMake option alpaka_DEP_* controls whether a parallelization framework is used and introduces a dependency on third-party libraries. This allows the usage of the coresponding executor e.g. gpuCuda, gpuHip or oneApi alpaka_EXEC_* activates or deactivates which execution schemas will be used for examples/test and benchmarks.

compile for CPU only (serial and OpenMP):

spack load gcc@14.1.0
spack load cmake@3.29.1

# -Dalpaka_DEP_OMP=ON is implicitly set, if the compiler not support OpenMP only serial code will be generated
# Assuming alpaka source is in ../alpaka3 with respect to the current directory
#
cmake ../alpaka3 -Dalpaka_TESTS=ON -Dalpaka_BENCHMARKS=ON -Dalpaka_EXAMPLES=ON -DBUILD_TESTING=ON
cmake --build . --parallel
ctest --output-on-failure

compile for CPU with (serial and oneAPI TBB):

spack load cmake@3.29.1
spack load intel-oneapi-tbb@2021.10.0

cmake ../alpaka3 -Dalpaka_TESTS=ON -Dalpaka_BENCHMARKS=ON -Dalpaka_EXAMPLES=ON -Dalpaka_DEP_TBB=ON -Dalpaka_DEP_OMP=OFF
cmake --build . --parallel
ctest --output-on-failure

compile for NVIDIA CUDA only:

spack load cmake@3.29.1
spack load cuda@12.4.0

# use -DCMAKE_CUDA_ARCHITECTURES=80 to set the GPU architecture
cmake ../alpaka3 -Dalpaka_TESTS=ON -Dalpaka_BENCHMARKS=ON -Dalpaka_EXAMPLES=ON -Dalpaka_DEP_OMP=OFF -Dalpaka_DEP_CUDA=ON -Dalpaka_EXEC_CpuSerial=OFF
cmake --build . --parallel
ctest --output-on-failure

compile for AMD HIP only:

spack load cmake@3.29.1
spack load hip@6.3.4
export CXX=clang++

# use -DCMAKE_HIP_ARCHITECTURES=gfx906 to set the GPU architecture
# for older CMake version sometimes the architecture must be set with -DAMDGPU_TARGETS=gfx906
cmake ../alpaka3 -Dalpaka_TESTS=ON -Dalpaka_BENCHMARKS=ON -Dalpaka_EXAMPLES=ON -Dalpaka_DEP_OMP=OFF -Dalpaka_DEP_HIP=ON -Dalpaka_EXEC_CpuSerial=OFF
cmake --build . --parallel
ctest --output-on-failure

compile for OneApi SYCL CPU/GPU only

spack load cmake@3.29.1
spack load intel-oneapi-compilers@2025.0.4
spack load intel-oneapi-dpl@2022.2.0

# by default all device kinds get be addressed CPU and Intel GPU will be addressed
# You can add support for NVIDIA GPU and AMD GPU via
#  -Dalpaka_ONEAPI_AmdGpu=ON
#  -Dalpaka_ONEAPI_NvidiaGpu=ON
# or deselect the device kind with
#  -Dalpaka_ONEAPI_Cpu=OFF
#  -Dalpaka_ONEAPI_IntelGpu=OFF
#
# The architecture can be set with -Dalpaka_ONEAPI_*_ARCH=<arch>
# Cpu ISA e.g. avx,avx2, avx512
# Nvidia only the sm number is needed e.g. 80
# Amd full qualifier is required e.g. gfx906
cmake ../alpaka3 -DCMAKE_CXX_COMPILER=icpx -Dalpaka_TESTS=ON -Dalpaka_BENCHMARKS=ON -Dalpaka_EXAMPLES=ON -Dalpaka_DEP_ONEAPI=ON -Dalpaka_DEP_OMP=OFF -Dalpaka_EXEC_CpuSerial=OFF
cmake --build . --parallel
ctest --output-on-failure

Warning

If an api is selected in the source code that is not activated during CMake configuration time, a compiler error occurs.