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 the C++ ImmVision demos with OpenCV¶

ImmVision works without OpenCV (using ImageBuffer / numpy arrays), and never links it: the Python bindings do not use OpenCV at all. cv::Mat interop is a choice of each C++ application, which defines IMMVISION_HAS_OPENCV and links OpenCV by itself.

Some C++ demos do this, in order to show more image processing (Sobel, blur, etc.):

cmake ../.. -DIMGUI_BUNDLE_DEMOS_WITH_OPENCV=ON

OpenCV must then be findable (installed, or via -DOpenCV_DIR=...). As a convenience, -DIMMVISION_FETCH_OPENCV=ON 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 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:8764/doc/

Pitfalls of the book (MyST, exported to PDF with Typst):

• The PDF is one Typst document made of every page: a heading used on two pages makes a duplicate label, and the PDF build fails (label <...> occurs multiple times). Rename one of the headings.

• The PDF drops grids ({grid} directives). A page with grids needs a plain copy for the PDF: see intro/demos.md and intro/demos_pdf.md, written by just playground_examples_docs, and _toc_pdf.yml.

• Nested directives need longer outer fences: a card (::::) inside a grid (:::::), with an image (:::) inside the card.

• mystmd takes the page’s title from its first H1 only when it comes first: put a comment after it, not before.

• jupyter-book build --pdf exits 0 even when Typst fails: just doc_build_cf checks that the PDF was really written.

• The site’s theme (mystmd’s book theme) is downloaded once into _build/templates, and the builds keep it. To upgrade it: jupyter-book clean --templates in docs/book, then a build. Then check the pages that _static/custom.css restyles (the top bar, the API pages, the demos’ cards), at phone and desktop widths, in the dark and light themes.

Useful justfile commands¶

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

See Build Guide for the full command reference.

What next?¶