Automates much of the process of upgrading this repo to new Dear ImGUI versions

README.md

@@ -23,8 +23,9 @@ The static library for Dear ImGui, and supported backends, are provided as artif
 ## How to use the backends
 
 Right now, this package only exports the following backends:
-* `dear_imgui_vulkan`
+
-* `dear_imgui_sdl3`
+- `dear_imgui_vulkan`
+- `dear_imgui_sdl3`
 
 Contributions are welcome if you'd like to add others. The process should be fairly straightforward.
 
@@ -39,41 +40,23 @@ At build time, `generate.zig` is called on the relevant JSON files to generate a
 
 `dear_bindings` does not provide enough data to generate perfect pointer types for all situations, but a reasonable conservative heuristic is used to avoid `[*c]` where possible. This could be improved in the future through whitelists.
 
-## How to change versions
+## How to update Dear ImGUI
 
-Update `build.zig.zon`, and then if the headers changed, regenerate them into `src/cached` with [dear_bindings](https://github.com/dearimgui/dear_bindings).
+Note that you never need to do this as a user of the library, unless you're making a PR that upgrades this library to a new Dear ImGUI version.
 
-Here's how to build `cimgui.h`:
+1. Update `build.zig.zon`
-```sh
+2. Add `python3` to your path
-python3 $DEAR_BINDINGS_PATH/dear_bindings.py --imconfig-path src/include/zimconfig.h -o src/cached/dcimgui $DEAR_IMGUI_PATH/imgui.h
+3. Set `$DEAR_BINDINGS` to a path to an appropriate version of [dear_bindings](https://github.com/dearimgui/dear_bindings) for the version of Dear ImGUI you're updating to
-```
+4. Run `zig build dear_bindings`. Output may need tweaks, glance over diff.
-
+5. Run `zig build generate` to see if the generator still works. If it fails, you're probably missing values in an enumeration, `std.json` does not provide helper errors for this at the time of writing, the easiest way to debug this is to comment out the actual generation code, and all fields in `Header`, adding them back until you figure out which are causing the issue.
-Here's how to build `cimgui_internal.h`:
+6. Test the bindings from a real Zig program that imports Dear ImGUI.
-```sh
-python3 $DEAR_BINDINGS_PATH/dear_bindings.py --imconfig-path src/include/zimconfig.h -o src/cached/dcimgui_internal --include $DEAR_IMGUI_PATH/imgui.h $DEAR_IMGUI_PATH/imgui_internal.h
-```
-
-Here's how to build a backend, using Vulkan as an example:
-
-```sh
-python3 $DEAR_BINDINGS_PATH/dear_bindings.py --backend --imconfig-path src/include/zimconfig.h -o src/cached/cimgui_impl_vulkan $DEAR_IMGUI_PATH/backends/imgui_impl_vulkan.h
-```
-
-And here's SDL3:
-
-```sh
-python3 $DEAR_BINDINGS_PATH/dear_bindings.py --backend --imconfig-path src/include/zimconfig.h -o src/cached/dcimgui_impl_sdl3 $DEAR_IMGUI_PATH/backends/imgui_impl_sdl3.h
-```
-
-If `generator.zig` fails, you may need to add missing values to the enumeration. `std.json` does not provide helpful errors at the time of writing, the easiest way to debug this is to comment out the actual generation code, and all fields in `Header`, adding them back until you figure out which are causing the issue.
-
-You can also debug the generator with the `generate` command.
 
 ## Known differences
-* doesn't build `binary_to_compressed_c`
+
-* doesn't build `misc/cpp/imgui_stdlib.cpp`
+- doesn't build `binary_to_compressed_c`
-* freetype mode not supported (but easily could be)
+- doesn't build `misc/cpp/imgui_stdlib.cpp`
-* only the vulkan backend is provided as of now (but others are easy to add)
+- freetype mode not supported (but easily could be)
-* the Vulkan backend assumes `IMGUI_IMPL_VULKAN_NO_PROTOTYPES`
+- only the vulkan backend is provided as of now (but others are easy to add)
-* the Vulkan backend assumes dynamic rendering is available (>= `VK_VERSION_1_3` or `VK_KHR_dynamic_rendering`)
+- the Vulkan backend assumes `IMGUI_IMPL_VULKAN_NO_PROTOTYPES`
-    * we could add support for this conditional, but it seems unlikely to get much use
+- the Vulkan backend assumes dynamic rendering is available (>= `VK_VERSION_1_3` or `VK_KHR_dynamic_rendering`)
+  - we could add support for this conditional, but it seems unlikely to get much use

build.zig

@@ -176,4 +176,56 @@ pub fn build(b: *std.Build) void {
     });
     const docs_step = b.step("docs", "Build the docs");
     docs_step.dependOn(&install_docs.step);
