Update existing bindings - Dear ImGui Bundle

Quick reference: justfile commands¶

The justfile provides shortcuts for the most common library management tasks:

just libs_info              # Show all libraries with their remotes (fork / official)
just libs_check_upstream    # Check which forks have new upstream changes
just libs_log <name>        # Show new upstream commits for a library
just libs_rebase <name>     # Tag current state, then rebase fork on upstream
just libs_tag <name>        # Push a date tag to a fork
just libs_check_pushed      # Before pushing the bundle: are all its submodule commits on a server?
just bundle_push            # Push the bundle, once libs_check_pushed passes
just libs_bindings <name>   # Regenerate bindings for one library
just libs_bindings_all      # Regenerate all bindings
just libs_reattach          # Reattach all submodules to their branches
just libs_fetch             # Fetch all remotes
just libs_pull              # Pull all submodules

See Managing external libraries and forks for detailed explanations of each command.

Typical workflow¶

1. Check what’s new upstream¶

just libs_check_upstream

Example output:

Unchanged libraries: imgui, glfw, hello_imgui, ImCoolBar, ...
Libraries with new changes in official repo: imgui_test_engine

Inspect the new commits:

just libs_log imgui_test_engine

2. Update the library¶

For a non-forked library (e.g. immvision, glfw):

cd external/immvision/immvision
git pull
cd -

For a forked library (e.g. imgui_test_engine): tag the current state, then rebase on upstream:

just libs_rebase imgui_test_engine

This is equivalent to:

cd external/imgui_test_engine/imgui_test_engine
git tag "bundle_$(date +%Y%m%d)"
git push fork --tags
git rebase official/main
cd -

3. Regenerate bindings¶

just libs_bindings imgui_test_engine

Or call the generation script directly:

python external/imgui_test_engine/bindings/generate_imgui_test_engine.py

Examine the changes in the generated .cpp and .pyi files with git diff.

4. Compile & test¶

If you don’t have a build directory yet, see Getting Started or Build Guide.

Build:

cd builds/my_build
cmake --build . -j

Fix any compilation errors due to breaking changes in the upstream API. After an update of Dear ImGui, other libraries may break as well (many of them guard their code with IMGUI_VERSION_NUM). Use a keep-going build to see all the errors in one pass, instead of one library at a time:

cmake --build . -j -- -k      # Makefiles (with Ninja: -- -k 0)

Test in C++:

./demo_imgui_bundle    # Global demo exercising most libraries

Test in Python:

python bindings/imgui_bundle/demos_python/demos_immapp/demo_hello_world.py

Run the test suite:

just test_pytest   # or: pytest
just mypy          # or: mypy (from the repo root)

See Testing for more details.

After an update of imgui, implot or implot3d: their demos may have changed, and the API pages show pictures of them. Rebuild the web explorer (just imex_ems_build), then retake the pictures of the changed sections: just api_pictures --stale (see the docstring of ci_scripts/api_pictures.py).

5. Push fork changes (if applicable)¶

If the fork submodule was modified during rebase or to fix binding compatibility:

cd external/imgui_test_engine/imgui_test_engine
git push --force-with-lease fork imgui_bundle   # a rebase rewrites the history: a plain "git push" would be rejected
cd -

6. Commit¶

git add -A
git commit -m "Update imgui_test_engine and regenerate bindings"

Example: update imgui & bindings (detailed)¶

imgui and imgui_test_engine use forks. Update them together: the test engine uses imgui internals behind IMGUI_VERSION_NUM guards. The full update process:

1. Tag current fork state

just libs_tag imgui
just libs_tag imgui_test_engine

2. Rebase forks on upstream

just libs_rebase imgui
just libs_rebase imgui_test_engine

Or manually:

cd external/imgui/imgui
git rebase official/docking
cd -

cd external/imgui_test_engine/imgui_test_engine
git rebase official/main
cd -

3. Regenerate bindings

just libs_bindings_all

Regenerate all the libraries, not only imgui: the litgen options of imgui are shared with implot, implot3d and imgui_toggle. For imgui itself, this runs external/imgui/bindings/generate_imgui.py, which generates bindings for imgui, imgui_internal, and imgui_test_engine.

A clean rebase says nothing about litgen: a new decoration macro upstream (e.g. IM_NODEBUGSTEP) can be read as part of a return type. Symptoms: “Failed to run black formatter” in the log, and a stub that does not parse. So regenerate imgui alone first (just libs_bindings imgui), and check that its stubs parse before regenerating all the libraries. The fix is to strip the macro in _preprocess_imgui_code() (external/imgui/bindings/litgen_options_imgui.py).

4. Examine, build, and test (see steps 3-4 above)

4b. Check imgui-node-editor (it relies on two commits of the imgui fork: see the imgui-node-editor fork)

Run its automated tests: they tell whether popups, combos and multiline text still work inside a node with the new Dear ImGui.

cmake -S .github/ci_automation_tests -B builds/ci_automation_tests -DCMAKE_BUILD_TYPE=Release
cmake --build builds/ci_automation_tests --target ci_node_editor_tests -j
./builds/ci_automation_tests/ci_node_editor_tests --auto     # (macOS: inside ci_node_editor_tests.app/Contents/MacOS/)

Then, in the node editor fork (external/imgui-node-editor/imgui-node-editor):

refresh the patch files of misc/imgui_patches/ from the two rebased imgui commits (“ImGuiContext::BeginWindowCallback...” and “ImGuiContext::InputTextMultilineOverride”). The command is in its docs/fork_imgui_bundle.md, chapter 3. Check them with git apply --check against the new upstream tags (docking and master); rebuild the master variant of the first patch by hand if its check fails.
in its .github/workflows/tests.yml, bump the two tags of Dear ImGui (docking and master) used by the “stock Dear ImGui” job. (imgui_bundle is not pinned there: that workflow uses its main branch.)
in its examples/cmake/Findimgui.cmake, set GIT_TAG to the new commit of the imgui fork (tagged bundle_YYYYMMDD, so that it survives the next rebase), and build the examples once: cmake -S examples -B <build dir> && cmake --build <build dir>.

4c. Check hello_imgui’s Vulkan backend (on macOS, with the Vulkan SDK)

MoltenVK checks things that Windows drivers often let pass (e.g. the contents of the descriptor pool), so run the Vulkan demo on the Mac:

cmake -S external/hello_imgui/hello_imgui -B builds/himgui_vulkan -G Ninja -DHELLOIMGUI_HAS_VULKAN=ON -DHELLOIMGUI_USE_GLFW3=ON \
    -DHELLOIMGUI_DOWNLOAD_FREETYPE_IF_NEEDED=ON -DHELLOIMGUI_VULKAN_VALIDATION=ON
cmake --build builds/himgui_vulkan --target hello_imgui_demodocking
VK_LAYER_PATH=$VULKAN_SDK/share/vulkan/explicit_layer.d DYLD_LIBRARY_PATH=$VULKAN_SDK/lib \
    builds/himgui_vulkan/bin/hello_imgui_demodocking.app/Contents/MacOS/hello_imgui_demodocking

A clean run prints no “[vulkan] Debug report” message. hello_imgui’s Vulkan backend (src/hello_imgui/internal/backend_impls/rendering_vulkan*.cpp) follows imgui’s examples/example_glfw_vulkan/main.cpp: diff it against the new example.

5. Push updated forks

cd external/imgui/imgui && git push --force-with-lease fork imgui_bundle && cd -
cd external/imgui_test_engine/imgui_test_engine && git push --force-with-lease fork imgui_bundle && cd -