This section is for developers willing to build and modify the imgui_bundle library. It covers topics such as building the library, updating dependencies, and adding new features or bindings.
Architecture Overview¶
ImGui Bundle implements a four-layer architecture:
Rendering Backends – GLFW/SDL + OpenGL/Metal/DirectX/Vulkan
Dear ImGui Core – immediate-mode widget system
Hello ImGui Framework – window lifecycle, docking, DPI handling, asset management
ImmApp Layer – simplified runner with automatic add-on initialization
Users can work at their preferred abstraction level, from raw ImGui calls to the high-level immapp.run() API.
Python Bindings¶
The bindings are auto-generated using litgen, a code generator that transforms C++ headers into:
nanobind C++ code – the actual binding implementation
.pyitype stubs – for IDE autocompletion and type checking
All 23+ C++ libraries compile into a single _imgui_bundle native extension, with submodules conditionally available based on build configuration.
Key Concepts¶
Add-On System: ImmApp manages automatic context creation for optional libraries via
AddOnsParamsflags (with_implot,with_markdown, etc.)Cross-Platform: Same codebase deploys to desktop (Windows/macOS/Linux), mobile (iOS/Android), and web (Emscripten/Pyodide)
DPI-Aware Sizing: Helper functions like
EmToVec2()enable responsive layouts across high-DPI displays
Glossary¶
Terms used throughout the developer docs:
| Term | Meaning |
|---|---|
| Dear ImGui | The core C++ immediate-mode GUI library by Omar Cornut |
| Hello ImGui | Framework layer on top of Dear ImGui: window lifecycle, docking, DPI, asset management, multi-platform deployment |
| ImmApp | High-level runner that wraps Hello ImGui and auto-initializes add-ons (ImPlot, Markdown, etc.) via simple flags |
| litgen | Literate Generator — the tool that reads C++ headers and generates Python bindings (nanobind C++ code + .pyi stubs) |
| nanobind | C++ library used to create Python extension modules. Successor to pybind11; used by litgen’s generated code |
| srcML | XML representation of C++ source code; used internally by litgen to parse headers |
.pyi stubs | Python type stub files providing IDE autocompletion and type checking for the native extension |
| pybind | Legacy naming seen in generated filenames (pybind_*.cpp). These files actually use nanobind, not pybind11 — the name is historical |
| ibex | Abbreviation fo Dear ImGui Bundle Explorer — the full demo app showcasing all libraries, used in just recipes (just ibex_...) |
| imex | Abbreviation for Dear ImGui Explorer - source code in external/imgui_explorer. Used just recipes just imex_... |
_imgui_bundle | The single compiled native extension (.so/.pyd) containing all 23+ C++ libraries |
| justfile | Task runner config at repo root; provides shortcuts like just libs_bindings, just test_pytest, etc. |
More Resources¶
DeepWiki - ImGui Bundle – AI-powered documentation explorer for in-depth architecture questions
Litgen Documentation – the bindings generator used by this project
In This Section¶
Getting Started (Developer) – clone, build, run, test
Repository Structure – folder organization
Build Guide – CMake options, presets, justfile commands
Testing – running tests, CI workflows
Bindings Introduction – how the generator works
Update Bindings – updating existing library bindings
Add New Library – adding a new library to the bundle
Debug Native C++ – debugging C++ code from Python
PyPI Deployment – releasing to PyPI
Pyodide Build Guide – building for Python-in-the-browser
OpenCV Build Guide – building with OpenCV / ImmVision