Variable reference#

All LIBRA_* CMake cache variables. These are set at configure time via -D on the cmake command line, or in a preset’s cacheVariables. Most can also be set in project-local.cmake — see project-local.cmake: How To Hook Into LIBRA for restrictions.

For a conceptual overview of how feature flags work and interact with presets, see Feature flags. For file discovery and layout conventions, see Project layout.

Important

Unless specified otherwise, all variables apply only to the current project and its registered targets. No CMAKE_XXX global variables are set, which prevents unintended cascades into dependency builds.

General#

LIBRA_DRIVER#
Default:

SELF

Type:

CACHE STRING

The primary user-visible driver to LIBRA, if any. Possible values are:

  • SELF - LIBRA itself is the driver/main way users interact with the build system; for all intents and purposes, LIBRA IS the build system. It also handles packaging duties, to the extent that cmake supports packaging.

  • CONAN - CONAN is the primary driver of the build system. It sets up the environment and handles all packaging tasks. LIBRA only has to run the actual builds.

LIBRA_SUMMARY#
Default:

NO

Type:

CACHE BOOL

Show a configuration summary after the configuration step finishes.

Quality Gates#

LIBRA_TESTS#
Default:

NO

Type:

CACHE BOOL

Enable building of tests via:

  • make unit-tests (unit tests only)

  • make integration-tests (integration tests only)

  • make regression-tests (regression tests only)

  • make all-tests (all tests)

LIBRA_COVERAGE#
Default:

NO

Type:

CACHE BOOL

Build in runtime code-coverage instrumentation for report generation and coverage checking. See Target reference for the targets enabled.

LIBRA_COVERAGE_NATIVE#
Default:

YES

Type:

CACHE BOOL

Direct compilers to build in coverage instrumentation in their “native” format. E.g., clang will use LLVM format, and GCC will use GNU format. If false, all compilers will use GNU format. The created targets will reflect which format is selected.

LIBRA_ANALYSIS#
Default:

NO

Type:

CACHE BOOL

Enable static analysis targets for checkers, formatters, etc. See Target reference for the targets enabled (assuming the necessary executables are found). See Static analysis for tool-specific configuration guidance.

LIBRA_DOCS#
Default:

NO

Type:

CACHE BOOL

Enable documentation build via make apidoc and/or make sphinxdoc.

LIBRA_SPHINXDOC_COMMAND#
Default:

sphinx-build

Type:

STRING

The command to run sphinx and generate documentation. via make sphinxdoc.

LIBRA_FORMAT#
Default:

NO

Type:

CACHE BOOL

Enable formatting/format checking via make format and/or make format-check.

LIBRA_WERROR#
Default:

NO

Type:

CACHE BOOL

Pass -Werror to the selected compiler so that all warnings are treated as errors when building.

LIBRA_CTEST_INCLUDE_UNIT_TESTS#
Default:

YES

Type:

BOOL

Should registered unit tests be included in the test target to run?

LIBRA_CTEST_INCLUDE_INTEGRATION_TESTS#
Default:

YES

Type:

BOOL

Should registered integration tests be included in the test target to run?

LIBRA_CTEST_INCLUDE_REGRESSION_TESTS#
Default:

YES

Type:

BOOL

Should registered regression tests be included in the test target to run?

LIBRA_CTEST_INCLUDE_UNIT_TESTS
Default:

YES

Type:

BOOL

Should registered unit tests be included in the test target to run?

LIBRA_CTEST_INCLUDE_INTEGRATION_TESTS
Default:

YES

Type:

BOOL

Should registered integration tests be included in the test target to run?

LIBRA_CTEST_INCLUDE_REGRESSION_TESTS
Default:

YES

Type:

BOOL

Should registered regression tests be included in the test target to run?

LIBRA_GCOVR_LINES_THRESH#
Default:

95

Type:

STRING

Threshold for line coverage under which the gcovr-check target will return non-zero.

