Quickstart

This guide will get you from zero to a running LIBRA project in minutes. Before starting, ensure your system meets the Environment Configuration.

1. Choose Your Integration

Select the integration method that matches your workflow.

Best for managing dependencies and multi-repo scaling.

Step A: Configure conanfile.py

def build_requirements(self):
    self.tool_requires("libra/0.8.0")

Step B: Create CMakeLists.txt

cmake_minimum_required(VERSION 3.31)
include(libra/project)
project(my_project CXX)

Best for standard system-wide or prefix-based installs.

Step A: Install LIBRA

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

Step B: Create CMakeLists.txt

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

Best for quick prototyping or standalone repos.

Step A: Add Submodule

git submodule add https://github.com/jharwell/libra.git
ln -s libra/cmake/project.cmake CMakeLists.txt

Note: The symbolic link replaces the need for a manual CMakeLists.txt.

2. Configure Your Project

LIBRA expects your logic to live in cmake/project-local.cmake. This keeps your root CMakeLists.txt clean and portable.

Create cmake/project-local.cmake:

# LIBRA auto-discovers files in src/ and tests/
# Just declare the target type:
libra_add_executable(${${PROJECT_NAME}_CXX_SOURCE})

# Optional: Enable project-wide quality gates
set(LIBRA_ANALYSIS ON)
set(LIBRA_FORTIFY ON)

3. Build & Run

Use standard CMake workflows. LIBRA provides the convenience targets.

# Configure and enable tests
cmake -B build -DLIBRA_TESTS=YES

# Build everything
cmake --build build

# Run the LIBRA "all-in-one" test target
make -C build build-and-test

Project Structure

By following this convention, LIBRA requires zero manual file listing:

my_project/
├── CMakeLists.txt           # Framework entry point
├── cmake/
│   └── project-local.cmake  # Target definitions
├── src/                     # .cpp/.c files (Auto-discovered)
├── include/                 # Public headers
├── tests/                   # *-utest.cpp (Auto-discovered)
└── build/                   # Build artifacts

Common Workflows

See Build Time Actions for full documentation.

Build & Run Tests

make build-and-test

Generate Code Coverage

GNU/gcov:

cmake -B build -DCMAKE_BUILD_TYPE=Debug -DLIBRA_CODE_COV=ON
cd build
make all-tests && make test && make gcovr-report
# Open coverage/index.html

Clang/llvm-cov:

cmake -B build -DCMAKE_BUILD_TYPE=Debug -DLIBRA_CODE_COV=ON -DLIBRA_CODE_COV_NATIVE=YES
cd build
make all-tests && make test && make llvm-coverage
# Open coverage/index.html

Profile-Guided Optimization

# Phase 1: Generate profile
cmake -B build -DLIBRA_PGO=GEN
cd build && make && ./bin/my_app

# Phase 2: Optimize (Clang requires merging profiles)
llvm-profdata merge -o default.profdata default*.profraw  # Clang only
cmake -B build -DLIBRA_PGO=USE
make

Static Analysis

cmake -B build -DLIBRA_ANALYSIS=ON
cd build
make analyze              # Run all analyzers
make analyze-clang-tidy   # Just clang-tidy
make fix-clang-tidy       # Auto-fix issues

Sanitizers (Debug Builds)

cmake -B build -DCMAKE_BUILD_TYPE=Debug -DLIBRA_SAN="ASAN+UBSAN"
cd build && make && make test