A ready-to-develop desktop application built on the three ETIB libraries:
| Library | Role in the application |
|---|---|
| evan | Opens the window and renders with Vulkan (GLFW backend). |
| guillaume | UI framework: scenes, widgets, layout, events, theme, storage. |
| maïs | Runs the application's Python scripts (embedded through pybind11). |
Clone it, build it, and you get a window with a few widgets and a Python script driving one of them. Then replace the scene and the script with your own.
- CMake 3.28 or newer and a C++20 compiler
- Git and network access (the first configure downloads the libraries)
- The Vulkan SDK (LunarG)
- Python 3.9 to 3.14 with its development files (
python3-devon Debian and Ubuntu; included in the python.org, Homebrew and Xcode installations) - On Linux, the window-system packages:
bash tools/install_ubuntu_dependencies.sh
cmake --preset default
cmake --build --preset default --parallel
cmake --build --preset default --target runThe first configure fetches evan, guillaume, maïs and their dependencies, and the first build compiles them: allow a few minutes. Later builds only compile what you change.
The executable is build/bin/getting_started. It can be started from any
directory.
Run the tests with:
ctest --preset defaultCMakeLists.txt the application target; rename the app here
CMakePresets.json default (debug), release, siblings (local libraries)
cmake/
Dependencies.cmake the pinned revisions of the libraries
Runtime.cmake what is copied next to the executable
src/
main.cpp the host: start-up order and frame loop
AppContext.hpp state shared by the frame loop and the scenes
scenes/HomeScene.cpp the start-up scene: build your UI here
scripting/Scripting.* what Python can see of the application
scripts/app.py the Python hooks
assets/ your models, images and textures
tests/ tests that run without a window
tools/ formatting and Linux set-up scripts
.github/workflows/ build and formatting checks
src/main.cpp owns the order. The libraries do not know about each other.
- maïs starts Python and loads
scripts/app.py. configure(settings): the script proposes the window title and size.- The host validates the proposal. An invalid one is reported and replaced by the defaults.
- evan creates the window and the engine; guillaume enters
HomeScene. on_start(context).- Every frame:
on_update(context), then one guillaume frame (events, layout, render, present). on_shutdown(context), then Python stops.
In the sample, the button increments context.clicks, the script reads it in
on_update and writes context.status, and the host shows that text in the
window. This is the full round trip: widget, host, Python, host, widget.
A failing on_update is printed once with its Python traceback and the window
stays open.
Edit HomeScene::onEnter() in src/scenes/HomeScene.cpp. Each widget has a
builder under guillaume/entities/. The
widget gallery
shows every widget with the code that creates it.
- Copy
src/scenes/HomeScene.*to a new class and add the.cpptoadd_executable()inCMakeLists.txt. - List the class in
guillaume::Application<HomeScene, MyScene>insrc/main.cpp. The first one is shown at start-up. - Switch from a click handler with
goToScene<MyScene>().
- Add a field to
FrameContext(or a new structure) insrc/scripting/Scripting.hpp. - Bind it in
registerBindings()insrc/scripting/Scripting.cpp:def_readonlyfor values the script reads,def_readwritefor values it writes,host.def(...)for a command. - Fill it before the hook, or act on it after the hook, in
src/main.cpp. - Add a check in
tests/ScriptingTest.cpp.
Scripts receive plain values, never the engine or a widget. A command sets a flag that the host reads; it does not act by itself. See maïs's host integration guide for the reasons.
Put the file under assets/ and load it by its path relative to that
directory, for example models/chair.obj. See assets/README.md.
Edit scripts/app.py, then run the run target again: scripts are copied on
every build, and nothing is recompiled.
Change the revision in cmake/Dependencies.cmake, then configure and build
again. The engine's shaders and the fonts come from the same pinned sources,
so they follow the revision.
With evan, guillaume and maïs checked out next to this repository:
cmake --preset siblings
cmake --build --preset siblings --parallel
cmake --build --preset siblings --target runThe application then builds against the local checkouts instead of the pinned
revisions. For a single library, pass
-DFETCHCONTENT_SOURCE_DIR_GUILLAUME=/path/to/guillaume (or _EVAN, _MAIS,
_UTILITY) to the default preset.
Change APP_NAME at the top of CMakeLists.txt. The executable and the
targets follow. The window title is set in scripts/app.py.
| Test | What it checks |
|---|---|
scripting.app_script |
scripts/app.py loads, proposes valid settings and survives a few frames. |
scripting.bindings |
Each binding of the host module, with tests/scripts/fixture.py. |
app.smoke |
The window opens, 120 frames are drawn, the application exits. |
app.smoke needs a display and a Vulkan driver, so it is off by default:
cmake --preset default -DAPP_ENABLE_GPU_TESTS=ONThe same frame limit is available by hand:
GETTING_STARTED_MAX_FRAMES=120 ./build/bin/getting_started.
C++ is formatted with clang-format 21.1.8 (LLVM-based, 80 columns, tabs). The version is pinned because the output changes between releases:
pip install 'clang-format==21.1.8'
./tools/run-clang-format.shTo format staged files on every commit:
git config core.hooksPath .githooks-DAPP_DEV_MODE=ON compiles the application's own code with -Wall -Wextra -Wpedantic -Werror. CI builds with it.
Could NOT find Vulkan: install the Vulkan SDK and, on macOS and Windows, run its environment script (or setVULKAN_SDK) before configuring.Could NOT find Pythonor a missingPython.h: install the Python development files, or select an interpreter with-DPython_EXECUTABLE="$(command -v python3)".- Vulkan validation messages in the terminal: a debug build enables the validation layers when they are installed. The image-layout errors and the "vertex attribute not consumed" warnings come from the libraries; the guillaume widget gallery prints the same ones.
- Very verbose output: debug builds of the libraries log every frame.
Use the
releasepreset, or redirect the output, when that gets in the way.
Released under the MIT License. The fonts copied next to the executable (Roboto, Material Symbols) keep their own licenses, which are copied with them.