Build Guide

This page documents CMake options, presets, the justfile task runner, and common build scenarios.

CMake presets¶

The repo ships a CMakePresets.json with these presets:

Usage:

mkdir -p builds/my_build && cd builds/my_build
cmake ../.. --preset python_bindings -DPython_EXECUTABLE=$(which python)
cmake --build . -j

Module selection (IMGUI_BUNDLE_WITH_*)¶

Each library can be individually enabled or disabled. All default to ON.

Dependency chain: CMake automatically disables dependent modules. For example, setting IMGUI_BUNDLE_WITH_HELLO_IMGUI=OFF also disables immapp, imgui_md, test_engine, and the GLFW backend.

Convention: CMake option names and C++ #define names are identical. For example, IMGUI_BUNDLE_WITH_IMANIM is both the option() and the #ifdef guard in C++.

Legacy options: IMGUI_BUNDLE_DISABLE_* options are deprecated (removal ~January 2028). Use IMGUI_BUNDLE_WITH_*=OFF instead.

Backend selection¶

You need at least one platform backend and one rendering backend:

Platform backends:

Rendering backends:

If you make no choice, the default is GLFW3 + OpenGL3.

Other build options¶

For pip builds, pass CMake options via the CMAKE_ARGS environment variable:

CMAKE_ARGS="-DIMGUI_BUNDLE_WITH_IMMVISION=OFF" pip install -v -e .

Common build scenarios¶

Desktop C++ (minimal)¶

mkdir -p builds/desktop && cd builds/desktop
cmake ../.. --preset default
cmake --build . -j

Python bindings with ImmVision¶

mkdir -p builds/python && cd builds/python
cmake ../.. --preset python_bindings \
    -DPython_EXECUTABLE=$(which python) \
    -DIMMVISION_FETCH_OPENCV=ON
cmake --build . -j

Emscripten (ImGui Bundle Explorer)¶

just ibex_build       # builds into build_ibex_ems/
just ibex_serve       # serve on port 8642

Or manually:

mkdir -p builds/ems && cd builds/ems
source ~/emsdk/emsdk_env.sh
emcmake cmake ../.. -DCMAKE_BUILD_TYPE=Release
make -j

Emscripten (ImGui Explorer, lightweight)¶

just imex_ems_build   # builds into build_imex_ems/
just imex_ems_serve   # serve on port 7006, add ?lib=imgui etc. to URL

Pyodide (Python in the browser)¶

just pyodide_setup_local_build    # one-time setup
just pyodide_build                # build wheel
just pyodide_test_serve           # serve test page

See also ci_scripts/pyodide_local_build/Readme.md.

Offline build (vcpkg)¶

git clone https://github.com/microsoft/vcpkg && ./vcpkg/bootstrap-vcpkg.sh
./vcpkg/vcpkg install opencv freetype glfw3 lunasvg
export CMAKE_TOOLCHAIN_FILE=vcpkg/scripts/buildsystems/vcpkg.cmake
mkdir build && cd build && cmake ..

justfile reference¶

The justfile at the repo root provides shortcuts for common tasks. Run just to list all commands.

Library management (just libs_*)¶

Build & deploy¶

Documentation¶

Testing¶

Pyodide¶

CI / Docker¶