Caffeine

Build guide

Stable Engine Last verified:

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#

bash
./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:

bat
scripts\build.bat
scripts\build.bat release
scripts\build.bat test

Fish shell:

fish
./scripts/build.fish release

The wrappers are convenience only; every step is a normal CMake command.

What the wrapper runs#

StepCommand
Dependency checkcmake and python3 on PATH
Configurecmake -DCMAKE_BUILD_TYPE=<type> .. from build/
Buildcmake --build . --parallel <cores>
Testctest --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:

bash
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:

bash
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:

bash
./scripts/submodules.sh
./scripts/build.sh release
ls build/plugins

To skip plugins in a minimal or headless environment:

bash
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#

bash
cd build && ctest --output-on-failure
cd doppio && cargo test -p doppio-ui
./scripts/check-rust-ui.sh

check-rust-ui.sh runs:

  1. cargo fmt --check
  2. cargo test for the workspace
  3. cargo check --features agent
  4. cargo clippy -- -D warnings
  5. the caffeine-core / ImGui coupling audit
  6. the headless flow suite

Headless UI checks:

bash
./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/:

bash
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#

SymptomFix
doppio-plugins submodule is missing./scripts/submodules.sh or -DCAFFEINE_BUILD_DOPPIO_PLUGINS=OFF
SDL3 not foundInstall SDL3 or configure with -DCAFFEINE_BUILD_HEADLESS=ON for core-only work
Doppio cannot load libcaffeine-capiBuild the caffeine-capi target and set CAFFEINE_ENGINE_ROOT if the trees are separate
Rust build fails after a C ABI changeRebuild the C ABI, then cargo clean -p doppio-engine and rebuild
Headless renderer cannot startSet ICED_TEST_BACKEND=tiny-skia