Building Caliper

Building and installing Caliper requires cmake, a current C++11-compatible compiler, and a Python interpreter. To build Caliper manually, clone it from the github repository. Next, configure and build Caliper, e.g.:

$ cd <path to caliper root directory>
$ mkdir build && cd build
$ cmake -DCMAKE_INSTALL_PREFIX=<path to install location> ..
$ make
$ make install

This is a minimal configuration, see below for additional CMake configuration flags.

CMake Flags

Configure Caliper using the usual CMake flags to select the C and C++ compiler, build type, and install prefix (CMAKE_C_COMPILER, CMAKE_CXX_COMPILER, CMAKE_BUILD_TYPE, and CMAKE_INSTALL_PREFIX). In addition, Caliper supports the following CMake flags:


Build documentation.


Build shared or static library. Default: On (build shared library).


Build unit tests.


Enable support for recording program metadata with the Adiak library. Point CMake to adiak CMake module, e.g. with -Dadiak_PREFIX=<path-to-adiak>/lib/cmake/adiak.


Enable support for CUDA performance analysis (wrapping of driver/runtime API calls and CUDA activity tracing).


Build the Fortran wrappers.


Enable Gotcha support. Allows pthread, IO, and malloc/free tracking, and enables dynamic wrapping of MPI functions. If Gotcha is disabled, MPI wrappers use the PMPI interface. Requires Linux.


Enables libdw support for DWARF symbol lookup. Required for most sampling-based configurations.


Enable Linux perf_event sampling. Set libpfm installation dir in LIBPFM_INSTALL.


Enables libunwind support for call-path unwinding.


Build with MPI support.


Build adapters to forward Caliper annotations to NVidia’s nvtx annotation API. Set CUDA_TOOLKIT_ROOT_DIR to the CUDA installation.


Build with support for the OpenMP tools interface.


Enable PAPI support. Set PAPI installation dir in PAPI_PREFIX.


Build adapters to forward Caliper annotations to AMD’s roctx annotation API.


Enable support for ROCm/HIP performance analysis (runtime API profiling and GPU activity tracing).


Enable time-based sampling on Linux.


Build Caliper’s tools (i.e, cali-query and mpi-caliquery). Default: On.


Build adapters to forward Caliper annotations to Intel’s VTune annotation API. Set Intel ITT API installation dir in ITT_PREFIX.

All options are off by default. On Linux, Gotcha is enabled by default.

Linking Caliper programs

Typically, all that is needed to create a Caliper-enabled program is to link it with the Caliper runtime library, which resides in An example link command for a C++ program built with g++ could look like this:

CALIPER_DIR = /path/to/caliper/installation

g++ -o target-program $(OBJECTS) -L$(CALIPER_DIR)/lib64 -lcaliper

Using Caliper in CMake projects

Caliper creates a CMake package file (caliper-config.cmake) and installs it in <caliper-installation-dir>/lib64/cmake/caliper. The package file defines Caliper’s include directories and exports targets for the Caliper libraries. Projects using CMake can use find_package() and target_link_libraries() to integrate Caliper as a dependency.

This example CMake code builds a program which depends on Caliper:

add_executable(MyExample MyExample.cpp)
target_link_libraries(MyExample PRIVATE caliper)

When configuring the target program, point CMake to the desired Caliper installation with caliper_DIR:

cmake -Dcaliper_DIR=<caliper-installation-dir>/share/cmake/caliper ..

The CMake package defines the following variables and targets:


Caliper include directory (variable)


The Caliper runtime library (target)


Caliper runtime library without MPI dependencies (target)


Utilities for caliper tools (target)

In most cases, just link the “caliper” target.