Environment Configuration

Platform Requirements

  • A recent version of Linux.

  • cmake >= 3.31

  • doxygen/graphviz if you want to generate API documentation.

  • lcov/gcovr if you want to do GNU code coverage, llvm-XX if you want to do clang/LLVM code coverage.

Compiler Support

  • gcc/g++, version 9+

  • clang++/clang, version 17+

  • icpx/icx, version 2024.1+

Older compiler versions may or may not work. Note that the C and CXX compiler vendors should always match (e.g., GNU for gcc/g++), in order to avoid strange build issues (LIBRA warns if they don’t). See Compiler Support: All The Details for more details about supported compiler support.

LIBRA comes with an internal set of diagnostics targeted at GCC 12, icx 2025, and clang-21.

Important

If you are want to use the Intel compiler suite, you will have to download and install it from Intel’s website. It installs to a non-standard location, so prior to being able to use it in the terminal like clang or gcc, you will need to source the compiler definitions (actual command varies by version). Note also that only the LLVM-based Intel suite is supported; the icc/icpc legacy suited is deprecated both by Intel and LIBRA.

Repository/Code Structure Requirements

  • All C++ source files end in .cpp, and all C++ header files end in .hpp.

  • All C source files end in .c and all C header files end in .h.

  • All projects must include a cmake/project-local.cmake containing any project specific bits (i.e. adding subdirectories, what libraries to create, etc.). See project-local.cmake: How To Hook Into LIBRA for how to structure this file.

Repository/Code Structure Recommendations

These are recommended elements of repository/code structure, which can safely be ignored if you don’t want to use them.

  • All source files for a repository should live under src/ in the root. This is only required if you want to take advantage of automated source file globbing (which you should).

    See also Using cmake Globbing.

  • All tests for a project should live under the tests/ directory in the root of the project and must end in a configured prefix (see Build Time Actions) for details. Out of the box, unit tests are expected to end in -utest.{cpp, c}, integration tests are expected to end in -itest.{cpp, c}, and test harness files are expected to end in _test.{c, cpp, h, hpp}. This is only required if you want to take advantage of automated test globbing.

    See also Using cmake Globbing, LIBRA_TESTS.

  • All test harness files for a project should live under the tests/ directory in the root of the project and must end in a configured prefix (see Build Time Actions) for details. Out of the box, unit they are expected to end in _test.{c, cpp, h, hpp}. This is only required if you want to take advantage of automated test globbing.

    See also Using cmake Globbing, LIBRA_TESTS.

  • If LIBRA_DOCS is enabled, project documentation lives under <repo_name>/docs, with a docs/Doxyfile.in defined to generate doxygen documentation.

  • Use libra_add_library() to add libraries, and libra_add_executable() to add executables, so that all the LIBRA compiler/compilation magic can be applied to multiple targets, rather than only the PROJECT_NAME target.