Quickstart — CLI#

This page gets you to a working build in under five minutes. For a complete walkthrough including tests, coverage, and analysis, see New project setup.

If you have not installed clibra yet, start at Installation.

1. Set up your project#

You must define the CMake base layer:

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)

For other integration methods (Conan, installed package, submodule), see Integrating LIBRA into your 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)

You also must define CMake presets; clibra is entirely preset driven:

CMakePresets.json:
{
  "version": 6,
  "configurePresets": [
    {
      "name": "base",
      "hidden": true,
      "generator": "Ninja",
      "binaryDir": "${sourceDir}/build/${presetName}",
      "cacheVariables": {
        "LIBRA_TESTS":    "OFF",
        "LIBRA_COVERAGE": "OFF",
        "LIBRA_ANALYSIS": "OFF",
        "LIBRA_DOCS":     "OFF"
      }
    },
    {
      "name": "debug",
      "inherits": "base",
      "cacheVariables": {
        "CMAKE_BUILD_TYPE": "Debug",
        "LIBRA_TESTS": "ON",
        "LIBRA_FORMAT": "ON"
      }
    },
    {
      "name": "release",
      "inherits": "base",
      "cacheVariables": {
        "CMAKE_BUILD_TYPE": "Release",
        "LIBRA_LTO": "ON"
      }
    },
    {
      "name": "coverage",
      "inherits": "base",
      "cacheVariables": {
        "CMAKE_BUILD_TYPE": "Debug",
        "LIBRA_TESTS": "ON",
        "LIBRA_COVERAGE": "ON"
      }
    },
    {
      "name": "ci",
      "inherits": "coverage"
    },
    {
      "name": "analyze",
      "inherits": "base",
      "cacheVariables": {
        "CMAKE_BUILD_TYPE": "Debug",
        "LIBRA_ANALYSIS": "ON"
      }
    }
  ],
  "buildPresets": [
    { "name": "debug",    "configurePreset": "debug" },
    { "name": "release",  "configurePreset": "release" },
    { "name": "coverage", "configurePreset": "coverage" },
    { "name": "ci",       "configurePreset": "ci" },
    { "name": "analyze",  "configurePreset": "analyze",
      "targets": ["analyze"] }
  ],
  "testPresets": [
    {
      "name": "debug",
      "configurePreset": "debug",
      "output": { "outputOnFailure": true }
    },
    {
      "name": "coverage",
      "configurePreset": "coverage",
      "output": { "outputOnFailure": true }
    },
    {
      "name": "ci",
      "configurePreset": "ci",
      "output": { "outputOnFailure": true }
    }
  ]
}

2. Build and test#

clibra build --preset debug   # configure + build
clibra test  --preset debug   # build tests + run

3. Inspect your build#

clibra doctor   # check tool availability
clibra info     # show feature flags and available targets

Troubleshooting#

See Troubleshooting for common errors.

Next steps#