Prepare inclusion of sokol_imgui.h into sokol-zig bindings.

CHANGELOG.md

@@ -4,6 +4,16 @@
 to the example code or the supported Zig version. For actual Sokol header changes, see the
 [sokol changelog](https://github.com/floooh/sokol/blob/master/CHANGELOG.md).
 
+### 01-Jun-2024
+
+- added bindings for sokol_imgui.h (please read the section `## Dear ImGui support`
+  in the readme, and also check out this [example project](https://github.com/floooh/sokol-zig-imgui-sample))
+- the sokol C library name has been renamed from `sokol` to `sokol_clib`, and
+  is now exposed to the outside world via `installArtifact()` (this allows a user of
+  the sokol dependency to lookup the CompileStep for the sokol C library via
+  `dep_sokol.artifact("sokol_clib"))` which is important to inject a cimgui
+  header search path (e.g. via `dep_sokol.artifact("sokol_clib").addIncludePath(cimgui_root);`)
+
 ### 20-Apr-2024
 
 - update the emsdk dependency to 3.1.57

README.md

@@ -234,3 +234,35 @@ This list might grow longer over time!
   target, for instance using `std.fs` functions will most likely fail
   to compile (the sokol-zig bindings might add more sokol headers
   in the future to fill some of the gaps)
+
+## Dear ImGui support
+
+The sokol-zig bindings come with sokol_imgui.h (exposed as the Zig package
+`sokol.imgui`), but integration into a project's build.zig requires some extra
+steps, mainly because I didn't want to add a
+[cimgui](https://github.com/cimgui/cimgui) dependency to the sokol-zig package
+(especially since cimgui uses git submodule which are not supported by the Zig
+package manager).
+
+The main steps to create Dear ImGui apps with sokol-zig are:
+
+1. 'bring your own cimgui'
+2. tell the sokol dependency that it needs to include sokol_imgui.h into
+  the compiled C library:
+    ```zig
+    const dep_sokol = b.dependency("sokol", .{
+        .target = target,
+        .optimize = optimize,
+        .with_sokol_imgui = true,
+    });
+    ```
+3. inject the path to the cimgui directory into the sokol dependency so
+  that C compilation works (this needs to find the `cimgui.h` header)
+
+    ```zig
+    dep_sokol.artifact("sokol_clib").addIncludePath(cimgui_root);
+    ```
+
+Also see the following example project:
+
+https://github.com/floooh/sokol-zig-imgui-sample/

build.zig

@@ -18,6 +18,7 @@ pub fn build(b: *Build) !void {
     const opt_use_x11 = b.option(bool, "x11", "Force X11 (default: true, Linux only)") orelse true;
     const opt_use_wayland = b.option(bool, "wayland", "Force Wayland (default: false, Linux only, not supported in main-line headers)") orelse false;
     const opt_use_egl = b.option(bool, "egl", "Force EGL (default: false, Linux only)") orelse false;
+    const opt_with_sokol_imgui = b.option(bool, "with_sokol_imgui", "Add support for sokol_imgui.h bindings") orelse false;
     const sokol_backend: SokolBackend = if (opt_use_gl) .gl else if (opt_use_wgpu) .wgpu else .auto;
 
     const target = b.standardTargetOptions(.{});
@@ -33,6 +34,7 @@ pub fn build(b: *Build) !void {
         .use_wayland = opt_use_wayland,
         .use_x11 = opt_use_x11,
         .use_egl = opt_use_egl,
+        .with_sokol_imgui = opt_with_sokol_imgui,
         .emsdk = emsdk,
     });
     mod_sokol.linkLibrary(lib_sokol);
@@ -153,14 +155,20 @@ pub const LibSokolOptions = struct {
     use_x11: bool = true,
     use_wayland: bool = false,
     emsdk: ?*Build.Dependency = null,
+    with_sokol_imgui: bool = false,
 };
 pub fn buildLibSokol(b: *Build, options: LibSokolOptions) !*Build.Step.Compile {
     const lib = b.addStaticLibrary(.{
-        .name = "sokol",
+        .name = "sokol_clib",
         .target = options.target,
         .optimize = options.optimize,
         .link_libc = true,
     });
+
+    // installArtifact allows us to find the lib_sokol compile step when
+    // sokol is used as package manager dependency via 'dep_sokol.artifact("sokol_clib")'
+    b.installArtifact(lib);
+
     if (options.target.result.isWasm()) {
         // make sure we're building for the wasm32-emscripten target, not wasm32-freestanding
         if (lib.rootModuleTarget().os.tag != .emscripten) {
@@ -271,6 +279,15 @@ pub fn buildLibSokol(b: *Build, options: LibSokolOptions) !*Build.Step.Compile {
             .flags = cflags,
         });
     }
+
+    // optional Dear ImGui support, the called is required to also
+    // add the cimgui include path to the returned compile step
+    if (options.with_sokol_imgui) {
+        lib.addCSourceFile(.{
+            .file = b.path(csrc_root ++ "sokol_imgui.c"),
+            .flags = cflags,
+        });
+    }
     return lib;
 }
 

src/sokol/c/sokol_imgui.c

@@ -0,0 +1,9 @@
+#if defined(IMPL)
+#define SOKOL_IMGUI_IMPL
+#endif
+#include "sokol_defines.h"
+#include "sokol_app.h"
+#include "sokol_gfx.h"
+#define CIMGUI_DEFINE_ENUMS_AND_STRUCTS
+#include "cimgui.h"
+#include "sokol_imgui.h"