Building
Manual CMake configuration for the engine and C ABI, the Rust workspace that builds Doppio, and the test commands used by CI and agents.
Engine (C++20 + CMake)#
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j
For editor work, build only the C ABI after a source change:
cmake --build build --target caffeine-capi -j
Artifacts#
| Target | Output | Purpose |
|---|---|---|
caffeine-core | build/libcaffeine-core.a | Engine library without ImGui or editor code. |
caffeine-capi | build/libcaffeine-capi.so / .dylib / .dll | Stable C ABI loaded by Doppio and external frontends. |
caffeine-runtime | build/caffeine-runtime | Standalone ImGui runtime host for scenes. |
caffeine-combined | build/caffeine-combined | Combined runtime build with the editor-support shim. |
caffeine-render-snapshot | build/caffeine-render-snapshot | Reference-scene renderer for visual regression images. |
caf-encode | build/caf-encode | Legacy CAF encoder; prefer the caf-pack CLI. |
| Doppio plugins | build/plugins/*.so | Every plugin from the doppio-plugins submodule, loaded on demand. |
Doppio (Rust 2021 + Iced 0.14)#
Build the C ABI first, then the workspace:
cd doppio
cargo build -p doppio-ui
cargo run -p doppio-ui
The binaries are written to doppio/target/<profile>/doppio and
doppio/target/<profile>/doppio-headless (the latter requires the headless
feature). The release profile is the one used by the launcher:
cd doppio
cargo build --release -p doppio-ui
Common CMake options#
| Option | Default | Effect |
|---|---|---|
CAFFEINE_BUILD_HEADLESS | OFF | Builds caffeine-core without SDL3 or RHI for servers and CI. |
CAFFEINE_ENABLE_SCRIPTING | ON | Lua 5.4 + sol2 bindings and the script system. |
CAFFEINE_ENABLE_BULLET3 | ON | Bullet3 rigid-body physics. |
CAFFEINE_BUILD_DOPPIO_PLUGINS | ON | Builds every plugin from doppio-plugins into build/plugins; set OFF for minimal or headless builds. |
CMAKE_BUILD_TYPE | Debug | Use Release for editor and benchmark work. |
Note. If the doppio-plugins submodule is missing,
configure fails with an explicit message. Run ./scripts/submodules.sh
or pass -DCAFFEINE_BUILD_DOPPIO_PLUGINS=OFF.
Tests#
C++ engine#
cd build
ctest --output-on-failure
The Catch2 binary is build/tests/CaffeineTest; run a single tag or test directly:
./build/tests/CaffeineTest "[ecs]"
Rust editor#
cd doppio
cargo test -p doppio-ui
cargo test -p doppio-ui --features headless
The headless feature runs the committed UI flows in
doppio/tests/ui-flows/. The combined check used by CI is:
./scripts/check-rust-ui.sh
Headless driver#
./scripts/doppio-headless.sh widgets
./scripts/doppio-headless.sh run doppio/tests/ui-flows --format text
See the headless guide for the full action reference, screenshots, baselines and GIF/MP4 recording.
Platform helpers#
| Command | Platform | What it does |
|---|---|---|
./scripts/build.sh debug |
Linux/macOS | Configure and build Debug |
./scripts/build.sh release |
Linux/macOS | Configure and build Release |
./scripts/build.sh test |
Linux/macOS | Debug build followed by ctest |
./scripts/build.sh rebuild |
Linux/macOS | Remove build/, configure and build |
./scripts/build.sh clean |
Linux/macOS | Remove build/ |
scripts\build.bat |
Windows | Windows build helper |
./scripts/build.fish |
Fish shell | Fish variant |
./scripts/build-launcher.sh |
Linux/macOS | Builds the Rust launcher |
Cleaning#
rm -rf build doppio/target
Reconfigure after deleting build/. Cargo caches are safe to delete but make the
next Rust build slower.