How to integrate Dear ImGui Bundle into your C++ application

This template demonstrates how to easily integrate Dear ImGui Bundle to your own project.

You can use it as a starting point for your own project.

Template repository: https://github.com/pthom/imgui_bundle_template

CMake

By default, you do not need to add imgui_bundle as a dependency to your project, it will be downloaded and built automatically during CMake configure time.

The CMakeLists.txt file

• Downloads imgui_bundle at configure time

• Makes the imgui_bundle_add_app cmake function available

• Uses imgui_bundle_add_app to build your app and link it with ImGuiBundle

Note: imgui_bundle_add_app will automatically link your app to imgui_bundle, and will embed the assets folder (for desktop, mobile, and emscripten apps)

Assets

Anything in the assets/ folder located beside the app’s CMakeLists will be bundled together with the app (for macOS, iOS, linux, emscripten).

The files in assets/app_settings/ will be used to generate the app icon, and the app settings.

assets/
├── world.png                   # A custom asset
│
├── app_settings/               # Application settings
│    ├── icon.png               # This will be the app icon, it should be square
│    │                          # and at least 256x256. It will  be converted
│    │                          # to the right format, for each platform (except Android)
│    ├── apple/
│    │    ├── Info.plist        # macOS and iOS app settings
│    │    │                      # (or Info.ios.plist + Info.macos.plist)
│    │    └── Resources/
│    │         └── ios/          # iOS specific settings: storyboard
│    │             └── LaunchScreen.storyboard
│    ├── android/                # Android app settings: any file placed here will be deployed
│    │   │── AndroidManifest.xml # (Optional manifest, HelloImGui will generate one if missing)
│    │   └── res/
│    │       └── mipmap-xxxhdpi/ # Optional icons for different resolutions
│    │           └── ...         # Use Android Studio to generate them:
│    │                           # right click on res/ => New > Image Asset
│    │
│    └── emscripten/
│        ├── shell.emscripten.html # Emscripten shell file
│        │                         #   (this file will be cmake "configured"
│        │                         #    to add the name and favicon)
│        └── custom.js             # Any custom file here will be deployed
│                                  #   in the emscripten build folder
│
├── fonts/
│    ├── DroidSans.ttf           # Default fonts
│    └── fontawesome-webfont.ttf #     used by HelloImGui
│    ├── Roboto
│    │    ├── Roboto-Bold.ttf        # Font used by Markdown
│    │    ├── Roboto-BoldItalic.ttf
│    │    ├── Roboto-Regular.ttf
│    │    └── Roboto-RegularItalic.ttf
│    ├── Inconsolata-Medium.ttf
├── images
│    └── markdown_broken_image.png

Main cpp file

The hello_world.cpp file

• Provides a Gui function which is executed at each frame

• Provides a main function that set the ImmApp ("Immediate App") params, and mentions the addons we intend to use (here we are using markdown and implot).

Build instructions

Build for Linux and macOS

1. Optional: clone imgui_bundle

Note: This step is optional, since the CMakeLists.txt file will by default download and build imgui_bundle at configure time.

In this example, we clone imgui_bundle inside external/imgui_bundle.

mkdir -p external && cd external
git clone https://github.com/pthom/imgui_bundle.git
cd imgui_bundle && git submodule update --init --recursive
cd ../..

Notes:

• external/ is mentioned in .gitignore

• The main CMakeLists will detect the presence of external/imgui_bundle and will use it instead of downloading it.

2. Create the build directory, run cmake and make

mkdir -p build && cd build
cmake ..
make -j 4

Build for Windows

1. Optional: clone imgui_bundle

Follow step 1 from the Linux/macOS section above.

2. Create the build directory, run cmake

mkdir build && cd build
cmake ..

3. Open the Visual Studio solution

It should be located in build/imgui_bundle_example_integration.sln

Build for emscripten

Install emscripten

You can either install emsdk following the instruction on the emscripten website.

Compile with emscripten

# Add emscripten tools to your path
# (assuming you installed emscripten in ~/emsdk)
source ~/emsdk/emsdk_env.sh

# cmake and build
mkdir build_emscripten
cd build_emscripten
emcmake cmake .. -DCMAKE_BUILD_TYPE=Release # (Release builds lead to smaller files)
make -j 4

# launch a webserver
python3 -m http.server

Open a browser, and navigate to [http://localhost:8000](http://localhost:8000).

Build for Android

1. Clone imgui_bundle

You will need to clone imgui_bundle. In this example, we clone hello_imgui inside hello_imgui_template/external/hello_imgui

Note: external/ is mentioned in .gitignore

mkdir -p external && cd external
git clone https://github.com/pthom/imgui_bundle.git
cd imgui_bundle && git submodule update --init --recursive && cd ..
cd ..

Add this line at the top of your CMakeLists.txt

add_subdirectory(external/imgui_bundle)

2. Create the Android Studio project

# Set the ANDROID_HOME and ANDROID_NDK_HOME environment variables
# For example:
export ANDROID_HOME=/Users/YourName/Library/Android/sdk
export ANDROID_NDK_HOME=/Users/YourName/Library/Android/sdk/ndk/26.1.10909125

mkdir build_android && cd build_android
../external/imgui_bundle/external/hello_imgui/hello_imgui/tools/android/cmake_arm-android.sh ..

3. Open the project in Android Studio

It should be located in build_android/imgui_bundle_example_integration_AndroidStudio

Build for iOS

1. Clone imgui_bundle: follow steps 1 from the Android section above.

2. Create the Xcode project

mkdir build_ios && cd build_ios

Run CMake with the following command, where you replace XXXXXXXXX with your Apple Developer Team ID, and com.your_website with your website (e.g. com.mycompany).

cmake .. \
-GXcode \
-DCMAKE_TOOLCHAIN_FILE=../external/imgui_bundle/external/hello_imgui/hello_imgui/hello_imgui_cmake/ios-cmake/ios.toolchain.cmake \
-DPLATFORM=OS64COMBINED \
-DCMAKE_XCODE_ATTRIBUTE_DEVELOPMENT_TEAM=XXXXXXXXX \
-DHELLO_IMGUI_BUNDLE_IDENTIFIER_URL_PART=com.your_website \
-DHELLOIMGUI_USE_SDL2=ON \
-DHELLOIMGUI_FREETYPE_STATIC=ON \
-DHELLOIMGUI_HAS_OPENGL3=ON

Then, open the XCode project in build_ios/imgui_bundle_example_integration.xcodeproj