Skip to content

Installation

Host requirements

Lince is developed and CI-tested on Linux x86-64. Linux ARM64 and macOS should work but are not part of the validation matrix.

Tool Minimum version Notes
CMake 3.25 Presets are required.
Ninja 1.10 Recommended generator (-G Ninja).
C++ compiler GCC ≥ 12 or Clang ≥ 16 Must support C++20, including concepts and std::span.
Git any For cloning + FetchContent.
Python 3.10+ Only needed to build the documentation site.
Doxygen 1.9+ Optional — required only when building the API reference.
doxybook2 1.5+ Optional — converts Doxygen XML to Markdown.

For RTEMS testing you also need a SPARC cross-toolchain (RCC 1.3.2 is the canonical choice; see Testing).

Cloning

git clone https://github.com/claaj/lince.git
cd lince

Lince has two automatically-fetched dependencies (Catch2 and tl::expected) and one vendored dependency (Berkeley SoftFloat 3e under third-party/softfloat3e/). No manual apt install of libraries is required.

Building

The standard out-of-tree build:

cmake -S . -B build -G Ninja
cmake --build build

This produces:

  • build/src/app/lince-emu — the standalone CLI
  • build/src/runtime/liblince_runtime.a — the runtime library
  • build/tests/... — Catch2 test executables (when LINCE_BUILD_TESTS=ON)

CMake options

Option Default Effect
LINCE_BUILD_TESTS ON Builds Catch2 + the unit/integration test tree.
LINCE_BUILD_DOCS OFF Adds the docs target (Doxygen + doxybook2 + MkDocs).
CMAKE_BUILD_TYPE RelWithDebInfo Toggle Debug, Release, etc.

Example debug build with documentation:

cmake -S . -B build -G Ninja \
      -DCMAKE_BUILD_TYPE=Debug \
      -DLINCE_BUILD_DOCS=ON
cmake --build build --target lince-emu docs

Verifying

ctest --test-dir build --output-on-failure

Expected outcome: 263 tests pass with one conditional skip (test_rtems_boot, which requires the cross-compiled RTEMS hello binary). All other tests are unconditional.

Building the documentation locally

python3 -m venv .venv
source .venv/bin/activate
pip install -r docs/requirements.txt

# 1. C++ API extraction (optional, requires doxygen + doxybook2):
doxygen docs/Doxyfile
doxybook2 --input build/doxygen/xml --output docs/api --config docs/doxybook2.json

# 2. Render and serve:
mkdocs serve

Open http://127.0.0.1:8000/ and navigate the live preview. mkdocs build produces a static site/ directory ready for GitHub Pages, S3 or any plain static host.

CMake convenience

With -DLINCE_BUILD_DOCS=ON the build also exposes cmake --build build --target docs, which runs the three steps above behind a single command.