diff --git a/README.md b/README.md index 395dadf..4f99fe0 100644 --- a/README.md +++ b/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`: -```sh -python3 $DEAR_BINDINGS_PATH/dear_bindings.py --imconfig-path src/include/zimconfig.h -o src/cached/dcimgui $DEAR_IMGUI_PATH/imgui.h -``` - -Here's how to build `cimgui_internal.h`: -```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. +1. Update `build.zig.zon` +2. Add `python3` to your path +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. +6. Test the bindings from a real Zig program that imports Dear ImGUI. ## Known differences -* doesn't build `binary_to_compressed_c` -* doesn't build `misc/cpp/imgui_stdlib.cpp` -* freetype mode not supported (but easily could be) -* only the vulkan backend is provided as of now (but others are easy to add) -* the Vulkan backend assumes `IMGUI_IMPL_VULKAN_NO_PROTOTYPES` -* 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 + +- doesn't build `binary_to_compressed_c` +- doesn't build `misc/cpp/imgui_stdlib.cpp` +- freetype mode not supported (but easily could be) +- only the vulkan backend is provided as of now (but others are easy to add) +- the Vulkan backend assumes `IMGUI_IMPL_VULKAN_NO_PROTOTYPES` +- 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 diff --git a/build.zig b/build.zig index 1939aba..6acaa82 100644 --- a/build.zig +++ b/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; + } + } } diff --git a/src/cached/dcimgui_imconfig_zig.json b/src/cached/dcimgui_imconfig_zig.json new file mode 100644 index 0000000..1e8d7ac --- /dev/null +++ b/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": [] +} \ No newline at end of file diff --git a/src/cached/dcimgui_impl_sdl3_imconfig_zig.json b/src/cached/dcimgui_impl_sdl3_imconfig_zig.json new file mode 100644 index 0000000..1e8d7ac --- /dev/null +++ b/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": [] +} \ No newline at end of file diff --git a/src/cached/dcimgui_impl_vulkan_imconfig_zig.json b/src/cached/dcimgui_impl_vulkan_imconfig_zig.json new file mode 100644 index 0000000..1e8d7ac --- /dev/null +++ b/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": [] +} \ No newline at end of file diff --git a/src/cached/dcimgui_internal_imconfig_zig.json b/src/cached/dcimgui_internal_imconfig_zig.json new file mode 100644 index 0000000..1e8d7ac --- /dev/null +++ b/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": [] +} \ No newline at end of file