Installation¶

This page covers building Tero from source: host requirements, the two supported toolchain paths (system packages or nix develop), the build itself, verification, and troubleshooting.

flowchart LR
    A[Install toolchain<br/>GCC/Clang + CMake + Ninja + LLVM≥18] --> B[git clone]
    B --> C["cmake --preset default<br/>(fetches fmt / tl::expected / Catch2)"]
    C --> D["cmake --build build"]
    D --> E["ctest --test-dir build"]
    E --> F[./build/src/app/tero-emu]

Host requirements¶

Tero is developed and CI-tested on Linux x86-64. Linux ARM64 and macOS are functional but not CI-validated.

The C++ library dependencies (fmt, tl::expected, Catch2) are fetched automatically by CMake's FetchContent — they do not need to be installed on the host. The vendored SoftFloat 3e lives under third-party/softfloat3e/. LLVM is the exception: it is a mandatory build dependency for the binary-translation JIT and is not fetched — you must install LLVM ≥ 18 dev libraries on the host (see the table and the per-distribution commands below). As a reproducible alternative to installing the toolchain manually, the repo ships a flake.nix that pins everything — LLVM included — to known-good versions (see the Nix option below).

Strict host requirements (must be present)¶

find_package(LLVM REQUIRED CONFIG)
if(LLVM_PACKAGE_VERSION VERSION_LESS 18)
    message(FATAL_ERROR
        "Tero requires LLVM >= 18 (found ${LLVM_PACKAGE_VERSION})")
endif()

Optional tools¶

Choose your toolchain path¶

sudo dnf install cmake ninja-build gcc-c++ llvm-devel git \
                 python3 doxygen ncurses-compat-libs

sudo apt install cmake ninja-build g++ llvm-18-dev git \
                 python3 doxygen libtinfo5

brew install cmake ninja llvm git python doxygen

# Enter the dev shell (first run downloads the pinned toolchain):
nix develop

# With direnv (automatic shell activation on cd):
#   1. Install nix-direnv: https://github.com/nix-community/nix-direnv
#   2. direnv allow        # (once, in the repo root)

RTEMS cross-toolchain¶

For full test coverage (RTEMS boot, sptests, GDB interop) and to build your own RTEMS guests, install the Cobham Gaisler RCC 1.3.2 toolchain and put sparc-gaisler-rtems5-gcc and sparc-gaisler-rtems5-gdb on PATH. The default install prefix the build scripts expect is /opt/rcc-1.3.2-gcc/. RCC 1.3.2 ships RTEMS 5.x. See First RTEMS boot and Testing for details on the conditional test skips that fire when the toolchain is absent.

Cloning¶

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

Tero has three automatically-fetched C++ libraries and one vendored dependency:

The three fetched libraries are pinned to the tags above in CMakeLists.txt and downloaded on the first cmake configure; later builds reuse the contents of build/_deps/.

LLVM (≥ 18) must be installed before configuring — it is linked into tero_jit and is the one non-fetched, non-vendored dependency. Whether tero-emu also needs the LLVM shared library at run time depends on how your host packages LLVM (static component archives vs. libLLVM.so). The only other external runtime library is libtinfo.so.5, used by the SPARC GDB cross-debugger; everything else is header-only or statically linked.

Building¶

The repo ships CMake presets (CMakePresets.json). The default preset is a RelWithDebInfo Ninja build into build/ and matches CI:

cmake --preset default
cmake --build --preset default

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

Both produce the same tree. The build emits:

• build/src/app/tero-emu — the standalone CLI (CLI reference)
• build/src/runtime/libtero_runtime.a — the runtime library to embed
• build/examples/hello-gr712rc/hello-gr712rc, .../hello-gr740, .../gdb-demo/gdb-demo — the worked examples
• build/tests/... — Catch2 test executables (when TERO_BUILD_TESTS=ON)

Available presets¶

CMake options¶

Example debug build with opcode histograms:

cmake -S . -B build-debug -G Ninja \
      -DCMAKE_BUILD_TYPE=Debug \
      -DTERO_OPCODE_HISTOGRAM=ON
cmake --build build-debug --target tero-emu

Verifying¶

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

Expected outcome: all tests pass with a small number of conditional skips that fire only when external artifacts are unavailable — the GDB interop test (no sparc-gaisler-rtems5-gdb), the RTEMS boot test (no pre-built RTEMS ELFs), and the RTEMS-aware live-guest test (no nm). All other tests are unconditional. The suite also covers the binary-translation path: IR/JIT lockstep against the interpreter plus a sanitiser-clean tero_jit_tests executable.

To run a focused subset:

ctest --test-dir build -R rtems_sptests --output-on-failure   # RTEMS sptests only
ctest --test-dir build -j 4                                    # parallel

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:
zensical serve

Open http://127.0.0.1:8000/ for the live preview. zensical build produces a static site/ directory ready for GitHub Pages, S3 or any plain static host. (In the nix develop shell, run pip install -r docs/requirements.txt first — see the note below.)

Troubleshooting¶

Next: the Quickstart runs your first SPARC instruction in under five minutes.