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¶

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

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

Then set your PYTHONPATH to include the build output, and run:

cd ../..
python bindings/imgui_bundle/demos_python/demo_imgui_bundle.py

Alternative: editable pip install¶

For a development workflow where changes are picked up without rebuilding manually:

pip install -v -e .

This uses scikit-build-core under the hood and takes longer the first time.

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_interactive    # Live-reload dev server
# or
just doc_build_static         # Static HTML build
just doc_serve_static         # Serve the static build on port 7005

Useful justfile commands¶

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

See Build Guide for the full command reference.

What next?¶