Getting started » Integration library usage with CMake

Guide how to find and use Magnum integration libraries with CMake build system.

Using Magnum Integration that was externally built and installed

The main logic is in the FindMagnumIntegration.cmake module distributed in the modules/ directory of the integration repository, you are encouraged to copy it into your project and add path to the files to CMAKE_MODULE_PATH:

# Path where FindMagnumIntegration.cmake can be found, adapt as needed
set(CMAKE_MODULE_PATH "${PROJECT_SOURCE_DIR}/modules/" ${CMAKE_MODULE_PATH})

Otherwise, if CMake won't be able to find this file in predefined locations, it will error out even if Magnum Integration might be installed on the system. There are other Find modules that you might need for particular features or platforms, see the list below. Each library that needs one of the extra modules also mentions the requirement in its documentation. Note that the module files are updated as the library evolves, you are encouraged to update your copies from time to time to avoid strange building issues.

If you installed the library or its dependencies to non-standard location (other than /usr, e.g. /home/xyz/projects), set CMAKE_PREFIX_PATH to that directory to help CMake find it. You can enter more different dirs if you separate them with semicolons.

Using Magnum Integration as a CMake subproject

Continuing from Using Magnum as a CMake subproject, adding Magnum Integration is very similar. Again, the Integration build-time options have to be specified before the subdirectory gets added:

...

set(MAGNUM_WITH_GLM ON CACHE BOOL "" FORCE) # enable what you need
add_subdirectory(magnum-integration EXCLUDE_FROM_ALL)

find_package(MagnumIntegration REQUIRED ...) # see below

Each *Integration namespace provides further information about additional steps needed for a CMake subproject setup.

Finding the package and its components

Basic usage is:

find_package(MagnumIntegration REQUIRED)

This command tries to find Magnum integration library and then defines:

MagnumIntegration_FOUND — Whether the library was found

This command alone is useless without specifying the components:

Bullet — BulletIntegration library
Eigen — EigenIntegration library
Dart — DartIntegration library
Glm — GlmIntegration library
ImGui — ImGuiIntegration library
Ovr — OvrIntegration library

Note that each *Integration namespace contains more detailed information about dependencies, availability on particular platform and also guide how to enable given library in build and use it with CMake.

Example usage with specifying additional components is:

find_package(MagnumIntegration REQUIRED Bullet)

For each component is then defined:

MagnumIntegration_*_FOUND — Whether the component was found
MagnumIntegration::* — Component imported target

The package is found if either debug or release version of each requested library is found. If both debug and release libraries are found, proper version is chosen based on actual build configuration of the project (i.e. Debug build is linked to debug libraries, Release build to release libraries).

See also Magnum usage with CMake for more information.

Other CMake modules

The modules/ directory of Magnum Integration sources contains more useful CMake modules. If a library requires presence of any of these, it mentions them in its usage documentation.

FindGLM.cmake — CMake module for finding the GLM library. Copy this to your module directory if you want to use the GlmIntegration library.
FindOVR.cmake — CMake module for finding the OVR SDK. Copy this to your module directory if you want to use the OvrIntegration library.
FindImGui.cmake — CMake module for finding Dear ImGui. Copy this to your module directory if you want to use the ImGuiIntegration library.

« Plugin usage with CMake | Getting started | Extras library usage with CMake »