# Boba Caliper Build Run

> Compile and run BoBa with Caliper enabled, capture `CALI_CONFIG=runtime-report` output, and interpret which rows correspond to BoBa profiling regions. Use when profiling a test, tutorial, or miniapp, or when deciding between `BOBA_ENABLE_CALIPER`, `BOBA_ENABLE_CALIPER_EXTERNAL`, and `BOBA_ENABLE_CALIPER_OBJECTS`.

- Skill: `llnl/boba-caliper-build-run` (Agent Skill)
- Install (CLI): `npx skillmds@latest add llnl/boba-caliper-build-run`
- Raw SKILL.md: https://api.skillmd.com/api/skills/llnl/boba-caliper-build-run/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: llnl (https://skillmd.com/u/llnl)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/llnl/boba-caliper-build-run

---


# BoBa Caliper Build And Run

Use this skill when you need to build a BoBa target with Caliper, run it, save the report, and read the reported hotspots.

## Quick Choice

- Use `BOBA_ENABLE_CALIPER=1` when you want the normal BoBa internal profiling scopes.
- Use `BOBA_ENABLE_CALIPER_EXTERNAL=1` when you want Caliper scopes outside BoBa internals, such as in exercises and tests.
- Use `BOBA_ENABLE_CALIPER_OBJECTS=1` when you specifically need object-level profiling regions.
- Source `caliper_lib_path_info_cpu` before running on CPU so the runtime loader can find `libcaliper`. This file is generated by `./boba_builder.py`.

## `make` Flow

Build a target with Caliper enabled:

```bash
source caliper_lib_path_info_cpu
make clean
make test_boba_tensor_train BOBA_ENABLE_CALIPER=1
```

In the `make` flow, the output executable name usually picks up a suffix such as `_cpu_cali.out`. For this target the executable is `test_boba_tensor_train_cpu_cali.out`.

Run it with Caliper's runtime report and save the text output. Capture both stdout and stderr so the report table is not lost:

```bash
( CALI_CONFIG=runtime-report ./test_boba_tensor_train_cpu_cali.out ) 2>&1 | tee cali_runtime_report.txt
```

For profiling regions outside of BoBa source code while avoiding profiling BoBa source, use the "external" regions and add them to your code:

```bash
source caliper_lib_path_info_cpu
make clean
make test_boba_tensor_train BOBA_ENABLE_CALIPER_EXTERNAL=1
( CALI_CONFIG=runtime-report ./test_boba_tensor_train_cpu_cali.out ) 2>&1 | tee cali_apps_report.txt
```

## CMake Flow

For CMake, the Caliper toggles are read from the environment and Caliper must also be discoverable through `CALIPER_DIR`.

```bash
source caliper_lib_path_info_cpu
BOBA_ENABLE_CALIPER=1 cmake -S . -B build -DCALIPER_DIR=/path/to/caliper/install
cmake --build build --target test_boba_tensor_train -j
( CALI_CONFIG=runtime-report ./build/examples/tests/test_boba_tensor_train ) 2>&1 | tee cali_runtime_report.txt
```

If you only want only the Caliper regions outside of BoBa source (e.g. in exercises or tests) ...

```bash
source caliper_lib_path_info_cpu
BOBA_ENABLE_CALIPER_EXTERNAL=1 cmake -S . -B build -DCALIPER_DIR=/path/to/caliper/install
cmake --build build --target test_boba_tensor_train -j
( CALI_CONFIG=runtime-report ./build/examples/tests/test_boba_tensor_train ) 2>&1 | tee cali_apps_report.txt
```

## Reading The Report

- In this BoBa setup, `runtime-report` may emit the text table on stderr. Use `( ... ) 2>&1 | tee file.txt` when you want a reliable saved copy.
- The exact columns can vary by Caliper version, but focus on the region name/path, time, time percentage, and call count columns.
- The hottest rows are the ones with the largest total time or largest time percentage.
- For hotspot ranking, prefer the largest `Time (E)` rows under `main` rather than `main` itself, since `main` is usually not the most actionable row.
- `BOBA_CALI_MARK` usually shows function-level regions.
- `BOBA_CALI_BEGIN("...")`, `BOBA_CALI_SWITCH("...","...")`, and `BOBA_CALI_END("...")` produce rows named after the explicit phase labels such as `setup` or `iterating`.
- `BOBA_ENABLE_CALIPER_EXTERNAL=1` is useful when you want CALIPER scopes in code outside BoBa source, such as exercises and tests.

## Practical Reading Workflow

1. Start with `BOBA_ENABLE_CALIPER_EXTERNAL=1` to find which top-level phase dominates in external code.
2. Rebuild with `BOBA_ENABLE_CALIPER=1` if you need finer detail inside that phase.
3. Open the saved report with `less cali_runtime_report.txt`.
4. Search for the heaviest region names and then `rg` those labels in `include/BOBA/` or `examples/` to find the owning code.

## Precision Profiling

If on a temporary basis you want to profile a precise set of functions in a call stack but ignore everything else, `BOBA_ENABLE_CALIPER_EXTERNAL` can be used with `BOBA_ENABLE_CALIPER_EXTERNAL=1` targeting just the desired functions. This might be useful for temporary targeted profiling.

## Common Problems

- If the executable fails to start because `libcaliper` is missing, source `caliper_lib_path_info_cpu` in the current shell before running.
- If the report shows little or no BoBa profiling data, rebuild with one of `BOBA_ENABLE_CALIPER=1`, `BOBA_ENABLE_CALIPER_EXTERNAL=1`, or `BOBA_ENABLE_CALIPER_OBJECTS=1`.
- If you only see coarse rows, you likely built with `BOBA_ENABLE_CALIPER_EXTERNAL=1` instead of full `BOBA_ENABLE_CALIPER=1`.