Usage with CMake

Table of Contents

Guide how to find and use Magnum with CMake build system

Magnum uses CMake build system for both building and integration into your projects. The logic is in module FindMagnum.cmake distributed with the engine in modules/ directory, you are encouraged to copy it along with FindCorrade.cmake into your project and add path to the files to CMAKE_MODULE_PATH. Otherwise, if CMake won't be able to find this file in predefined locations, it will error out even if Magnum might be installed on the system. If you plan to use Magnum on OpenGL ES, you may also need FindOpenGLES2.cmake or FindOpenGLES3.cmake and in some cases also FindEGL.cmake.

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.

Basic usage is:

find_package(Magnum REQUIRED)

This module tries to find base Magnum library and then defines:

However, this command will try to find only the base library, not the optional components. The base library depends on Corrade and OpenGL libraries (or OpenGL ES libraries). Additional dependencies are specified by the components. The optional components are:

Platform namespace is split into more components:

For manual context creation (without application wrappers) there are also platform-specific context libraries (see Using custom platform toolkits for more information):

There are also extensions to Corrade::TestSuite::Tester for testing GPU code:

The library also contains a set of plugins for importing essential file formats. Additional plugins are provided in separate plugin repository, see Plugin usage with CMake for more information. If you are going to use dynamic plugins (the default) via plugin manager, they don't need to be handled via CMake. The manager will look for them at runtime at specified location and loads them dynamically. However, if they are built as static (see Downloading and building plugins for more information), they need to be linked into the executable and then explicitly imported. Also if you are going to use them as dependencies, you need to find the dependency and then link to it.

Lastly, a few utility executables are available:

Note that each namespace, all Platform libraries and each plugin class contain 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(Magnum REQUIRED MeshTools Primitives Sdl2Application)

For each component is then defined:

If exactly one *Application or exactly one Windowless*Application component is requested and found, its target is available in convenience alias Magnum::Application / Magnum::WindowlessApplication to simplify porting. Similarly, if exactly one *Context component is requested and found, its target is available in convenience alias Magnum::Context.

The package is found if either debug or release version of each requested library (or plugin) is found. If both debug and release libraries (or plugins) 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). Note that this autodetection might fail for the MAGNUM_PLUGINS_DIR variable, especially on multi-configuration build systems. You can make use of CORRADE_IS_DEBUG_BUILD preprocessor variable along with MAGNUM_PLUGINS_*_DEBUG_DIR / MAGNUM_PLUGINS_*_RELEASE_DIR variables to decide in preprocessing step.

Features of found Magnum library are exposed in these CMake variables, they are also available as preprocessor variables if including Magnum/Magnum.h:

Workflows without imported targets are deprecated and the following variables are included just for backwards compatibility and only if MAGNUM_BUILD_DEPRECATED is enabled:

Corrade library provides also its own set of CMake macros and variables, see its documentation for more information. Plugins repository, Integration repository and Extras repository have also their own CMake modules.

Other CMake modules

The modules/ directory contains more useful CMake modules:

See also relevant section for Corrade, Plugins, Integration and Extras projects.