LIBRA_GCOVR_FUNCTIONS_THRESH#
Default:

60

Type:

STRING

Threshold for functions coverage under which the gcovr-check target will return non-zero.

LIBRA_GCOVR_BRANCHES_THRESH#
Default:

50

Type:

STRING

Threshold for branches coverage under which the gcovr-check target will return non-zero.

LIBRA_GCOVR_DECISIONS_THRESH#
Default:

50

Type:

STRING

Threshold for decisions coverage under which the gcovr-check target will return non-zero.

Runtime Checking#

LIBRA_SAN#
Default:

NONE

Type:

CACHE STRING

Build in runtime checking of code using any compiler. When passed, the value should be a semicolon-separated list of sanitizer groups to enable:

  • MSAN - Memory checking/sanitization. Requires libmsan compatible with your compiler.

  • ASAN - Address sanitization. Requires libasan compatible with your compiler.

  • SSAN - Aggressive stack checking.

  • UBSAN - Undefined behavior checks.

  • TSAN - Multithreading checks. Requires libtsan compatible with your compiler.

  • NONE - None of the above.

Note

ASAN, UBSAN, and SSAN can generally be stacked together without issue. TSAN is incompatible with some other sanitizer groups depending on compiler.

LIBRA_FORTIFY#
Default:

NONE. Any non-None value also sets LIBRA_LTO=YES.

Type:

CACHE STRING

Build in compiler support/runtime checking of code for heightened security. Which options get passed to compiler/linker AND which groups are supported is compiler dependent.

Important

When enabling fortification, you will likely need to compile everything with the same settings to avoid linker errors.

When passed, the value should be a comma-separated list of groups to enable:

  • STACK - Fortify the stack: add stack protector, etc.

  • SOURCE - Fortify source code via _FORTIFY_SOURCE=2.

  • FORMAT - Fortify against formatting attacks.

  • ALL - All of the above.

  • NONE - None of the above.

Added in version 0.8.3.

LIBRA_VALGRIND_COMPAT#
Default:

NO

Type:

CACHE BOOL

Disable compiler instructions in 64-bit code so that programs will run under valgrind reliably.

Build configuration#

LIBRA_FPC#
Default:

INHERIT

Type:

CACHE STRING

Enable Function Precondition Checking (FPC): checking function parameters/global state before executing a function. LIBRA defines a declarative interface for specifying what type of checking is desired; a library or application chooses how to interpret it.

Possible values:

  • NONE - Checking compiled out.

  • RETURN - If a precondition is not met, return without executing the function.

  • ABORT - If a precondition is not met, abort() the program.

  • INHERIT - Inherit from a parent project that exposes it. Default, to avoid cluttering compiler commands for projects that do not use FPC.

LIBRA_FPC_EXPORT#
Default:

NO

Type:

CACHE BOOL

Make LIBRA_FPC visible to downstream projects. Private by default.

LIBRA_ERL#
Default:

INHERIT

Type:

CACHE STRING

Specify Event Reporting Level (ERL). LIBRA provides a declarative interface for specifying the desired result of event reporting framework configuration. Possible values:

  • ALL - All event reporting compiled in.

  • FATAL - Compile out all except FATAL events.

  • ERROR - Compile out all except [FATAL, ERROR].

  • WARN - Compile out all except [FATAL, ERROR, WARN].

  • INFO - Compile out all except [FATAL, ERROR, WARN, INFO].

  • DEBUG - Compile out all except [FATAL, ERROR, WARN, INFO, DEBUG].

  • TRACE - Same as ALL.

  • NONE - All event reporting compiled out.

  • INHERIT - Inherit from a parent project. Default.

LIBRA_ERL_EXPORT#
Default:

NO

Type:

CACHE BOOL

Make LIBRA_ERL visible to downstream projects. Private by default.

Build optimization#

LIBRA_NATIVE_OPT#
Default:

NO

Type:

CACHE BOOL

