Getting started » Usage with CMake

Guide how to find and use Magnum with the CMake buildsystem.

Magnum uses CMake as a primary build system for both building and integration into your projects. The following guide explains how to use it. If you wish to use a different buildsystem, see Using Magnum with custom buildsystems instead.

Using Magnum that was externally built and installed

The main logic is in the FindMagnum.cmake module distributed with the engine in the 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:

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

find_package(Magnum REQUIRED ...) # see below

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. 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 as a CMake subproject

A self-contained alternative to a shared instance of the libraries, is to add the repositories directly into your project (as Git submodules, bundling downloaded archives etc.), and then to use CMake's add_subdirectory() command to compile them on demand. With this approach, you don't need to care about manually installing Magnum and Corrade, however the usual tradeoffs when bundling code apply — slower full rebuilds, IDEs having more to parse etc. In this case, build-time options can be set() before calling add_subdirectory(). Note that, unless you require CMake 3.13 at least, it's necessary to use the CACHE ... FORCE arguments in order to have the options set properly. For example:

add_subdirectory(corrade EXCLUDE_FROM_ALL) # so only things you use are built

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

find_package(Magnum REQUIRED ...) # see below

Note that the use of add_subdirectory() does not replace the configuration necessary for an installed version of Magnum. The modules/ directory and calls to find_package() are needed in both the installed and the subproject case for a properly configured environment.

To simplify your project setup, the subproject globally configures CMAKE_RUNTIME_OUTPUT_DIRECTORY and friends to <CONFIG>/bin / <CONFIG>/lib directories inside your build directory. This makes the subproject workflow easier when dynamically-loaded plugins are involved; and on Windows it makes it possible to run built executables without having to do a $PATH setup for dependency DLLs. If your project already configures CMAKE_{RUNTIME,LIBRARY,ARCHIVE}_OUTPUT_DIRECTORY, those will get used instead (and you can also set your own output directories after the add_subdirectory() call, which will make Magnum keep the above). If you want to disable this behavior altogether and keep all executables and libraries in their implicit locations, set those variables to an empty string (as opposed to nothing at all, which is the same as if the variable is not set) — Magnum will detect and respect that:

# I'm happy with having binaries scattered around the build dir
set(CMAKE_RUNTIME_OUTPUT_DIRECTORY "")
set(CMAKE_LIBRARY_OUTPUT_DIRECTORY "")
set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY "")

add_subdirectory(corrade EXCLUDE_FROM_ALL)
add_subdirectory(magnum EXCLUDE_FROM_ALL)

Please note that in case of the (by default) dynamic plugins, because these are loaded at runtime, CMake doesn't know we need them to be built — one option is to list them explicitly like shown below, another (but uglier) is to not use EXCLUDE_FROM_ALL on the magnum subdirectory, so everything is always built implicitly.

set(MAGNUM_WITH_ANYIMAGEIMPORTER ON CACHE BOOL "" FORCE)
set(MAGNUM_WITH_ANYSCENEIMPORTER ON CACHE BOOL "" FORCE)
add_subdirectory(magnum EXCLUDE_FROM_ALL)

# So the AnyImageImporter / AnySceneImporter gets built implicitly
add_dependencies(your-app
    Magnum::AnyImageImporter
    Magnum::AnySceneImporter)

Each namespace, plugin and application class provides further information about additional steps needed for a CMake subproject setup.

Finding the package and its components

Basic usage is:

find_package(Magnum REQUIRED)

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

  • Magnum_FOUND — Whether the library was found
  • Magnum::Magnum — Base library imported target
  • MAGNUM_DEPLOY_PREFIX — Prefix where to put final application executables, defaults to .. If a relative path is used, it's relative to CMAKE_INSTALL_PREFIX.
  • MAGNUM_INCLUDE_INSTALL_PREFIX — Prefix where to put platform-independent include and other files, defaults to .. If a relative path is used, it's relative to CMAKE_INSTALL_PREFIX.
  • MAGNUM_PLUGINS_DEBUG_DIR — Base directory with dynamic plugins for debug builds. Empty by default, which means the directory is autodetected based on library and executable location; override if needed.
  • MAGNUM_PLUGINS_RELEASE_DIR — Base directory with dynamic plugins for release builds. Empty by default, which means the directory is autodetected based on library and executable location; override if needed.
  • MAGNUM_PLUGINS_DIR — Base directory with dynamic plugins, defaults to MAGNUM_PLUGINS_RELEASE_DIR in release builds and multi-configuration builds or to MAGNUM_PLUGINS_DEBUG_DIR in debug builds.
  • MAGNUM_PLUGINS_FONT[|_DEBUG|_RELEASE]_DIR — Directory with dynamic font plugins
  • MAGNUM_PLUGINS_FONTCONVERTER[|_DEBUG|_RELEASE]_DIR — Directory with dynamic font converter plugins
  • MAGNUM_PLUGINS_IMAGECONVERTER[|_DEBUG|_RELEASE]_DIR — Directory with dynamic image converter plugins
  • MAGNUM_PLUGINS_IMPORTER[|_DEBUG|_RELEASE]_DIR — Directory with dynamic importer plugins
  • MAGNUM_PLUGINS_AUDIOIMPORTER[|_DEBUG|_RELEASE]_DIR — Directory with dynamic audio importer plugins

If Magnum is built for Emscripten, the following variables contain paths to various support files — see JavaScript, HTML5 and WebGL for more information about each file:

  • MAGNUM_EMSCRIPTENAPPLICATION_JS — Path to the EmscriptenApplication.js file
  • MAGNUM_WINDOWLESSEMSCRIPTENAPPLICATION_JS — Path to the WindowlessEmscriptenApplication.js file
  • MAGNUM_WEBAPPLICATION_CSS — Path to the WebApplication.css file

However, this command will try to find only the base library, not the optional components. The base library depends on Using Corrade with CMake 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):

  • CglContext — CGL context
  • EglContext — EGL context
  • GlxContext — GLX context
  • WglContext — WGL context

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 Trade MeshTools Primitives Sdl2Application)

For each component is then defined:

  • Magnum_*_FOUND — Whether the component was found
  • Magnum::* — Component imported target

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::GLContext.

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 a preprocessing step instead.

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

  • MAGNUM_BUILD_DEPRECATED — Defined if compiled with deprecated features included
  • MAGNUM_BUILD_STATIC — Defined if compiled as static libraries. Default are shared libraries.
  • MAGNUM_BUILD_STATIC_UNIQUE_GLOBALS — Defined if static libraries keep their globals unique even across different shared libraries. Enabled by default for static builds.
  • MAGNUM_TARGET_GL — Defined if compiled with OpenGL interoperability enabled
  • MAGNUM_TARGET_GLES — Defined if compiled for OpenGL ES
  • MAGNUM_TARGET_WEBGL — Defined if compiled for WebGL
  • MAGNUM_TARGET_GLES2 — Defined if compiled for OpenGL ES 2.0 / WebGL 1 instead of OpenGL ES 3.0+ / WebGL 2
  • MAGNUM_TARGET_EGL — Defined if compiled for EGL instead of a platform-specific OpenGL support library such as CGL, EAGL, GLX or WGL.
  • MAGNUM_TARGET_VK — Defined if compiled with Vulkan interoperability enabled

The following variables are provided for backwards compatibility purposes only when MAGNUM_BUILD_DEPRECATED is defined and will be removed in a future release:

  • MAGNUM_BUILD_MULTITHREADED — Alias to CORRADE_BUILD_MULTITHREADED. Use CORRADE_BUILD_MULTITHREADED instead.
  • MAGNUM_TARGET_HEADLESS — Alias to MAGNUM_TARGET_EGL, unless on iOS, Android, Emscripten or Windows RT. Use MAGNUM_TARGET_EGL instead.
  • MAGNUM_TARGET_DESKTOP_GLES — Defined if compiled for OpenGL ES but GLX / WGL is used instead of EGL. Use MAGNUM_TARGET_EGL instead.
  • MAGNUM_TARGET_GLES3 — Defined if compiled for OpenGL ES 3.0+ / WebGL 2. Use an inverse of the MAGNUM_TARGET_GLES2 variable instead.

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.

« Downloading and building examples | Getting started | Plugin usage with CMake »