pthom / hello_imgui_template

A quick start template to work with Hello ImGui

hello_imgui_template: get started with HelloImGui in 5 minutes

This template demonstrates how to easily integrate HelloImGui to your own project.

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

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

Explanations

CMake

The CMakeLists.txt file will download and build hello_imgui at configure time, and make the "hello_imgui_add_app" cmake function available.

By default, you do not need to add HelloImGui as a dependency to your project, it will be downloaded and built automatically during CMake configure time. If you wish to use a local copy of HelloImGui, edit CMakeLists.txt and uncomment the add_subdirectory line.

Note: hello_imgui_add_app will automatically link your app to hello_imgui, embed the assets folder (for desktop, mobile, and emscripten apps), and the application icon.

Assets

Anything in the assets/ folder located beside the app's CMakeLists will be bundled together with the app (for macOS, iOS, Android, Emscripten). The files in assets/app_settings/ will be used to generate the app icon, and the app settings.

assets/
├── world.jpg                   # 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

Build instructions

Build for Linux and macOS

1. Optional: clone hello_imgui

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

In this example, we clone hello_imgui inside external/hello_imgui

Note: external/ is mentioned in .gitignore

mkdir -p external && cd external
git clone https://github.com/pthom/hello_imgui.git
cd ..

Add this line at the top of your CMakeLists.txt

add_subdirectory(external/hello_imgui)

2. Create the build directory, run cmake and make

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

Build for Windows

1. Optional: clone hello_imgui

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/helloworld_with_helloimgui.sln

Build for Android

1. Clone hello_imgui:

You will need to clone hello_imgui. 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/hello_imgui.git
cd ..

Add this line at the top of your CMakeLists.txt

add_subdirectory(external/hello_imgui)

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/hello_imgui/tools/android/cmake_arm-android.sh ../

3. Open the project in Android Studio

It should be located in build_android/hello_world_AndroidStudio.

Build for iOS

1. Clone hello_imgui: 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/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_SDL_OPENGL3=ON

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

Build for emscripten

Install emscripten

You can either install emsdk following the instruction on the emscripten website or you can use the script ../tools/emscripten/install_emscripten.sh.

Compile with emscripten

# Add emscripten tools to your path
source ~/emsdk/emsdk_env.sh

# cmake and build
mkdir build_emscripten
cd build_emscripten
emcmake cmake ..
make -j 4

# launch a webserver
python3 -m http.server

Open a browser, and navigate to http://localhost:8000.