Enable compiler optimizations native to the current machine. Binaries compiled this way are not portable across CPU microarchitectures. Not recommended for CI pipelines or Docker builds.

Added in version 0.9.15.

LIBRA_PGO#
Default:

NONE

Type:

CACHE STRING

Generate a Profile-Guided Optimisation build. Possible values:

  • NONE

  • GEN - Instrumentation phase. Build, run with a representative workload, then merge profile data (Clang only):

    cmake -DLIBRA_PGO=GEN ..
make
./bin/my_application
llvm-profdata merge -o default.profdata default*.profraw  # Clang only

  • USE - Optimisation phase, after collecting profile data:

    cmake -DLIBRA_PGO=USE ..
make
LIBRA_LTO#
Default:

NO

Type:

BOOL

Enable Link-Time Optimisation (LTO), also known as Interprocedural Optimisation (IPO). Compiler-independent.

Changed in version 0.8.3: Automatically enabled when LIBRA_FORTIFY != NONE.

LIBRA_STDLIB#
Default:

UNDEFINED; use compiler built-in default.

Type:

CACHE STRING

Select which standard library to use. Valid values:

  • NONE - No stdlib. Defines __nostdlib__ for all source files. For bare-metal builds.

  • CXX - Use libc++, if the compiler supports it.

  • STDCXX - Use libstdc++, if the compiler supports it.

LIBRA_OPT_REPORT#
Default:

NO

Type:

CACHE BOOL

Enable compiler-generated reports for optimizations performed, as well as suggestions for further optimizations.

Toolchain/compiler#

LIBRA_C_STANDARD#
Default:

Autodetected to the latest C standard supported by CMAKE_C_COMPILER.

Type:

CACHE STRING

Respects CMAKE_C_STANDARD if set. C_EXTENSIONS ON is set for the configured version.

Added in version 0.8.4.

LIBRA_CXX_STANDARD#
Default:

Autodetected to the latest C++ standard supported by CMAKE_CXX_COMPILER.

Type:

CACHE STRING

Respects CMAKE_CXX_STANDARD if set. CXX_EXTENSIONS ON is set for the configured version.

Added in version 0.8.4.

LIBRA_GLOBAL_C_FLAGS#
Default:

NO

Type:

CACHE BOOL

Apply all C flags set for registered targets globally via CMAKE_C_FLAGS_<build type> to all C files. Use with care — this affects external dependencies built alongside your code.

LIBRA_GLOBAL_CXX_FLAGS#
Default:

NO

Type:

CACHE BOOL

Apply all C++ flags set for registered targets globally via CMAKE_CXX_FLAGS_<build type> to all C++ files. Use with care.

Changed in version 0.9.14.

Build tooling#

LIBRA_NO_CCACHE#
Default:

NO

Type:

CACHE BOOL

Disable usage of ccache even if it is found. Useful when doing build profiling where ccache would skew timing results.

LIBRA_BUILD_PROF#
Default:

NO

Type:

CACHE BOOL

To the extent supported by the selected compiler, enable build profiling. This can be helpful in determining why you’re build is taking so long (e.g., lots of header file parsing).

LIBRA_USE_COMPDB#
Default:

YES

Type:

CACHE BOOL

Use compile_commands.json for all analysis tools. See Static analysis for when to disable this.

Added in version 0.9.36.

LIBRA_CLANG_TOOLS_USE_FIXED_DB#
Default:

TRUE

Type:

CACHE BOOL

When LIBRA_USE_COMPDB is NO, this controls how include paths and defines are passed to clang-based tools. When YES (default), flags are passed after -- (fixed compilation database convention). When NO, --extra-arg= is used for each flag.

The fixed-DB path (YES) is more reliable for projects with complex include paths or those using CPM, where include directories may contain special characters or spaces. Use the extra-arg path only if a specific tool version requires it.

Added in version 0.10.0.

See also the individual docs pages for each compiler, which describe how these variables are realized for each supported compiler.