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.
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. 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
FindOpenGLES3.cmake and in some cases also
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
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:
This module tries to find base Magnum library and then defines:
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
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
MAGNUM_PLUGINS_DEBUG_DIR— Base directory with dynamic plugins for debug builds, defaults to
magnum-d/subdirectory of dir where Magnum library was found
MAGNUM_PLUGINS_RELEASE_DIR— Base directory with dynamic plugins for release builds, defaults to
magnum/subdirectory of dir where Magnum library was found
MAGNUM_PLUGINS_DIR— Base directory with dynamic plugins, defaults to
MAGNUM_PLUGINS_RELEASE_DIRin release builds and multi-configuration builds or to
MAGNUM_PLUGINS_DEBUG_DIRin debug builds. You can modify all three variable (e.g. set them to
.when deploying on Windows with plugins stored relatively to the executable), the following
MAGNUM_PLUGINS_*_DIRvariables depend on it.
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
MAGNUM_EMSCRIPTENAPPLICATION_JS— Path to the
MAGNUM_WINDOWLESSEMSCRIPTENAPPLICATION_JS— Path to the
MAGNUM_WEBAPPLICATION_CSS— Path to the
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:
Audio— Audio library
DebugTools— DebugTools library
GL– GL library
MeshTools— MeshTools library
Primitives— Primitives library
SceneGraph— SceneGraph library
Shaders— Shaders library
Shapesdeprecated — Shapes library
Text— Text library
TextureTools— TextureTools library
Trade— Trade library
Vk— Vk library
Platform namespace is split into more components:
GlutApplicationdeprecated — GlutApplication
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::
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.
AnyAudioImporter— AnyAudioImporter plugin
AnyImageConverter— AnyImageConverter plugin
AnyImageImporter— AnyImageImporter plugin
AnySceneImporter— AnySceneImporter plugin
MagnumFont— MagnumFont plugin
MagnumFontConverter— MagnumFontConverter plugin
ObjImporter— ObjImporter plugin
TgaImageConverter— TgaImageConverter plugin
TgaImporter— TgaImporter plugin
WavAudioImporter— WavAudioImporter plugin
Lastly, a few utility executables are available:
distancefieldconverter— magnum-distancefieldconverter executable
fontconverter— magnum-fontconverter executable
imageconverter— magnum-imageconverter executable
gl-info— magnum-gl-info executable
al-info— magnum-al-info executable
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::WindowlessApplication to simplify porting. Similarly, if exactly one
*Context component is requested and found, its target is available in convenience alias
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_
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_BUILD_DEPRECATED— Defined if compiled with deprecated APIs included
MAGNUM_BUILD_STATIC— Defined if compiled as static libraries. Default are shared libraries.
MAGNUM_BUILD_MULTITHREADED— Defined if compiled in a way that allows having multiple thread-local Magnum contexts. The default.
MAGNUM_TARGET_GL— Defined if compiled with OpenGL interoperability enabled
MAGNUM_TARGET_GLES— Defined if compiled for OpenGL ES
MAGNUM_TARGET_GLES2— Defined if compiled for OpenGL ES 2.0
MAGNUM_TARGET_GLES3— Defined if compiled for OpenGL ES 3.0
MAGNUM_TARGET_DESKTOP_GLES— Defined if compiled with OpenGL ES emulation on desktop OpenGL
MAGNUM_TARGET_WEBGL— Defined if compiled for WebGL
MAGNUM_TARGET_HEADLESS— Defined if compiled for headless machines. See MAGNUM_
TARGET_ HEADLESS documentation for more information.
MAGNUM_TARGET_VK— Defined if compiled with Vulkan interoperability enabled
Workflows without imported targets are deprecated and the following variables are included just for backwards compatibility and only if MAGNUM_
MAGNUM_LIBRARIES— Expands to
Magnum::Magnumtarget directly instead.
MAGNUM_*_LIBRARIES— Expands to
Magnum::*target directly instead.
MAGNUM_WINDOWLESSAPPLICATION_LIBRARIES— Expands to
Magnum::WindowlessApplicationtarget directly instead.
MAGNUM_CONTEXT_LIBRARIES— Expands to
Magnum::Contexttarget directly 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.
modules/ directory contains more useful CMake modules:
FindOpenAL.cmake— CMake module for finding OpenAL. This is a forked version of the upstream module that works properly with Emscripten. Copy this to your module directory if you want to use the Audio library on Emscripten.
FindGLFW.cmake— CMake module for finding GLFW. Copy this to your module directory if you want to use Platform::
FindEGL.cmake— CMake module for finding EGL. Copy this to your module directory if you want to target embedded platforms such as iOS, Android, Windows RT or Emscripten or if you want to use EGL instead of GLX/WGL/CGL on a desktop platform.
FindOpenGLES3.cmake— CMake module for finding OpenGL ES 2.0 / 3.0 library. Copy this to your module directory if you want to target OpenGL ES.
FindSDL2.cmake— CMake module for finding SDL 2. Copy this to your module directory if you want to use Platform::