Cheryl is a C++23 engine with one neutral engine library and optional platform, graphics, UI and audio modules. It provides sequential or concurrent simulation, retained 2D rendering, input actions/events/text, Unicode layout and CPU asset preparation separate from graphics upload. Game state and mechanics belong to the application.
Read the documentation for the API reference, setup guides and first-game walkthrough.
The default assembly includes Startup, Workers with hwloc/JSON, Native GLFW,
OpenGL, TGUI, RmlUi and miniaudio. The demo and tests are opt-in.
Single-configuration Linux GNU/Clang Debug builds also select the optional
output-terminal module by default. Other configurations default it to OFF.
- Online documentation
- Setup
- Targets
- Tests
- CI and development SDKs
- Repository architecture
- Documentation and development
You need Git, CMake 3.28 or newer, Ninja, and a C++23 compiler and standard library
with std::format support. The default root configuration also requires Python
3.11 or newer for documentation targets and hwloc 2.5+ (2.x) for worker support.
Set CHERYL_BUILD_DOCS=OFF or CHERYL_BUILD_WORKER_TOPOLOGY_HWLOC=OFF to omit
the corresponding requirement. Install the selected modules'
system dependencies.
Linux builds use ordinary shared development packages. Windows requires Windows
10 version 1903+ and the SDK's ICU C API; prepare its external shared dependencies
using the dependency helper.
git clone https://github.com/cppcooper/cheryl-engine.git
cd cheryl-engine
git submodule update --init --recursiveConfigure and build the demo from anywhere inside the checkout:
(
set -e
cd "$(git rev-parse --show-toplevel)"
cmake -S . -B build/release -G Ninja -DCMAKE_BUILD_TYPE=Release \
-DCHERYL_BUILD_DEMO=ON
cmake --build build/release --target demo --parallel
./build/release/demo
)The command uses Linux system packages. Windows uses the prepared
x64-windows prefix and DLL CRT configuration from the build guide. FreeType,
HarfBuzz, GLFW, the UI toolkits and optional hwloc/HIDAPI are shared dependencies.
Windows uses built-in ICU; Linux uses its distribution's ICU. miniaudio, spdlog,
Gainput and GLAD remain embedded in their Cheryl owners.
The demo starts with checked-in shaders and an embedded font. Optional package
images add tile/sprite samples; missing images do not prevent startup. WASD pans,
R resets the camera, F2 selects text focus, Escape releases it and Q quits.
Use --concurrent for a simulation worker. The
demo guide covers all controls, artwork and runtime
options.
After changing branches or updating the checkout, restore its pinned dependencies:
(
set -e
cd "$(git rev-parse --show-toplevel)"
git submodule sync --recursive
git submodule update --init --recursive
)The build guide lists configuration options, dependency settings, Debug/Release behavior and common setup failures. Existing build directories retain cached options; reload CMake after changing selections.
Build concrete target names with cmake --build ... --target; applications link
the public aliases to inherit headers and dependencies.
| Build target | Public alias | Purpose |
|---|---|---|
cengine |
Cheryl::Engine |
Neutral engine contracts and implementation. |
module_startup |
Cheryl::Startup |
Generic application bootstrap, validated command-line configuration and selected backend integration. |
module_workers |
Cheryl::Workers |
Independently selectable hwloc discovery/binding and JSON worker settings; capability-specific legacy aliases refer to this binary. |
module_native_glfw |
Cheryl::NativeGLFW |
Display, windows and optional input. |
module_debug_terminal_linux |
Cheryl::DebugTerminal::Linux |
Optional Linux process output capture/viewer; an interface selects the implementation by configuration. |
cengine_debug_terminal_startup |
Cheryl::DebugTerminal::Startup |
Private static argument/startup attachment accepting a module implementation callback. |
module_opengl |
Cheryl::OpenGL |
Rendering, context, presentation and resources; requires Native GLFW. |
module_opengl_startup (interface) |
Cheryl::OpenGL::Startup |
Compatibility interface linking Startup and OpenGL; produces no additional binary. |
module_ui_tgui |
Cheryl::UI::TGUI |
TGUI widgets and retained scene bridge. |
module_ui_rmlui |
Cheryl::UI::RmlUi |
RML/RCSS documents and retained scene bridge. |
module_audio_miniaudio |
Cheryl::Audio::Miniaudio |
Audio decoding, mixing, native output and streaming. |
demo |
— | Example native application. |
first-game |
— | Opt-in maintained game from the walkthrough, with its own assets. |
tutorial-game |
— | Opt-in Controller/Character, joining players, patrol and TGUI HUD example supporting the tutorials and task index. |
docs, docs-clean, docs-tools |
— | Optional incremental generation, full regeneration and shared documentation tool setup; also available through the docs-only CMake project. |
cheryl-sdk |
— | Builds selected installable libraries when CHERYL_BUILD_SDK=ON. |
See the module index for each owner's API and the
consumption guide for application CMake
composition. Applications can also use an installed prebuilt SDK through
find_package(Cheryl 4 CONFIG REQUIRED).
With tests enabled, build and run the combined GoogleTest runner for selected owners:
(
set -e
cd "$(git rev-parse --show-toplevel)"
cmake -S . -B build/release -G Ninja -DCMAKE_BUILD_TYPE=Release \
-DCHERYL_BUILD_TESTS=ON
cmake --build build/release --target all-tests --parallel
./build/release/tests-all
)The test guide explains focused runners, aggregates, CTest selection, consumers and environment opt-ins. Native graphics and real-font checks need their stated prerequisites; skipped cases leave that coverage pending. The testing queue contains pending automated checks and QA.
GitHub CI selects Linux GCC/Clang and Windows MSVC builds, focused tests and installed SDK consumers. Successful main-push validation collects prebuilt development SDKs as workflow artifacts. They contain compiled libraries, public/inline/template headers, CMake integration and licenses. SDKs use the ordinary build's dependency policy: embedded libraries stay inside their shared Cheryl owners, shared native runtimes are packaged or declared as platform requirements, and static Cheryl SDKs also retain their embedded archive closure for final linking. The demo and C/C++ implementation files are excluded. GitHub release publication is separate, and exact hosted Linux/Windows acceptance remains pending the first run.
projects/engine/ owns neutral contracts and implementation. Optional integrations
live under projects/modules/; Engine has no dependency on them. Applications
assemble the required owners. projects/apps/demo/ demonstrates that assembly,
while projects/tests/ owns cross-module checks.
Each owner declares its own sources, public includes, dependencies and tests. The
root CMake file selects owners; cmake/ supplies shared metadata and composition
helpers. extern/ holds pinned dependencies and the assets/ submodule holds
definitions, textures, shader recipes, UI documents and font inputs. Initialize it
alongside the dependencies; optional package images still follow the
catalog. See module authoring
for the steps required to add an owner.
From the checkout root, run ./generate-docs.sh to update the local manual and API
reference. Add --clean for full regeneration, --extract-only for Doxygen XML,
or --help for output and tool-selection options. The
generation guide also covers Python and CMake
entry points and hosted publication.
The generated entry point is docs/site/generation/generated/html/index.html.