Quickstart — CMake only#

This page gets you to a working build using plain CMake. For a complete walkthrough, see New project setup. To add LIBRA to an existing project, see Adding Libra To An Existing Project.

If you have Rust installed and want shorter commands for day-to-day work, see Quickstart — CLI. The project structure and CMakePresets.json are identical — the CLI can be added at any time.

1. Set up your project#

See Project setup for all integration methods, layout conventions, and the recommended preset hierarchy. The minimum:

cmake_minimum_required(VERSION 3.31)

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")

# Prefer local packages when present — useful for simultaneous
# local development of multiple LIBRA-enabled projects.
set(CPM_USE_LOCAL_PACKAGES ON)
include(${CMAKE_CURRENT_BINARY_DIR}/cmake/CPM.cmake)

CPMAddPackage(
  NAME libra
  GIT_REPOSITORY https://github.com/jharwell/libra.git
  GIT_TAG master)

list(APPEND CMAKE_MODULE_PATH ${libra_SOURCE_DIR}/cmake)
project(my_project C CXX)
include(libra/project)

# Register the main executable. CXX_SRC is auto-populated
# from src/ at configure time.
libra_add_executable(${${PROJECT_NAME}_CXX_SRC})

# For a library instead (C_SRC auto-populated):
# libra_add_library(${${PROJECT_NAME}_C_SRC})

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

2. Configure and build#

You can use any preset you have defined, not just “debug”; see CMakePresets.json for more info about CMake presets.

cmake --preset debug
cmake --build --preset debug -j$(nproc)

cmake -B build -DCMAKE_BUILD_TYPE=Debug
cmake --build build -j$(nproc)

3. Run tests#

cmake --build --preset debug --target all-tests
ctest --preset debug --output-on-failure

4. What’s available#

cmake --build --preset debug --target help-targets

Troubleshooting#

See Troubleshooting.

Next steps#