clibra-0.9.5 is not a library.

.. SPDX-License-Identifier: MIT

.. |version-master| image:: https://img.shields.io/github/v/tag/jharwell/libra?filter=!*.beta*&label=master&sort=semver :target: https://github.com/jharwell/libra/releases :alt: Latest release tag

.. |version-devel| image:: https://img.shields.io/github/v/tag/jharwell/libra?filter=*-*&include_prereleases&label=devel&sort=semver :target: https://github.com/jharwell/libra/releases :alt: Latest devel tag

.. figure:: docs/figures/libra-logo-banner-light-text.png

================================ Luigi Builds Reusable Automation

LIBRA is a declarative CMake framework that standardizes compiler flags, testing, analysis, and packaging for C/C++ projects with near-zero configuration.

Near-Zero Boilerplate: Define your project in just a few lines of CMake.
Secure by Default: Automatic hardening flags and sanitizers.
Unified Tooling: One interface for GCC, Clang, and Intel compilers.
Quality Tooling Built-In: Native targets for coverage, analysis, and docs.

Keywords: CMake framework, C/C++ build automation, sanitizers, coverage, static analysis, reproducible builds

How LIBRA Works

LIBRA is a collection of CMake modules that:

#. Define opinionated, best-practice defaults #. Auto-discover sources and tests #. Generate standard quality targets

You still write CMake, but far less of it; LIBRA layers on top of CMake. It does not replace your build system.

Why Use LIBRA?

You maintain multiple C/C++ projects with similar build needs.
You want consistent builds across compilers.
You are tired of copy-pasting CMake boilerplate.
You need reproducible builds with modern defaults.
You want tests and quality tooling with minimal effort.

Why Not Use LIBRA?

LIBRA prioritizes consistency and automation over maximal flexibility. You may want to choose a different approach if:

You use non-CMake build systems.
You require Windows/MSVC.
You depend on exotic or unsupported toolchains.
You need per-file compiler flag micromanagement.

Quick Example

Before LIBRA (Standard CMake):

.. code-block:: cmake

50+ lines to set up:

- Compiler flags for Debug/Release

- Sanitizer configuration with compiler detection

- Code coverage setup

- Test discovery and CTest integration

- Static analysis targets

... (boilerplate continues)

After LIBRA:

.. code-block:: cmake

CMakeLists.txt (4 lines)

cmake_minimum_required(VERSION 3.31) find_package(libra REQUIRED) project(myproj CXX) include(libra/project)

.. code-block:: cmake

cmake/project-local.cmake (2 lines)

libra_add_executable(${${PROJECT_NAME}_CXX_SOURCE}) set(LIBRA_SAN "ASAN+UBSAN") # Sanitizers on any compiler

Build:

.. code-block:: bash

cmake -B build -DLIBRA_TESTS=ON -DLIBRA_CODE_COV=ON -DLIBRA_DOCS=ON make -C build analyze # Run all static analysis tools make -C build build-and-test gcovr-report # Tests run + coverage report generated make -C build apidoc # Build API documentation make -C build format # Format all source files

Key Features And Architecture

Unified compiler abstraction
Sanitizers (ASAN, UBSAN, TSAN, MSAN, SSAN)
Static analysis (clang-check, clang-tidy, cppcheck)
Coverage (gcovr, llvm-cov)
Profile-guided optimization (PGO)
Automatic source file and test discovery and registration
Robust compiler warnings

All of the above comes "for free" with a project layout like this::

my_project/ ├── CMakeLists.txt # Minimal: find_package + project() ├── cmake/ │ └── project-local.cmake # Your targets and configuration ├── docs/ │ ├── conf.py # Your sphinx configuration │ └── Doxyfile.in # Your API doc configuration ├── src/ # Auto-discovered source files ├── include/ # Auto-discovered headers ├── tests/ # Auto-discovered tests (*-{u,i,r}test.{c,cpp}) └── build/ # Build artifacts (git-ignored)

At a high level, LIBRA works like this:

.. figure:: docs/figures/arch.png

Installation

There are two ways to consume LIBRA depending on whether you want the optional CLI companion tool.

Using LIBRA in a C/C++ Project (CMake only)

