Build instructions

Build instructions#

Build Hello ImGui and its demos#

On almost all platforms, HelloImGui can be compiled with simple commands:

```bash
git clone https://github.com/pthom/hello_imgui.git
cd hello_imgui
mkdir build && cd build
cmake .. 
make -j

This will compile the HelloImGui library, and the demos (which will be located in the build/bin/ folder).

Build your application using Hello ImGui#

To build an application that uses HelloImGui, you can either place HelloImGui inside your project (for example as a submodule), or it can be downloaded and built automatically by cmake.

In any case, follow the build instructions given in the HelloImGui Starter Template

Available backends#

See documentation below (extract from CMakeLists.txt):

#
# You need to select at least two backends:
#
#     - At least one (or more) rendering backend (OpenGL3, Metal, Vulkan, DirectX11, DirectX12)
#       Make your choice according to your needs and your target platforms, between:
#          -DHELLOIMGUI_HAS_OPENGL3=ON    # This is the recommended choice, especially for beginners
#          -DHELLOIMGUI_HAS_METAL=ON      # Apple only, advanced users only
#          -DHELLOIMGUI_HAS_VULKAN=ON     # Advanced users only
#          -DHELLOIMGUI_HAS_DIRECTX11=ON  # Windows only, still experimental
#          -DHELLOIMGUI_HAS_DIRECTX12=ON  # Windows only, advanced users only, still experimental
#
#     - At least one (or more) platform backend (SDL2, Glfw3):
#      Make your choice according to your needs and your target platforms, between:
#          -DHELLOIMGUI_USE_SDL2=ON
#          -DHELLOIMGUI_USE_GLFW3=ON
#
# If you make no choice, the default will be selected:
#     HELLOIMGUI_USE_GLFW3 + HELLOIMGUI_HAS_OPENGL3
#
# Note about rendering backends:
#   OpenGL3 is the recommended choice as a starting point, especially for beginners.
#   Vulkan, Metal, and DirectX11, DirectX12 do work, but you may need to customize the rendering code inside HelloImGui:
#   see src/hello_imgui/internal/backend_impls/rendering_xxxx.[h,cpp]
#   (using those backends probably implies that you want to heavily customize the rendering code)
#
################################################################################
# Platform backends:
option(HELLOIMGUI_USE_GLFW3 "Use Glfw3 as a platform backend" OFF)
option(HELLOIMGUI_USE_SDL2 "Use Sdl2 as a platform backend" OFF)
# Rendering backends
option(HELLOIMGUI_HAS_OPENGL3 "Use OpenGL3 as a rendering backend" OFF)
option(HELLOIMGUI_HAS_METAL "Use Metal as a rendering backend" OFF)
option(HELLOIMGUI_HAS_VULKAN "Use Vulkan as a rendering backend" OFF)
option(HELLOIMGUI_HAS_DIRECTX11 "Use DirectX11 as a rendering backend" OFF)
option(HELLOIMGUI_HAS_DIRECTX12 "Use DirectX12 as a rendering backend" OFF)

# Headless mode: by default, HelloImGui's cmake tooling will always check that there is at least one
# rendering backend and one platform backend that is not a "Null" backend.
# If you set HELLOIMGUI_HEADLESS, you can disable this check, and compile HelloImGui,
# using only the Null rendering/platform backends.
option(HELLOIMGUI_HEADLESS "Allow headless mode (will use Null rendering/platform backend)" OFF)

In order to select your own backend, use one of the afore mentioned backend combinations, for example:

cmake .. -DHELLOIMGUI_USE_SDL2=ON -DHELLOIMGUI_HAS_OPENGL3=ON

Hello ImGui dependencies#

HelloImGui depends on the following libraries:

Glfw3 or SDL2, depending on the platform backend you selected
Freetype, for font rendering, if HELLOIMGUI_USE_FREETYPE is ON, which is the default

Those dependencies may be downloaded and built automatically by cmake, or you can provide your own version of those libraries.

See documentation below (extract from CMakeLists.txt):

# Automatic download of Glfw3, SDL2, and Freetype (provided as a convenience)
#
# (this is disabled by default on Linux, which prefers to use the system libraries,
# enabled by default on other platforms)
#
# Note:
#
# SDL and Glfw3 will be downloaded only if:
# -----------------------------------------
#   - HELLOIMGUI_DOWNLOAD_GLFW_IF_NEEDED or HELLOIMGUI_DOWNLOAD_SDL_IF_NEEDED is ON
#   - HELLOIMGUI_USE_SDL_XXXX or HELLOIMGUI_USE_GLFW_XXXX is ON
#   - SDL and/or Glfw3 were not added as CMake target
#     (add_subdirectory(external/SDL) or add_subdirectory(external/glfw) for example)
#   - find_package(glfw3 or SDL2) fails. If a system library is found,
#     or a user library provided in a path added to CMAKE_PREFIX_PATH,
#     it will be used instead
#
# - Freetype will be downloaded only if:
# --------------------------------------
#   - HELLOIMGUI_DOWNLOAD_FREETYPE is ON, HELLOIMGUI_USE_FREETYPE is ON
#   - Freetype was not added as a CMake target
#         (add_subdirectory(external/freetype) for example)
#   - find_package(freetype) fails
#   (it will also be forcibly downloaded if HELLOIMGUI_FREETYPE_STATIC is ON)
#
#
# Automatic download of SDL2, Glfw3, and Freetype is disabled by default on Linux,
# because it is recommended to use the system libraries instead:
# On ubuntu, you can install them with:
#    sudo apt install libglfw3-dev libsdl2-dev libfreetype-dev
#
#------------------------------------------------------------------------------
if(CMAKE_SYSTEM_NAME MATCHES "Linux")
    set(autodownload_default OFF)
else()
    set(autodownload_default ON)
endif()
option(HELLOIMGUI_DOWNLOAD_GLFW_IF_NEEDED "Download and build GLFW if needed" ${autodownload_default})
option(HELLOIMGUI_DOWNLOAD_SDL_IF_NEEDED "Download and build SDL2 if needed" ${autodownload_default})
option(HELLOIMGUI_DOWNLOAD_FREETYPE_IF_NEEDED "Download and build Freetype if needed" ${autodownload_default})
option(HELLOIMGUI_FREETYPE_STATIC "Force static linking of freetype (only used for python bindings)" OFF)

Get dependencies via vcpkg#

You can install almost all required dependencies with vcpkg.

Note: this will not support ImGui Test Engine, as it is not available in vcpkg yet.

Manually#

The file vcpkg.json defines the dependencies required by HelloImGui.

For example:

# Clone hello_imgui 
git clone https://github.com/pthom/hello_imgui.git
cd hello_imgui
# Clone vcpkg -& bootstrap
git clone https://github.com/microsoft/vcpkg.git
./vcpkg/bootstrap-vcpkg.sh
export VCPKG_ROOT=$(pwd)/vcpkg     # You *need* to set this environment variable
                                   # to tell cmake where to find vcpkg

# Install dependencies required by hello_imgui
# (they will be read from the vcpkg.json file)
./vcpkg/vcpkg install

# Build hello_imgui
mkdir build && cd build
cmake .. -DCMAKE_TOOLCHAIN_FILE=../vcpkg/scripts/buildsystems/vcpkg.cmake
cmake --build . -j 4 

Using CMake Presets:#

The file CMakePresets.json defines several presets which will use vcpkg to grab the required dependencies.

Thus, you can build HelloImGui with vcpkg dependencies, using a CMake preset, like this:

# Clone hello_imgui 
git clone https://github.com/pthom/hello_imgui.git
cd hello_imgui
# Clone vcpkg -& bootstrap
git clone https://github.com/microsoft/vcpkg.git
./vcpkg/bootstrap-vcpkg.sh
export VCPKG_ROOT=$(pwd)/vcpkg     # You *need* to set this environment variable
                                   # to tell cmake where to find vcpkg

# Use the CMake preset "build_vcpkg_default" 
# This will grab all dependencies from vcpkg, 
# and use vcpkg toolchain file
cmake --preset build_vcpkg_default
cmake --build . -j 4 

Hello ImGui CMake options#

The CMakelists.txt file is heavily documented.

Below are the most important options:

Freetype (default: ON, except for Android and Mingw)

option(HELLOIMGUI_USE_FREETYPE "Use freetype for text rendering" ${freetype_default})

ImGui Test Engine (default: OFF)

option(HELLOIMGUI_WITH_TEST_ENGINE "Provide ImGui Test engine" OFF)

OS specific instructions#

Windows instructions#

Under windows, Hello ImGui will automatically provide a WinMain() function that will call main, and expects its signature to be int main(int, char**). You may get a linker error if your main function signature is for example int main().

You can disable this via cmake by passing -DHELLOIMGUI_WIN32_AUTO_WINMAIN=OFF as a command line cmake option. In this case, write your own WinMain under windows.

Warning: if using SDL, you will need to #define SDL_MAIN_HANDLED before any inclusion of SDL.h (to refrain SDL from #defining #define main SDL_main)

iOS instructions#

“SDL + OpenGL ES3” is currently the preferred backend for iOS.

This project uses the ios-cmake toolchain which is a submodule in the folder hello_imgui_cmake/.

See compilation instructions in the HelloImGui Starter Template

Emscripten instructions#

emscripten is a toolchain for compiling to asm.js and WebAssembly, built using LLVM, that lets you run C and C++ on the web at near-native speed without plugins.

See compilation instruction in the HelloImGui Starter Template

To test your emscripten application, you will need a web server. Python provides a basic web server that is easy to usen which you can launch like this:

cd build_emscripten
python3 -m http.server

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

macOS instructions#

If you prefer to build regular terminal executables (not app bundles), use the cmake option -DHELLOIMGUI_MACOS_NO_BUNDLE=ON.

Android instructions#

The Android version uses SDL + OpenGLES3.