Customising the build system

While the default CMakeLists.txt file is enough for most projects, some might require additional patches, for things like adding additional libraries.

The Config/cmake/<project name>.cmake script

You can configure variables and add custom functions inside the Config/cmake/<project name>.cmake file. This file will get loaded before all other CMake scripts, so some functionality, like calling custom functions will have to be refactored into callbacks.

Simple variables

You can easily modify the include directories or other options that don't require a target inside the project.cmake file. For example, if your project needs to include a library stored in the root directory, instead of in source, you can write the following code to set up the include directories:

include_directories(MyLibrary/include/)
link_directories(MyLibrary/lib/)

Getting the name of the binaries

Since there are 2 or 3 binaries, 2 of which have a name, unique to the project, we have provided variables that you can use to reference the current project:

1. UntitledImGuiFramework - There is no variable for the framework. You can just use the name UntitledImGuiFramework
2. Application library - ${APP_LIB_TARGET}
3. Application executable - ${APP_TARGET}

Adding additional sources

We provide variables for providing custom headers and source files to any of the 3 binaries. They are the following:

1. Framework:
   • Headers: ${UIMGUI_CUSTOM_FRAMEWORK_HEADERS}
   • Sources: ${UIMGUI_CUSTOM_FRAMEWORK_SOURCES}
2. Application library:
   • Headers: ${UIMGUI_CUSTOM_APP_HEADERS}
   • Sources: ${UIMGUI_CUSTOM_APP_SOURCES}
3. Application executable:
   • Sources: ${UIMGUI_CUSTOM_EXEC_SOURCES}

You can simply append a list of files to any of these variables in variable ways. For, example you can recursively get all source and header files, like this:

file(GLOB_RECURSE UIMGUI_CUSTOM_APP_SOURCES "MyLibrary/src/*.cpp")
file(GLOB_RECURSE UIMGUI_CUSTOM_APP_HEADERS "MyLibrary/include/*.hpp")

Custom compilation and setup steps

There are 2 callback functions that are provided as part of the template. They can be used to properly set up certain parts of the project, since CMake functions are not position-independent.

The custom_setup_step callback

The custom_setup_step callback is called after all modules and framework libraries are set up. Here, you can do calls to functions, such as add_subdirectory

The custom_compile_step callback

The custom_compile_step callback is added after binaries are added for compilation and all modules and framework libraries' defines are set up.

Here you can add additional compiler definitions, linker options and link libraries to all targets.

Utility function

You can use the following utility functions to make life easier.

The multicast function

The multicast function takes a function name and a variadic arguments list, then calls the function for all targets, given that the current platform supports the given target(application libraries are not supported on Windows). For example, instead of writing:

target_link_options(UntitledImGuiFramework PRIVATE -fwasm-exceptions -sSUPPORT_LONGJMP=wasm)
if (NOT WIN32)
    target_link_options(${APP_LIB_TARGET} PRIVATE -fwasm-exceptions -sSUPPORT_LONGJMP=wasm)
endif()
target_link_options(${APP_TARGET} PRIVATE -fwasm-exceptions -sSUPPORT_LONGJMP=wasm)

You can do a single call to multicast, like this:

multicast(target_link_options PRIVATE -fwasm-exceptions -sSUPPORT_LONGJMP=wasm)