This document provides an overview of Dear ImGui's build system infrastructure, including compilation approaches, continuous integration, and automated testing. It covers how the core library and examples are built across multiple platforms and compilers, as well as the validation mechanisms that ensure compatibility.
For detailed information about compiler flags, dependency management, and integrating Dear ImGui into specific build systems, see Build Configuration. For information about the CI/CD pipeline, automated testing workflows, and static analysis, see CI/CD Pipeline.
Dear ImGui follows a minimal build system philosophy designed for maximum portability and ease of integration:
No Required Build System: The core library does not mandate a specific build system. Users can integrate Dear ImGui by simply adding the necessary .cpp files to their existing project structure.
Self-Contained Core: The essential library consists of a small set of C++ files that compile independently without external dependencies (except for the C++ standard library):
imgui.cpp - Core context and APIimgui_widgets.cpp - Standard widgetsimgui_tables.cpp - Table systemimgui_draw.cpp - Drawing primitives and font renderingimgui_demo.cpp (optional) - Demo window for learningBackend Integration: Platform and renderer backends in backends/ are similarly self-contained, requiring only the relevant platform/graphics API headers.
Example-Driven Validation: Rather than providing a unified build system, Dear ImGui includes complete example applications that demonstrate proper integration with various build systems and platforms. These examples serve both as integration templates and as CI validation targets.
Sources: .github/workflows/build.yml1-794
Dear ImGui supports multiple build approaches to accommodate different project structures and developer preferences:
The simplest approach: add source files directly to your project's existing build system.
# Minimal set for basic integration:
imgui.cpp
imgui_widgets.cpp
imgui_tables.cpp
imgui_draw.cpp
backends/imgui_impl_<platform>.cpp
backends/imgui_impl_<renderer>.cpp
All Linux and macOS examples include Makefiles that demonstrate compilation with GCC and Clang. Example structure at examples/example_glfw_opengl3/Makefile
Key features:
WITH_EXTRA_WARNINGS=1WITH_FREETYPE=1Windows examples include .vcxproj files for Visual Studio integration. The CI automatically updates these to use the latest available toolset.
Sources: .github/workflows/build.yml52-59 .github/workflows/build.yml121-267
Select examples provide CMakeLists.txt for CMake-based builds, particularly for cross-platform web deployment:
emcmake cmake for WebAssembly compilationXcode Projects: iOS and macOS examples use .xcodeproj files
Gradle: Android example uses Gradle for APK assembly
Emscripten Makefiles: Web examples provide specialized Makefile.emscripten
Sources: .github/workflows/build.yml587-605 .github/workflows/build.yml622-647 .github/workflows/build.yml656-659
The CI infrastructure validates Dear ImGui across a comprehensive build matrix:
| Platform | Compilers | Architectures | Build Systems |
|---|---|---|---|
| Windows | MSVC, MinGW | Win32, x64 | MSBuild, Make, manual |
| Linux | GCC, Clang | 32-bit, 64-bit | Make, manual |
| macOS | Clang | 64-bit (x86_64, arm64) | Make, Xcode |
| iOS | Clang | arm64 | Xcode |
| Android | Clang (NDK) | armeabi-v7a, arm64-v8a, x86, x86_64 | Gradle + CMake |
| Emscripten | emcc | WebAssembly | Makefile, CMake |
Sources: .github/workflows/build.yml19-267 .github/workflows/build.yml268-507 .github/workflows/build.yml508-593 .github/workflows/build.yml594-605 .github/workflows/build.yml606-647 .github/workflows/build.yml649-659
Dear ImGui uses example_null as a configuration test bed to validate compile-time options and edge cases. This example compiles the library without any actual rendering, making it ideal for fast validation.
The CI tests the following configuration combinations through example_null:
Disable Flags (tested via single-file builds):
IMGUI_DISABLE_OBSOLETE_FUNCTIONS - Removes deprecated API functionsIMGUI_DISABLE_OBSOLETE_KEYIO - Removes legacy key I/OIMGUI_DISABLE_DEMO_WINDOWS - Excludes demo codeIMGUI_DISABLE_DEBUG_TOOLS - Excludes debug utilitiesIMGUI_DISABLE_FILE_FUNCTIONS - Removes file I/O dependenciesIMGUI_DISABLE_WIN32_FUNCTIONS - Removes Win32-specific functionsType Customizations:
IMGUI_USE_WCHAR32 - 32-bit Unicode character supportImDrawIdx = unsigned int - Large index buffers (>65k vertices)ImTextureID types (pointer, struct)IMGUI_USE_BGRA_PACKED_COLOR - Alternative color packingC++ Standards:
-nodefaultlibs -fno-rtti -fno-exceptions)Build Modes:
misc/single_file/imgui_single_file.hIMGUI_API = __declspec(dllexport/dllimport)Sources: .github/workflows/build.yml62-106 .github/workflows/build.yml286-489 .github/workflows/build.yml525-559
The build system integrates with the Dear ImGui Test Engine for automated functional testing:
Test Platforms:
Test Execution:
IMGUI_HAS_DOCK define)-nogui -nopause)-v2 -ve4)Sources: .github/workflows/build.yml661-755
The build system includes automated static analysis through PVS-Studio:
Workflow Trigger: The static-analysis.yml workflow triggers after the build.yml workflow completes successfully.
Analysis Process:
example_null with extra warnings enabledimstb_*.h headers)License Management: The workflow supports both licensed and free PVS-Studio analysis. If no license is configured, the analysis is skipped without failing the build.
Sources: .github/workflows/static-analysis.yml1-47
Dear ImGui's build system handles external dependencies through platform-specific package managers and direct downloads:
Downloaded at CI runtime:
SDL2-devel-2.32.8-VC.zip from libsdl.orgSDL3-devel-3.2.18-VC.zip from libsdl.orgThe Vulkan libraries are manually generated using .github/workflows/build_windows_vulkan_libs.ps1 and uploaded to avoid building them on every CI run.
Installed via apt-get:
libglfw3-dev - GLFW windowinglibsdl2-dev - SDL2 librarygcc-multilib, g++-multilib - Multi-architecture supportlibfreetype6-dev - FreeType font renderinglibvulkan-dev - Vulkan development filesInstalled via Homebrew:
glfw3 - GLFW windowingsdl2 - SDL2 librarysdl3 - SDL3 libraryManaged by Gradle with Android SDK/NDK:
Sources: .github/workflows/build.yml37-50 .github/workflows/build.yml281-284 .github/workflows/build.yml521-523
Dear ImGui supports single-file compilation through misc/single_file/imgui_single_file.h, which includes all core implementation files. This is extensively tested in CI:
The CI validates single-file builds with various configurations to ensure all preprocessor combinations work correctly.
Advantages:
Limitations:
Sources: .github/workflows/build.yml82-105 .github/workflows/build.yml323-489
The build workflow uses GitHub Actions' workflow_run trigger to optimize CI resource usage:
Always Built (on every push/PR):
example_null configurationsexample_glfw_opengl3, example_sdl2_directx11)Conditionally Built (only on workflow_run events):
This strategy balances validation coverage with CI execution time. Pull requests receive quick feedback on core configurations, while scheduled builds provide comprehensive validation.
The workflow_run trigger is activated by the dummy scheduled.yml workflow that runs daily at 9:00 UTC.
Sources: .github/workflows/build.yml6-16 .github/workflows/build.yml121-192 .github/workflows/scheduled.yml1-16
Refresh this wiki