elias/imgui-rs
1
0
Fork 0
mirror of https://github.com/eliasstepanik/imgui-rs.git synced 2026-01-11 21:48:36 +00:00
Code Issues Packages Projects Releases Wiki Activity

Documenting process to update imgui version

Browse Source
This commit is contained in:
dbr 2021-03-03 16:51:39 +11:00
parent fbd5353648
commit 89e94c55c5
1 changed files with 80 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

80
imgui-sys/README.md Normal file
View File

@ -0,0 +1,80 @@
# 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
## 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)