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`.