Build guide
The repository ships small CMake wrappers instead of a separate build tool. This page documents what each wrapper does, the exact commands it runs and the checks that must pass before a pull request.
One command#
./scripts/build.sh # Debug build (default)
./scripts/build.sh release # Release build
./scripts/build.sh test # Debug build, then ctest
./scripts/build.sh rebuild # Delete build/, configure, build
./scripts/build.sh clean # Delete build/
Windows:
scripts\build.bat
scripts\build.bat release
scripts\build.bat test
Fish shell:
./scripts/build.fish release
The wrappers are convenience only; every step is a normal CMake command.
What the wrapper runs#
| Step | Command |
|---|---|
| Dependency check | cmake and python3 on PATH |
| Configure | cmake -DCMAKE_BUILD_TYPE=<type> .. from build/ |
| Build | cmake --build . --parallel <cores> |
| Test | ctest --output-on-failure |
The wrapper auto-detects CPU cores with nproc (Linux), sysctl (macOS) or falls
back to four.
Building Doppio#
The Rust editor is not built by CMake. After the C ABI exists:
cmake --build build --target caffeine-capi -j
cd doppio
cargo build -p doppio-ui
cargo run -p doppio-ui
For a launcher-compatible release binary:
cd doppio
cargo build --release -p doppio-ui
# doppio/target/release/doppio
Plugins#
The engine build compiles every plugin from the doppio-plugins submodule into
build/plugins. There is no second plugin build step:
./scripts/submodules.sh
./scripts/build.sh release
ls build/plugins
To skip plugins in a minimal or headless environment:
cmake -S . -B build -DCAFFEINE_BUILD_DOPPIO_PLUGINS=OFF
Plugins target the legacy C++/ImGui SDK under include/caffeine/plugin/ and
include/caffeine/ui/, not the Rust UI.
Tests and checks#
cd build && ctest --output-on-failure
cd doppio && cargo test -p doppio-ui
./scripts/check-rust-ui.sh
check-rust-ui.sh runs:
cargo fmt --checkcargo testfor the workspacecargo check --features agentcargo clippy -- -D warnings- the
caffeine-core/ ImGui coupling audit - the headless flow suite
Headless UI checks:
./scripts/doppio-headless.sh run doppio/tests/ui-flows --format text
./scripts/doppio-headless.sh screenshot --annotate --out /tmp/doppio-shots
Documentation checks#
From caffeine-website/:
python3 scripts/audit-docs.py --include-engine
python3 scripts/audit-docs-i18n.py
These validate links, images, source paths, HTML rules and EN/PT structure. See
DOCS_STYLE.md.
Troubleshooting#
| Symptom | Fix |
|---|---|
doppio-plugins submodule is missing | ./scripts/submodules.sh or -DCAFFEINE_BUILD_DOPPIO_PLUGINS=OFF |
| SDL3 not found | Install SDL3 or configure with -DCAFFEINE_BUILD_HEADLESS=ON for core-only work |
Doppio cannot load libcaffeine-capi | Build the caffeine-capi target and set CAFFEINE_ENGINE_ROOT if the trees are separate |
| Rust build fails after a C ABI change | Rebuild the C ABI, then cargo clean -p doppio-engine and rebuild |
| Headless renderer cannot start | Set ICED_TEST_BACKEND=tiny-skia |