cimgui: a generated C shim over Dear ImGui, and what regeneration actually costs

What the generated files are, and who consumes each one

cimgui is a thin C API wrapper generated programmatically for Dear ImGui, the C++ immediate mode GUI library from ocornut/imgui. The README states that all imgui.h functions are programmatically wrapped. Two files come out of that for C compilation, cimgui.cpp and cimgui.h.

The other two outputs exist for binding authors rather than for C callers: definitions.lua with function definition information, and structs_and_enums.lua with struct and enum information. The generator section repeats the same idea with JSON, naming definitions.json, structs_and_enums.json and impl_definitions.json as the emitted metadata files.

So there are two audiences. A C or C++ program includes cimgui.h directly, while a binding generator reads the JSON and emits the glue for its own language. The README states the library is intended as an intermediate layer so that Dear ImGui can be used from other languages able to interface with C, and points at Extrawurst's D binding DerelictImgui as an example.

Version tracking is the reason the generator exists

The history section explains the architecture. cimgui was initially developed by Stephan Dilly as hand written code, and later turned into an auto generated version by sonora1234 in order to keep up with imgui more easily, letting the user select the desired branch and commit.

That is the whole reason the generator is written in LuaJIT rather than in the same language as the wrapper. Pinning a C shim to a moving C++ library by hand does not scale, so the generation step is the maintenance mechanism.

The cost is a stated dependency on a specific Dear ImGui version. The README says the wrapper is currently based on version 1.92.9b of Dear ImGui with internal api. A binding author who needs a different version regenerates rather than patches, which is a workflow difference and not just a build step.

Release tags on this repository stop in the 2017 to 2018 range, with v1.53.1 as the most recent, while the last push was on 2026-09-14. The activity is in the default branch, which is docking_inter, not in the tags.

Cloning requires submodules, and the build is Makefile or CMake

The imgui sources live in a submodule, so a shallow clone is not enough:

git clone --recursive https://github.com/cimgui/cimgui.git
git submodule update --init --recursive

The second line is the one to run if you already cloned. After that the README offers two build routes: a Makefile for linux, macOS and mingw, or CMake to generate a project.

The CMake options are worth reading because they decide what you are actually linking. IMGUI_STATIC compiles a static library rather than a shared one. IMGUI_FREETYPE enables FreeType2 text rendering, with FREETYPE_PATH pointing at the FreeType2 CMake install location. IMGUI_WCHAR32 and CIMGUI_VARGS0 cover a wchar_t mode and a function variant without varargs for vararg functions, where the generated name carries a 0 suffix.

The Makefile shows the shared library naming and the static target

The cross platform Makefile is explicit about what each platform produces. On Linux the output is cimgui.so, with -shared -fPIC added and an include path of ./imgui/. On macOS it is cimgui.dylib, built with -dynamiclib and an include path of /usr/local/include. On Windows it is cimgui.dll, with -shared and -limm32.

Compiler flags are fixed rather than configurable in the file:

CXXFLAGS=-O2 -fno-exceptions -fno-rtti

That is a meaningful constraint on what Dear ImGui code will link against, since it removes exceptions and RTTI from the translation units.

There are two build entry points beyond the default. The default target builds the shared library, while a static target archives the object files:

static:$(OBJS)
	$(AR) libcimgui.a $(OBJS)

The object list covers the wrapper plus the imgui translation units themselves: imgui.o, imgui_draw.o, imgui_demo.o, imgui_tables.o and imgui_widgets.o. A re target exists for clean and rebuild, and clean removes objects with a platform specific rm or del so the Makefile works under both.

Non-POD structs gain a _c suffix, and that changes call names

The changes section documents the one behavioural change that will affect existing calling code. Dated 10/11/2025, functions returning or taking non-POD structs as arguments now do an internal conversion to allow ARM64 compilation.

The metadata records this: in structs_and_enums.json, the key nonPOD_used collects the types that are not usable from C and appear as returns or arguments. The value is either true, or "inherited" when the type comes from cimgui and appears in a cimgui extension such as cimplot. The C names for these carry a _c suffix.

That is a source breaking change for anyone calling the old name, and it is the kind of detail a binding generator consumes directly from the metadata rather than discovering at link time.

Running the generator needs LuaJIT, a C++ preprocessor and a config edit

Regeneration is optional unless you want a different imgui version, because generation is already done in the repository. When you do need it, the toolchain is three things: LuaJIT, preferably the 2.1 branch, a C++ compiler used for preprocessing (gcc, clang or cl, and the repo was done with gcc), and the imgui folder updated to the version you want.

The behaviour is selected in a script rather than in a config file. You edit generator/generator.bat on Windows or generator/generator.sh on Linux to choose the compiler, the backends, whether imgui_internal is generated, whether comments are generated, and whether constructors are generated, including versions that only initialise structs you provide yourself using IM_PLACEMENT_NEW, with _Construct added to the constructor names. The defaults are gcc as compiler, imgui_internal included, and sdl, glfw, vulkan, opengl2 and opengl3 as backends. Backend includes go in config_generator.lua, and the README notes vulkan needs one.

Compiler flags can be passed to the generator by editing them at the end of the call, for example -DIMGUI_USER_CONFIG. Custom options are easy to lose on the next update, and the README has a specific workaround: keep your own copy of generator.sh or generator.bat outside the cimgui folder.

Backends are somebody else's project here

cimgui wraps the core API only. The README is explicit that only functions, structs and enums from imgui.h are wrapped, optionally from imgui_internal.h, and that anyone interested in imgui backends should look at the LuaJIT-ImGui project instead.

That division matters for binding authors. cimgui produces the core surface and the metadata; platform integration, windowing and rendering are a separate layer. The generated cimgui_impl.h and impl_definitions.json cover backend functions when backends are selected in the generator, which is the hook a binding uses to reach them.

For compiling with backends, the README points at the backend_test folder, which now contains examples with SDL2 and opengl3/vulkan. Those produce a cimgui_sdl module and a test_sdl executable, which is the fastest way to confirm a toolchain works before writing a binding.

Licensing and the hand written exceptions

The repository is MIT licensed, and the wrapper is a mechanical transformation of the Dear ImGui API surface, so the licence obligations of your own project depend on Dear ImGui's terms as much as on cimgui's.

One nuance is worth knowing for anyone auditing generated code. Naming is algorithmic except for names coded in the cimgui_overloads table in generator.lua, and in the official version that table is empty. Overloads also exist outside that table: current overloaded function names are listed in generator/output/overloads.txt. The definitions metadata marks individual functions as manual when they are hand written rather than generated, and as skipped when a function is neither generated nor hand written, so an audit of what is and is not covered is possible from the metadata rather than by reading the C.

Editorial conclusion

Adopt cimgui if you are writing a language binding for Dear ImGui, or need the internal api exposed, and you are prepared to run the generator yourself against the imgui version you need. Do not adopt it as an application dependency for a language that already has a maintained binding, since cimgui is explicitly described as an intermediate layer for binding authors rather than a user facing GUI library, and the README redirects backend work to LuaJIT-ImGui. Verify first which Dear ImGui version your consumer expects, because the wrapper states it is based on version 1.92.9b, and note the function name suffixes _c and 0 that the generator adds for non-POD structs and vararg free variants.

Frequently asked questions

Official sources

1. cimgui/cimgui on GitHub
2. Issues
3. License: MIT
4. README
5. Releases