CMake setup

Detail
See also

ORE Studio uses CMake with CMakePresets to drive its build across Linux, macOS, and Windows. Presets fix the compiler, build type, and generator in one name. compass build provides the day-to-day entry point, resolving the checkout's preset from .env. This document captures what the parts are; the recipes it links to cover how to use them. Return to Knowledge.

Detail

Preset menu

Presets are named as <platform>-<compiler>-<build_type>-<generator> where:

Axis	Values
platform	`linux`, `macos`, `windows`
compiler	`clang`, `gcc`, `msvc`, `clang-cl`
build_type	`debug`, `release`
generator	`ninja`, `make`

Full list lives in CMakePresets.json at the repository root. Typical choices:

Preset	Use
`linux-clang-debug-ninja`	Default day-to-day debug build on Linux.
`linux-clang-release-ninja`	Release on Linux.
`linux-clang-debug-make`	What `compass build` uses on this checkout (via `ORES_PRESET`).
`windows-msvc-debug-ninja`	Default debug on Windows.
`macos-clang-debug-ninja`	Default debug on macOS.

To list at the command line: see How do I list available presets?.

Output directory layout

All CMake output lands under build/output. There is one preset subdirectory plus a top-level site/ for the generated website:

build/output/
├── <preset>/                      e.g. linux-clang-debug-ninja/
│   └── publish/
│       ├── bin/                   binaries and test executables
│       └── log/
│           ├── <app>.log          per-application logs
│           └── <component>_TESTS/ test logs, scoped by component
│               └── <suite>/       e.g. domain_account_tests/
│                   └── <test>.log e.g. account_serialization_to_json.log
├── site/                          generated website (deploy_site target)
└── (project root)
    └── .claude/
        └── settings.json          Claude Code permissions (deploy_settings target)

Test log paths follow the source layout exactly: <component>_TESTS/ matches projects/<comp>/tests/ and the suite folder name matches the test-suite implementation file's stem.

Build types

CMake build types come from CMakePresets.json base configurations:

debug-build — full debug symbols, no optimisation.
release-build — optimised, no debug info.
release-with-debug-build — optimised with debug symbols (used rarely; handy for profiling).

The preset's build_type axis picks one of these. The compiler axis sets warning levels, the generator axis sets Ninja vs Make.

Building via compass

compass build is the day-to-day entry point: it reads the checkout's preset from ORES_PRESET in .env, configures the build directory on first use, and accepts targets, friendly aliases (site, manual), --preset overrides and -j for parallelism.

Used by the build recipe at How do I build the system?.

Parallel builds and tests

Ninja auto-detects CPU cores and builds in parallel by default.
Make does not. CMAKE_BUILD_PARALLEL_LEVEL needs to be set in the environment for parallel Make builds.
CTEST_PARALLEL_LEVEL controls test parallelism (both generators).

Suggested in ~/.bashrc or equivalent:

export CMAKE_BUILD_PARALLEL_LEVEL=$(nproc)
export CTEST_PARALLEL_LEVEL=$(nproc)

CI workflows set these automatically via $(nproc).

Test logging

Test logging is disabled by default for performance. It is controlled by three variables in .env: ORES_TEST_LOG_ENABLED, ORES_TEST_LOG_LEVEL (trace, debug, info, warn, error) and ORES_TEST_LOG_CONSOLE. The root CMakeLists.txt forwards every .env variable verbatim to test processes via ORES_TEST_ENV_CMD, and .env is registered as a CMAKE_CONFIGURE_DEPENDS so changes trigger an automatic re-configure on the next build.

Toggle with compass test logging on [level] / off / status (aliases: compass env init --enable-logging / --disable-logging). The variables can also be set directly in the process environment for a one-off run; the runtime listener in ores.testing reads them at test startup.

See How do I enable test logging? for the operational steps; How do I run the tests? is the surrounding test-run recipe.