imgui-rs/docs/upgrading_imgui.md

Updating to new imgui versions

1. Ensure the submodules are populated (git submodule init --recursive and git submodule update --recursive)

2. Change into imgui-sys/third-party/cimgui/ and check the current version, e.g

   $ git status HEAD detached at 1.81 nothing to commit, working tree clean

3. Update upstream cimgui

   $ git remote update Fetching origin

4. Switch to a new branch, e.g

   $ git checkout 1.82 HEAD is now at ...

5. Check the nested imgui-sys/third-party/cimgui/imgui/ submodule pointing at the correct version:

   $ pwd .../imgui-rs/imgui-sys/third-party/cimgui $ git status HEAD detached at 1.81 nothing to commit, working tree clean $ git log ... $ cd imgui/ $ git status HEAD detached at v1.81 nothing to commit, working tree clean $ git log ...

If these versions differ, run git checkout v1.82 in the imgui folder (noting cimgui uses a different tag naming convention to imgui!)

6. Back in the root of the imgui-rs repo, run cargo xtask bindgen

   $ cargo xtask bindgen Finished dev [unoptimized + debuginfo] target(s) in 0.04s Running target/debug/xtask bindgen Executing bindgen [output = .../imgui-rs/imgui-sys/src/bindings.rs] Success [output = .../imgui-rs/imgui-sys/src/bindings.rs] Executing bindgen [output = .../imgui-rs/imgui-sys/src/wasm_bindings.rs] Success [output = .../imgui-rs/imgui-sys/src/wasm_bindings.rs]

This requires bindgen to be installed (cargo install bindgen should do it)

This step generates imgui-sys/src/bindings.rs which is used by imgui/src/*

7. Run cargo build and fix any errors from upstream.

8. Run the tests with cargo test.

9. Try running one of the examples

   cargo run --example test_window_impl

Building a specific revision

cimgui has pre-generated bindings to specific versions of imgui - usually for each regular imgui release, and the WIP docking branch at the same time as the release.

However this will not work if you need to either

1. Build imgui-rs against a specific revision, or
2. Build imgui-rs against another branch or fork

Luckily running the generator is quite straight forward:

1. Ensure luajit is installed (required by cimgui's generator)
2. In the cimgui submodule, check out the master branch
3. Update the nested imgui submodule (imgui-sys/third-party/cimgui/imgui/) to point to your desired upstream imgui
4. Run the generator as per https://github.com/cimgui/cimgui#using-generator
5. Run cargo xtask bindgen and follow the rest of the steps as usual

Note actually committing this change may be more complicated as you will need to either replace the submodule with a copy of the source, or update the cimgui submodule to point at your fork of imgui

Common sources of problems

Function changes

Check the upstream imgui release notes for the new versions, as they detail any breaking changes.

If functions have been renamed, the required changes to the bindings are usually simple.

If functions have been removed, the changes are usually also simple but the implications may require some thought.

If new function overloads are added - for example imgui::Thing() existed but imgui::Thing(float) was added - bindings.rs will previously have contained only igThing, but will now contain igThingNil() and igThingFloat(...)

Memory layout changes

It is common for upstream to add/remove/reorder fields, so the bindings will compile but the memory layout will not match - which will (hopefully) result in the bindings causing a segfault. These are not tagged as breaking changes in the release notes.

The *_memory_layout tests when running cargo test should catch these (if they are created for every relevant struct!)

The fix for this is usually to compare the struct in (read-only) imgui-sys/src/bindings.rs compared to the relevant struct in imgui/src/... - the ordering and data-types must match, but the names do not (structs in imgui/src/... should use conventional Rust naming/casing)