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.

LIBRA_PROJECT_VERSION#

Full version string without the leading v, e.g. 1.5.0-dev.3 or 1.5.0. For untagged commits this contains a synthetic suffix such as 1.5.0-dev.3.untagged.5+gabcdef.

LIBRA_PROJECT_VERSION_NUMERIC#

The MAJOR.MINOR.PATCH component only. Safe to pass directly to project(VERSION ...) and CPMAddPackage(VERSION ...).

LIBRA_PROJECT_VERSION_PRERELEASE#

The prerelease identifier without the leading -, e.g. dev.3 or rc.1. Empty string for stable releases.

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:

CACHE 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_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_OPT_NATIVE#
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_OPT_NO_GUARDS#
Default:

NO

Type:

CACHE BOOL

Remove compiler safety scaffolding to improve performance at the cost of debugging (e.g., remove the frame pointer). Always safe to enable in release builds.

Added in version 0.12.8.

LIBRA_OPT_INLINE#
Default:

NO

Type:

CACHE BOOL

Improve code visibility for the compiler across TU/library boundaries. Helps inlining and devirtualizing in shared libs. Always safe to enable in release builds.

Added in version 0.12.8.

LIBRA_OPT_LINKER#
Default:

NO

Type:

CACHE BOOL

Eliminate dead code at link time to reduce binary size and improve icache utilization.

Added in version 0.12.8.

LIBRA_OPT_NO_EXCEPTIONS#
Default:

NO

Type:

CACHE BOOL

Disable exception handling (C++ only). Turns exceptions into aborts in the STL, and removes stack unwinding code which can reduce binary size. Has no effect on C compilation.

Added in version 0.12.8.

LIBRA_OPT_NO_RTTI#
Default:

NO

Type:

CACHE BOOL

Disable RunTime Type Information (C++ only). If you don’t use typeid, dynamic_cast, etc. then this can reduce binary size. See also :cmake:variable`LIBRA_OPT_LINKER`.

Added in version 0.12.8.

LIBRA_OPT_FAST_MATH#
Default:

NO

Type:

CACHE BOOL

Relax floating point correctness requirements to squeeze maximum performance; may change numerical results. Validate correctness before enabling!

Added in version 0.12.8.

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

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