Getting Started (Developer)

This guide gets you from a fresh clone to a working build with demos and tests. It targets contributors and developers who want to build imgui_bundle from source.

Prerequisites¶

Linux only: install libglfw3-dev (or pass -DHELLOIMGUI_DOWNLOAD_GLFW_IF_NEEDED=ON).

Clone & init submodules¶

git clone --recursive https://github.com/pthom/imgui_bundle.git
cd imgui_bundle

If you already cloned without --recursive:

git submodule update --init --recursive

Submodules are auto-cloned during CMake configure by default (via IMGUI_BUNDLE_AUTO_CLONE_SUBMODULES=ON), so this step is often optional.

Quick build: C++ only (desktop)¶

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

This builds with GLFW + OpenGL3 (the default). Run the demos:

./demo_imgui_bundle          # Main demo showcasing all libraries

Quick build: Python bindings¶

The recommended dev setup is an editable install, then rebuild with CMake to iterate on the C++ code without re-running pip.

# Create a venv
python -m venv venv && source venv/bin/activate
pip install -r requirements-dev.txt   # numpy, pytest, mypy, etc.

# 1. Editable install (uses scikit-build-core under the hood; slow the first time)
pip install -v -e .

After this, import imgui_bundle works from anywhere, and pytest / the demos run directly, with no PYTHONPATH to set:

python bindings/imgui_bundle/demos_python/demo_imgui_bundle.py
pytest

To iterate on the C++ (or after regenerating bindings), rebuild with the CMake preset. The build redeploys the freshly-built native module into the editable install, so the next python run picks it up:

mkdir -p builds/my_python && cd builds/my_python
cmake ../.. --preset python_bindings -DPython_EXECUTABLE=$(which python)
cmake --build . -j                              # or: --target _imgui_bundle, to rebuild only the bindings

Build with ImmVision (OpenCV)¶

ImmVision works without OpenCV (using ImageBuffer / numpy arrays). To also enable cv::Mat interop:

cmake ../.. --preset python_bindings \
    -DPython_EXECUTABLE=$(which python) \
    -DIMMVISION_FETCH_OPENCV=ON

This fetches and builds a minimal OpenCV in the build directory. See OpenCV builds for immvision for platform-specific details.

Run the tests¶

# From the repo root
just test_pytest    # Run pytest
just test_mypy      # Run mypy type checking on bindings

Or without just:

pytest
cd bindings && ./mypy_bindings.sh

See Testing for details on GUI tests and CI.

Build the docs¶

just doc_serve                # Live-reload dev server (recommended for editing)
# or, for the full Cloudflare-deploy build (HTML anchored under /doc/, plus PDF):
just doc_build_cf
# Then preview under the right /doc/ prefix:
just cf_stage && just cf_serve_local   # http://localhost:8765/doc/

Useful justfile commands¶

Run just (no arguments) to see all available commands. Key groups:

See Build Guide for the full command reference.

What next?¶