Configure-Time
File Discovery
All files under
src/ending in:.c.cpp
are globbed as source files (see Requirements to use LIBRA for repository layout requirements) so that if you add a new source file, rename a source file, etc., you just need to re-run cmake. This means you don’t have to MANUALLY specify all the files in the cmake project. Woo-hoo!
Note
See Using cmake Globbing for rationale on why globs are used, contrary to common cmake guidance.
All files under
tests/ending in a specified pattern are recursively globbed as unit test files which will be compiled into executable unit tests at build time ifLIBRA_TESTS=YES. See Variables more details on this configuration item. Same for integration tests.${LIBRA_INTEGRATION_TEST_MATCHER.{c,cpp}}.All files under
tests/ending in a specified pattern are recursively globbed as the test harness for unit/integration tests. All test harness files will be compiled into static libraries at build time and all test targets link against them ifLIBRA_TESTS=YES.
Note
The difference between unit tests and integration tests is purely semantic, and exists solely to help organize your tests. LIBRA treats both types of tests equivalently.
The following variables are available for fine-tuning the cmake configuration
process. All of these variables can be specified on the command line via -D,
or put in your project-local.cmake–see project-local.cmake: How To Hook Into LIBRA for
details.
Knobs For Configuring LIBRA/Cmake
The location where cmake should search for other locally installed
libraries (e.g., $HOME/.local). VERY useful to separate out 3rd party
headers which you want to suppress all warnings for by treating them as
system headers when you can’t/don’t want to install things as root.
Only available if LIBRA_DRIVER=SELF.
Default: $HOME/.local/system
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.
Default: SELF.
Show a configuration summary after the configuration step finishes.
Default: NO.
Knobs For Supporting SW Engineering
Enable documentation build via make apidoc.
Default: NO.
Build in runtime code-coverage instrumentation for use with make
precoverage-report and make coverage-report.
Default: NO.
Build in runtime checking of code using any compiler. When passed, the value should be a comma-separated list of sanitizer groups to enable:
MSAN- Memory checking/sanitization.ASAN- Address sanitization.SSAN- Aggressive stack checking.UBSAN- Undefined behavior checks.TSAN- Multithreading checks.None- None of the above.
The first 4 can generally be stacked together without issue. Depending on compiler; the thread sanitizer is incompatible with some other sanitizer groups.
Default: “None”.
Enable static analysis targets for checkers, formatters, etc. See below for the targets enabled (assuming the necessary executables are found).
Default: NO.
Enable compiler-generated reports for optimizations performed, as well as suggestions for further optimizations.
Default: NO.
Build in compiler support/runtime checking of code for heightened security. Which options get passed to compiler/linker AND which groups are supported is obviously compiler dependent.
Important
When enabling things using this variable, you probably will have to compile everything with the same settings to avoid getting 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.LIBCXX_FAST- Fortify libc++ with the set of “fast” checks. clang only. See here for more details. LIBRA does not currently set clang to use libc++ for you.LIBCXX_EXTENSIVE- Fortify libc++ with the set of “extensive” checks. clang only. See here for more details. LIBRA does not currently set clang to use libc++ for you.LIBCXX_DEBUG- Fortify libc++ with a comprehensive set of debug checks that might slow things down a lot. clang only. See here for more details. LIBRA does not currently set clang to use libc++ for you.CFI- Fortify against Control Flow Integrity (CFI) attacks. clang only.GOT- Fortify against Global Offset Table (GOT) attacks with read-only relocations and immediate symbol binding on load.FORMAT- Fortify against formatting attacks.ALL- All of the above.NONE- None of the above.
Default: NONE. Any non-None value also sets LIBRA_LTO=YES.
Added in version 0.8.3.
Enable building of tests via:
make unit-tests(unit tests only)make integration-tests(integration tests only)make tests(all tests)
Default: NO.
Knobs For Configuring Builds
Enable multithreaded code/OpenMP code via compiler flags (e.g.,
-fopenmp), and/or selecting additional code for compilation.
Default: NO.
Enable multiprocess code/MPI code for the selected compiler, if supported.
Default: NO.
Enable Function Precondition Checking (FPC): checking function parameters/global state before executing a function, for functions which a library/application has defined conditions for. LIBRA does not define how precondition checking is implemented for a given library/application using it, only a simple declarative interface for specifying what type of checking is desired at build time; a library application can choose how to interpret the specification. This flexibility and simplicity is part of what makes LIBRA a very useful build process front-end across different projects.
FPC is, generally speaking, mostly used in C, and is very helpful for debugging, but can slow things down in production builds. Possible values for this option are:
NONE- Checking compiled out.RETURN- If at least one precondition is not met, return without executing the function. Do not abort() the program.ABORT- If at least one precondition is not met, abort() the program.INHERIT- FPC configuration should be inherited from a parent project which exposes it.
Default: RETURN.
Specify Event Reporting Level (ERL). LIBRA does not prescribe a given event reporting framework (e.g., log4ccx, log4c) which must be used. Instead, it provides a simple declarative interface for specifying the desired result of framework configuration at the highest level. Possible values of this option are:
ALL- Event reporting is compiled in fully and linked with; that is, all possible events of all levels are present in the compiled binary, and whether an encountered event is emitted is dependent on the level and scope of the event (which may be configured at runtime).
FATAL- Compile out event reporting EXCEPT FATAL events.
ERROR- Compile out event reporting EXCEPT [FATAL, ERROR] events.
WARN- Compile out event reporting EXCEPT [FATAL, ERROR, WARN] events.
INFO- Compile out event reporting EXCEPT [FATAL, ERROR, WARN, INFO] events.
DEBUG- Compile out event reporting EXCEPT [FATAL, ERROR, WARN, INFO, DEBUG] events.
TRACE- Same asALL.
NONE- All event reporting compiled out.
INHERIT- Event reporting configuration should be inherited from a parent project which exposes it.
Default: “”.
Generate a PGO build for the selected compiler, if supported. Possible values for this option are:
NONEGEN- Input stageUSE- Final stage (after executed theGENbuild to get profiling info).
Default: NONE.
Disable compiler instructions in 64-bit code so that programs will run under valgrind reliably.
Default: NO.
Enable Link-Time Optimization.
Default: NO.
Changed in version 0.8.3: This is automatically enabled by LIBRA_FORTIFY != NONE.
Enable using the standard library. You would only turn this off for bare-metal builds (e.g., bootstraps).
Default: YES.
Disable generation of debug symbols independent of whatever the default is with a given cmake build type.
Default: NO.
Added in version 0.8.4.