+
+    const dear_bindings = b.step("dear_bindings", "Update the cached bindings in this project's source tree to a new version of Dear ImGUI");
+    dear_bindings: {
+        const dear_bindings_path = b.graph.environ_map.get("DEAR_BINDINGS") orelse {
+            dear_bindings.dependOn(&b.addFail("$DEAR_BINDINGS not set").step);
+            break :dear_bindings;
+        };
+        {
+            const run = b.addSystemCommand(&.{ "python3", dear_bindings_path });
+            run.addArg("--imconfig-path");
+            run.addFileArg(b.path("src/include/imconfig_zig.h"));
+            run.addArg("-o");
+            run.addArg("src/cached/dcimgui");
+            run.addFileArg(upstream.path("imgui.h"));
+            dear_bindings.dependOn(&run.step);
+            run.has_side_effects = true;
+        }
+        {
+            const run = b.addSystemCommand(&.{ "python3", dear_bindings_path });
+            run.addArg("--imconfig-path");
+            run.addFileArg(b.path("src/include/imconfig_zig.h"));
+            run.addArg("-o");
+            run.addArg("src/cached/dcimgui_internal");
+            run.addFileArg(upstream.path("imgui_internal.h"));
+            run.addArg("--include");
+            run.addFileArg(upstream.path("imgui.h"));
+            dear_bindings.dependOn(&run.step);
+            run.has_side_effects = true;
+        }
+        {
+            const run = b.addSystemCommand(&.{ "python3", dear_bindings_path });
+            run.addArg("--backend");
+            run.addArg("--imconfig-path");
+            run.addFileArg(b.path("src/include/imconfig_zig.h"));
+            run.addArg("-o");
+            run.addArg("src/cached/dcimgui_impl_vulkan");
+            run.addFileArg(upstream.path("backends/imgui_impl_vulkan.h"));
+            dear_bindings.dependOn(&run.step);
+            run.has_side_effects = true;
+        }
+        {
+            const run = b.addSystemCommand(&.{ "python3", dear_bindings_path });
+            run.addArg("--backend");
+            run.addArg("--imconfig-path");
+            run.addFileArg(b.path("src/include/imconfig_zig.h"));
+            run.addArg("-o");
+            run.addArg("src/cached/dcimgui_impl_sdl3");
+            run.addFileArg(upstream.path("backends/imgui_impl_sdl3.h"));
+            dear_bindings.dependOn(&run.step);
+            run.has_side_effects = true;
+        }
+    }
 }

src/cached/dcimgui_imconfig_zig.json

@@ -0,0 +1,16 @@
+{
+    "defines": [
+        {
+            "name": "IMGUI_USE_WCHAR32",
+            "is_internal": false,
+            "source_location": {
+                "filename": "imconfig_zig.h",
+                "line": 2
+            }
+        }
+    ],
+    "enums": [],
+    "typedefs": [],
+    "structs": [],
+    "functions": []
+}

src/cached/dcimgui_impl_sdl3_imconfig_zig.json

@@ -0,0 +1,16 @@
+{
+    "defines": [
+        {
+            "name": "IMGUI_USE_WCHAR32",
+            "is_internal": false,
+            "source_location": {
+                "filename": "imconfig_zig.h",
+                "line": 2
+            }
+        }
+    ],
+    "enums": [],
+    "typedefs": [],
+    "structs": [],
+    "functions": []
+}

src/cached/dcimgui_impl_vulkan_imconfig_zig.json

@@ -0,0 +1,16 @@
+{
+    "defines": [
+        {
+            "name": "IMGUI_USE_WCHAR32",
+            "is_internal": false,
+            "source_location": {
+                "filename": "imconfig_zig.h",
+                "line": 2
+            }
+        }
+    ],
+    "enums": [],
+    "typedefs": [],
+    "structs": [],
+    "functions": []
+}

src/cached/dcimgui_internal_imconfig_zig.json

@@ -0,0 +1,16 @@
+{
+    "defines": [
+        {
+            "name": "IMGUI_USE_WCHAR32",
+            "is_internal": false,
+            "source_location": {
+                "filename": "imconfig_zig.h",
+                "line": 2
+            }
+        }
+    ],
+    "enums": [],
+    "typedefs": [],
+    "structs": [],
+    "functions": []
+}