mirror of
https://github.com/eliasstepanik/imgui-rs.git
synced 2026-01-12 05:58:35 +00:00
90 lines
3.7 KiB
Markdown
90 lines
3.7 KiB
Markdown
# Updating to new imgui versions
|
|
|
|
This document covers how to upgrade imgui-rs to a new version of the upstream C++ library.
|
|
|
|
The process is much the same to build imgui-rs for a tagged release (as shown) as it is for any arbitrary revision (such as one on a different branch)
|
|
|
|
|
|
## Step by step
|
|
|
|
1. Ensure the submodules are populated (`git submodule init` and `git submodule update --recursive`)
|
|
|
|
2. Check out the desired version of the `imgui-sys/third-party/imgui/` submodule
|
|
|
|
$ pwd
|
|
.../imgui-sys/third-party/imgui
|
|
$ git checkout v1.81
|
|
Previous HEAD position was 58075c44 Version 1.80
|
|
HEAD is now at 4df57136 Version 1.81
|
|
|
|
3. Ensure `luajit` is installed, as this is required by cimgui's generator.
|
|
|
|
$ luajit --help
|
|
|
|
4. Check out the `cimgui` project somewhere, as we use use the generator within this
|
|
|
|
$ git clone --recursive https://github.com/cimgui/cimgui.git /tmp/cimgui
|
|
|
|
5. Ensure the `imgui` submodule within `cimgui` is pointing to the same revision as in `imgui-rs`
|
|
|
|
$ cd /tmp/cimgui/imgui
|
|
$ git checkout v1.81
|
|
HEAD is now at 4df57136 Version 1.81
|
|
|
|
6. Back in `imgui-rs/imgui-sys/third-party/` - run the `update-cimgui-output.sh` helper script to execute cimgui's generator
|
|
|
|
$ pwd
|
|
.../imgui-sys/third-party
|
|
$ ./update-cimgui-output.sh /tmp/cimgui/
|
|
[...]
|
|
copyfile ./output/cimgui.h ../cimgui.h
|
|
copyfile ./output/cimgui.cpp ../cimgui.cpp
|
|
all done!!
|
|
|
|
This updates various files in the imgui-sys folder like `cimgui.cpp`, `definitions.json` and so on
|
|
|
|
With this step, we now have new C bindings to the desired verison of Dear ImGui.
|
|
|
|
7. 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/*`
|
|
|
|
8. Run `cargo build` and fix any errors caused by changes upstream (see next section)
|
|
|
|
9. Run the tests with `cargo test`.
|
|
|
|
10. Try running one of the examples
|
|
|
|
cargo run --example test_window_impl
|
|
|
|
|
|
## 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. Note by default `cimgui` generator will exclude any obsolete API.
|
|
|
|
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)
|