Feature flags#

LIBRA features are controlled by LIBRA_* CMake cache variables. This page explains the mental model — what they are, how they interact with presets, and the patterns that make them predictable. For the full variable reference, see Variable reference.

What feature flags are#

Each LIBRA_* variable controls a specific capability. Setting LIBRA_TESTS=ON at configure time causes LIBRA to:

  • discover test files under tests/

  • register them with CTest

  • create the all-tests, unit-tests, integration-tests, regression-tests, and build-and-test targets

Setting it to OFF means none of those targets exist in the build. This is the general pattern: flags gate both the behaviour and the targets. A target that requires a disabled flag is not merely non-functional — it does not exist, and attempting to build it produces a clear error.

The same flag also serves as the guard that clibra checks before running a subcommand. clibra test reads LIBRA_TESTS from the CMake cache of the resolved build directory and fails early with an actionable message if it is OFF, rather than letting the build fail mid-way with a cryptic “no rule to make target” error.

The explicit-off pattern#

The recommended preset hierarchy (see CMakePresets.json) uses a base hidden preset that sets every LIBRA_* flag to its default/off state explicitly. Every other preset inherits from base and enables only what it needs. This matters because CMake preset inheritance is additive — a child preset that does not mention a variable inherits its parent’s value. Without base setting everything off, a coverage preset inheriting from debug might silently inherit LIBRA_ANALYSIS=ON from some ancestor and run analysis on every coverage build.

The explicit-off pattern makes every preset self-describing: reading a preset’s cacheVariables tells you exactly what is enabled, with no hidden inherited state.

How flags interact with presets#

Feature flags live in the CMake cache of a configured build directory. They are set at configure time and do not change between builds unless you reconfigure. This means:

  • clibra build --preset debug and clibra test --preset debug use the same cache — the flags are shared across all commands that resolve to the same preset.

  • Changing a flag requires a reconfigure: clibra build --preset debug --reconfigure -DLIBRA_TESTS=ON, or by updating the preset’s cacheVariables and running a fresh configure.

  • Different presets have independent caches in independent build directories (when using ${presetName} in binaryDir). Switching from debug to coverage means switching to a different build directory, not reconfiguring the same one.

Checking flag state#

To see which flags are active in the current build:

clibra info               # shows LIBRA feature flags section
clibra info --build       # build configuration only

Or directly from the CMake cache:

cmake -LA -N build/<preset>/CMakeCache.txt | grep LIBRA_  # variable values
grep LIBRA_ build/<preset>/CMakeCache.txt