This is the core use case. No additional tooling is required beyond CMake.

Recommended: CPM (CMake Package Manager)

CPM is the recommended approach for most projects. It requires no pre-installation, pins the version in your project, and works automatically during configure.

.. code-block:: cmake

file(DOWNLOAD https://github.com/cpm-cmake/CPM.cmake/releases/download/v0.40.2/CPM.cmake ${CMAKE_CURRENT_BINARY_DIR}/cmake/CPM.cmake) set(CPM_SOURCE_CACHE $ENV{HOME}/.cache/CPM CACHE PATH "CPM source cache") include(${CMAKE_CURRENT_BINARY_DIR}/cmake/CPM.cmake) cpmaddpackage( NAME libra GIT_REPOSITORY https://github.com/jharwell/libra.git)

Alternative: Conan

If your project already uses Conan for dependency management:

.. code-block:: bash

git clone https://github.com/jharwell/libra conan create .

Alternative: System-wide install

Suitable for teams that manage build tooling centrally:

.. code-block:: bash

git clone https://github.com/jharwell/libra cmake -S libra -B build cmake --build build --target install

Alternative: git submodule

If you prefer to vendor dependencies directly in your repository:

.. code-block:: bash

git submodule add https://github.com/jharwell/libra

Using the LIBRA CLI

The LIBRA CLI is a Rust-based companion tool that adds project scaffolding and other workflow conveniences on top of the CMake framework. The CLI requires a compatible LIBRA CMake installation — it locates and orchestrates an existing install rather than bundling its own copy.

Prerequisites: Install LIBRA via one of the CMake options above, then:

.. code-block:: bash

cargo install libra-cli

The CLI will detect your LIBRA installation automatically. If none is found, it will exit with a clear error indicating which version is required.

.. note::

If you have not yet set up a LIBRA CMake installation, you can use the --bootstrap flag to have the CLI install LIBRA into a per-user cache (~/.local/share/libra) without affecting any system-wide installs:

.. code-block:: bash

  libra --bootstrap

With the CLI installed, you can scaffold a new project instead of copying the Quick Example by hand:

.. code-block:: bash

libra init my_project cd my_project cmake -B build make -C build

FAQ

Does LIBRA replace CMake? No. LIBRA is a layer on top of CMake that adds conventions and automation.

Can I mix LIBRA and plain CMake targets? Yes. Generally speaking, only targets created with libra_* macros receive LIBRA features.

Is globbing mandatory? No. You may override discovery with explicit source lists.

Does LIBRA enforce its project layout? LIBRA assumes conventional layouts by default, but most paths are configurable.

Can I disable individual features? Yes. All major features (sanitizers, coverage, analysis, docs) are opt-in.

Does the CLI bundle its own copy of LIBRA? No. The CLI locates an existing LIBRA CMake installation on your system. This avoids version conflicts with projects that already manage LIBRA as a CMake dependency. Use --bootstrap for a user-local install if you have not installed LIBRA separately.

Do I need the CLI to use LIBRA? No. The CLI is an optional convenience layer. All CMake functionality is available without it. The main benefit of the CLI is the libra init scaffolding command, which generates the project skeleton for you instead of copying the Quick Example by hand.

Requirements

CMake framework (all users)

Platform: Linux/Unix, macOS

Build Tools: CMake >= 3.31

Compilers: GCC >= 9, Clang >= 14, Intel >= 2025.0

CLI (optional)

Rust toolchain >= 1.75 (install via rustup <https://rustup.rs>_)

A compatible LIBRA CMake installation (or use libra --bootstrap)

clibra 0.9.5

================================ Luigi Builds Reusable Automation

How LIBRA Works

Why Use LIBRA?

Why Not Use LIBRA?

Quick Example

50+ lines to set up:

- Compiler flags for Debug/Release

- Sanitizer configuration with compiler detection

- Code coverage setup

- Test discovery and CTest integration

- Static analysis targets

... (boilerplate continues)

CMakeLists.txt (4 lines)

cmake/project-local.cmake (2 lines)

Key Features And Architecture

Installation

Using LIBRA in a C/C++ Project (CMake only)

Using the LIBRA CLI

FAQ

Requirements