Automated bindings: introduction

The bindings are generated automatically thanks to a sophisticated generator, which is based on srcML.

The generator is provided by litgen (Literate Generator), an automatic Python bindings generator developed by the same author as Dear ImGui Bundle. See also the litgen PDF manual for in-depth documentation.

Installing the generator¶

See the installation instructions (do a local installation).

Quick information about the generator¶

litgen (aka “Literate Generator”) is the package that will generate the python bindings.

Its source code is available here.

It is heavily configurable by a wide range of options.

See for examples the specific options for imgui bindings generation.

Folders structure¶

In order to work on bindings, it is essential to understand the folders structure inside Dear ImGui Bundle. Please study the dedicated doc.

Study of a bound library generation¶

Let’s take the example of the library ImCoolBar.

Here is how the generation works for the library. The library principal files are located in external/ImCoolBar:

external/ImCoolBar/                        # Root folder for ImCoolBar
├── ImCoolBar/                             # ImCoolBar submodule
│         ├── CMakeLists.txt               # ImCoolBar code
│         ├── ImCoolbar.cpp
│         ├── ImCoolbar.h
│         ├── LICENSE
│         └── README.md
└── bindings/                               # Scripts for the bindings generations & bindings
    ├── generate_imcoolbar.py               # This script reads ImCoolbar.h and generates:
    |                                       #     - binding C++ code in ./pybind_imcoolbar.cpp
    |                                       #     - stubs in
    |                                       #          bindings/imgui_bundle/im_cool_bar_pyi
    ├── im_cool_bar.pyi -> ../../../bindings/imgui_bundle/im_cool_bar.pyi   # this is a symlink!
    └── pybind_imcoolbar.cpp

The actual stubs are located here:

imgui_bundle/bindings/imgui_bundle/
├── im_cool_bar.pyi              # Location of the stubs
├── __init__.pyi                 # Main imgui_bundle stub file, which loads im_cool_bar.pyi
├── __init__.py                  # Main imgui_bundle python module which loads
|                                # the actual im_cool_bar module
├── ...

And the library is referenced in a global generation script:

imgui_bundle/external/bindings_generation/
├── autogenerate_all.py          # This script will call generate_imcoolbar.py (among many others)
├── all_external_libraries.py    # ImCoolBar is referenced here
├── ...

Regenerating bindings via justfile¶

The justfile provides convenient shortcuts for binding generation and library management:

just libs_bindings im_cool_bar    # Regenerate bindings for one library
just libs_bindings_all            # Regenerate all bindings
just libs_info                    # Show all libraries with their remotes
just libs_check_upstream          # Check which forks have new upstream changes

See Update Bindings for the full update workflow, and Managing external libraries and forks for how forks, remotes, and bundle-specific changes are managed.