Getting started » Downloading and building

ArchLinux packages

Package for the latest stable release is maintained in the community repo. Installing is as simple as this:

sudo pacman -S magnum

In package/archlinux/magnum-git there is a package for Git development build. The package is also in AUR as magnum-git. It depends on the Corrade ArchLinux package.

There are also quite a few development packages for native builds, OpenGL ES builds, cross-compilation for Emscripten, Android and MinGW or various sanitizer/coverage builds. See the PKGBUILD files in the package/archlinux directory. They allow you to build and install the package directly from the source tree. Example usage:

git clone https://github.com/mosra/magnum && cd magnum
cd package/archlinux
makepkg -fp PKGBUILD # or any other PKGBUILD file

In most cases the development PKGBUILDs also contain a check() function which will run all unit tests before packaging. That might sometimes fail or take too long, pass --nocheck to makepkg to skip that.

Once built, install the package using pacman:

sudo pacman -U magnum-*.pkg.tar.zst

Edit the PKGBUILDs if you want to pass additional flags to CMake or enable / disable additional features.

There are also ArchLinux packages for Magnum Plugins, Magnum Extras, Magnum Integration and Magnum Examples.

MSYS2 packages

MSYS2 package for the latest stable release is maintained in the official repos. Installing is as simple as this:

pacman -S mingw-w64-x86_64-magnum # or mingw-w64-i686-magnum

Similarly to ArchLinux, there is one package in the package/msys/magnum directory, which will download and package latest stable release; and then a development PKGBUILD in package/msys, allowing you to package and install the currently checked out source tree. Both depend on a corresponding Corrade MSYS2 package. Example usage:

git clone https://github.com/mosra/magnum && cd magnum
cd package/msys
makepkg -fp PKGBUILD

The above works in a 32/64bit MinGW shell, from a MSYS shell the equivalent command is

makepkg-mingw -fp PKGBUILD

which will build both a 32bit and a 64bit version. See the MSYS2 Wiki for more information.

There are also MSYS2 packages for Magnum Plugins and Magnum Integration.

Packages for Debian, Ubuntu and derivatives

The package/debian/ directory contains all files needed for building Debian packages. You need the Corrade Debian package installed and in addition also the dpkg-dev and debhelper packages. Building is easy, just change directory to package root, link or copy package/debian directory there and run dpkg-buildpackage:

git clone https://github.com/mosra/magnum && cd magnum
ln -s package/debian .
dpkg-buildpackage --no-sign

This will compile binary and development packages, which will then appear in a parent directory. Install them using dpkg:

sudo dpkg -i ../magnum*.deb

If you want to pass additional flags to CMake or enable / disable additional features, add them to dh_auto_configure at the bottom of debian/rules. Watch out, as indentation has to be done using tabs, not spaces.

There are also Debian packages for Magnum Plugins, Magnum Extras, Magnum Integration and Magnum Examples.

Gentoo Linux ebuilds

Gentoo Git ebuild is available in the package/gentoo directory. Get the Corrade Gentoo package first and then build and install Magnum like this:

git clone https://github.com/mosra/magnum && cd magnum
cd package/gentoo
sudo ebuild dev-libs/magnum/magnum-9999.ebuild manifest clean merge

If you want to pass additional flags to CMake or enable / disable additional features, add them to mycmakeargs in the *.ebuild file.

There are also Gentoo packages for Magnum Plugins, Magnum Extras, Magnum Integration and Magnum Examples.

Packages for Fedora, openSUSE and other RPM-based Linux distributions

Spec files for RPM-based distributions are in the package/rpm/ directory. In addition you will need to install the following dependencies in order to build the packages (assuming Fedora Linux):

sudo dnf install fedora-packager rpmdevtools

After that, make sure you build and install the Corrade RPM package first and then run the build.sh script. Internally it queries the Git version, makes a tarball, may ask you to install appropriate dependencies if not present already, and then builds the package.

./package/rpm/build.sh

At the end, if everything succeeds, you'll have the newly built packages located in ~/rpmbuild/RPMS. The script will print their names at the end.

If you want to pass additional flags to CMake or enable / disable additional features, edit the *.spec file.

There are also RPM packages for Magnum Plugins, Magnum Extras, Magnum Integration and Magnum Examples.

Homebrew formulas for macOS

macOS Homebrew formulas building the latest Git revision are in the package/homebrew directory. Either use the *.rb files directly or use the tap at https://github.com/mosra/homebrew-magnum. This will install the latest stable version of Magnum with all its dependencies:

brew install mosra/magnum/magnum

But often you may want to install the latest Git revision of all Magnum projects instead:

brew install --HEAD mosra/magnum/corrade
brew install --HEAD mosra/magnum/magnum

# If already installed, use the following to upgrade, in the same order
brew upgrade --fetch-HEAD mosra/magnum/corrade
brew upgrade --fetch-HEAD mosra/magnum/magnum

When installing from the *.rb files you need to install the Corrade Homebrew package first. If you want to pass additional flags to CMake or enable / disable additional features, edit the *.rb file.

There are also Homebrew packages for Magnum Plugins, Magnum Extras, Magnum Integration and Magnum Examples.

CMake Package Manager / CPM

If you're using CPM, adding Magnum as a dependency can be done with the following, together with the Corrade CPM package. If you're fetching the master branch, it's recommended to disable GIT_SHALLOW to perform a full clone including all tags. If not, the build prints a warning about being unable to fetch a Git version for the version.h header, and will generate a fallback file instead.

CPMAddPackage(
    NAME corrade
    GIT_REPOSITORY https://github.com/mosra/corrade.git
    GIT_TAG master
    GIT_SHALLOW NO)

CPMAddPackage(
    NAME magnum
    GIT_REPOSITORY https://github.com/mosra/magnum.git
    GIT_TAG master
    GIT_SHALLOW NO)

You'll most likely want to enable / disable additional features, or perhaps pass additional flags to CMake, which can be done via OPTIONS. Note that certain features will require additional dependencies, see their documentation for more information.

CPMAddPackage(
    NAME magnum
    ...
    OPTIONS
        "MAGNUM_WITH_ANYIMAGEIMPORTER ON"
        "MAGNUM_WITH_SDL2APPLICATION ON")

CPM can be used also for Magnum Plugins, Magnum Extras and Magnum Integration.

Vcpkg package

Magnum is available as a Vcpkg package. After setting up Vcpkg as described in their README, it is recommended to set the "default triplet". You can do this by setting the VCPKG_DEFAULT_TRIPLET variable, e.g. to x64-windows — refer to the documentation on triplets for other options.

You can then install latest stable version of Magnum with all its dependencies like this:

vcpkg install magnum

Not all features are installed by default; only those that are implicitly enabled in Enabling or disabling features together with Sdl2Application. To opt-in or opt-out of additional features, you can use the following syntax; feature names are simply names of CMake MAGNUM_WITH_* options but lowercase, e.g.:

vcpkg install magnum[glfwapplication,tgaimporter]

To install all features of a package, use *, e.g.:

vcpkg install magnum[*]

For more information, see the documentation on feature packages.

Packages installed using Vcpkg can be used in Visual Studio straight away — all you need to do is to #include the headers you want and the buildsystem will do all needed library linking and setup behind the scenes automatically. (Cool, isn't it?)

In order to make Magnum projects installed using Vcpkg available to CMake-based projects, specify the Vcpkg toolchain file on the command line when invoking CMake in a fresh build directory, for example:

mkdir build && cd build
cmake .. -DCMAKE_TOOLCHAIN_FILE=C:/src/vcpkg/scripts/buildsystems/vcpkg.cmake

If you want Vcpkg to pass additional flags to CMake during installation of a package, use the edit command, e.g. vcpkg edit magnum, and edit OPTIONS in vcpkg_configure_cmake().

There is also a Vcpkg package for Magnum Plugins, Magnum Integration and Magnum Extras.

Hunter package

Starting from version 2019.01, stable releases of Magnum are available in the Hunter CMake-driven package manager. See the magnum package documentation for details.

Downloading the sources

The source is available on GitHub: https://github.com/mosra/magnum. Clone the repository with your favorite IDE or Git GUI, download currrent snapshot as a compressed archive or use the command line:

git clone https://github.com/mosra/magnum.git

Relevant information about CMake usage is described in Corrade download and installation guide, this guide is assuming you have at least basic knowledge of CMake.

Via command-line (on Linux/Unix)

On Unix-based OSes, the library (for example with support for SDL2 applications) can be built and installed using these four commands:

mkdir build && cd build
cmake .. \
    -DCMAKE_INSTALL_PREFIX=/usr \
    -DMAGNUM_WITH_SDL2APPLICATION=ON
make
make install # sudo may be needed

See below for additional configuration options.

If you have the dependencies installed in non-standard location (other than /usr, e.g. /home/xyz/projects), set CMAKE_PREFIX_PATH to that directory to help CMake find them. You can enter more different dirs if you separate them with semicolons. On CMake 3.12+ you can also use <PackageName>_ROOT variables to point to dependency-specific locations, e.g. -DCorrade_ROOT=/home/xyz/projects/corrade-install.

Also, if you plan to install the library to non-standard location, you might want to set CMAKE_INSTALL_RPATH to lib/ subdir of given prefix (e.g. /home/xyz/projects/lib), so the dynamic libraries can be found at runtime.

Building on Windows

On Windows you can use MSVC, clang-cl or the MinGW-w64 compiler. It's then up to you whether you will use QtCreator, Visual Studio or another IDE or do the build from a command line. Note that for most convenient usage it's best to use some dedicated directory (e.g. C:/Sys) for installing dependencies instead of putting each dependency to its own directory in C:/Program Files or elsewhere. Then you can just add its bin/ subdir (e.g. C:/Sys/bin) to %PATH% so all the DLLs are found when running the executables. If you are using MinGW-w64, the C:/MinGW directory is in most cases already prepared for exactly this.

Then, when running CMake, set CMAKE_PREFIX_PATH and CMAKE_INSTALL_PREFIX value to that directory (e.g. -DCMAKE_INSTALL_PREFIX=C:/Sys). If you have dependencies scattered across multiple locations, enter them into CMAKE_PREFIX_PATH separated with semicolons. On CMake 3.12+ you can also use <PackageName>_ROOT variables to point to dependency-specific locations, e.g. -DCorrade_ROOT=C:/projects/corrade-install.

mkdir build && cd build
cmake -DCMAKE_INSTALL_PREFIX="C:/Sys" ..
cmake --build .
cmake --build . --target install

Enabling or disabling features

By default the engine is built for desktop OpenGL. Using the TARGET_* CMake options you can target other platforms. Note that some features are available for desktop OpenGL only, see Functionality requiring desktop OpenGL.

• MAGNUM_TARGET_GL — Build libraries with OpenGL interoperability enabled. Enabled by default when MAGNUM_WITH_GL is enabled. Disabling this will cause other libraries to not depend on the GL library, but doesn't affect the GL library itself.
• MAGNUM_TARGET_GLES — Target OpenGL ES. Available only when MAGNUM_WITH_GL is enabled.
• MAGNUM_TARGET_GLES2 — Target OpenGL ES 2.0 instead of 3.0 and later. Available only when MAGNUM_WITH_GL is enabled. Currently enabled by default when MAGNUM_TARGET_GLES is set.
• MAGNUM_TARGET_EGL — Target EGL instead of a platform-specific OpenGL support library like CGL, EAGL, GLX or WGL. Enabled implicitly on Android, Emscripten and Windows RT, enabled by default when MAGNUM_TARGET_GLES is set unless on iOS. Available only when MAGNUM_WITH_GL is enabled.
• MAGNUM_TARGET_VK — Build libraries with Vulkan interoperability enabled. Enabled by default when MAGNUM_WITH_VK is enabled. Disabling this will cause libraries to not depend on the Vk library, but doesn't affect the Vk library itself.

By default the engine is built with nearly everything except the Audio and Vk libraries, plugins, command-line utilities and application libraries (see below). Using the following MAGNUM_WITH_* CMake options you can specify which parts will be built and which not:

• MAGNUM_WITH_AUDIO — Build the Audio library. Depends on OpenAL, not enabled by default.
• MAGNUM_WITH_DEBUGTOOLS — Build the DebugTools library.
• MAGNUM_WITH_GL — Build the GL library. Enabled automatically if MAGNUM_WITH_SHADERS is enabled.
• MAGNUM_WITH_MATERIALTOOLS — Build the MaterialTools library. Enables also building of the Trade library.
• MAGNUM_WITH_MESHTOOLS — Build the MeshTools library. Enables also building of the Trade library.
• MAGNUM_WITH_PRIMITIVES — Build the Primitives library. Enables also building of the Trade library.
• MAGNUM_WITH_SCENEGRAPH — Build the SceneGraph library
• MAGNUM_WITH_SCENETOOLS — Build the SceneTools library. Enables also building of the Trade library.
• MAGNUM_WITH_SHADERS — Build the Shaders library. Enables also building of the GL library.
• MAGNUM_WITH_SHADERTOOLS — Build the ShaderTools library
• MAGNUM_WITH_TEXT — Build the Text library. Enables also building of the TextureTools library.
• MAGNUM_WITH_TEXTURETOOLS — Build the TextureTools library. Enabled automatically if MAGNUM_WITH_TEXT or MAGNUM_WITH_DISTANCEFIELDCONVERTER is enabled.
• MAGNUM_WITH_TRADE — Build the Trade library. Enabled automatically if MAGNUM_WITH_MATERIALTOOLS, MAGNUM_WITH_MESHTOOLS, MAGNUM_WITH_PRIMITIVES or MAGNUM_WITH_SCENETOOLS is enabled.
• MAGNUM_WITH_VK — Build the Vk library. Depends on Vulkan, not enabled by default.

None of the application libraries is built by default (and you need at least one, unless you are handling platform integration yourself — see Using custom platform toolkits for more information). As they are rather tiny, they are always built as static. Choose the one that suits your requirements and your platform best. The Sdl2Application library is a good default choice, as it is the most portable — and if you're going to build any of the examples, you'll need it.

• MAGNUM_WITH_ANDROIDAPPLICATION — Build the AndroidApplication library. Available only on Android. Enables also building of the GL library.
• MAGNUM_WITH_EMSCRIPTENAPPLICATION — Build the EmscriptenApplication library. Available only on Emscripten.
• MAGNUM_WITH_GLFWAPPLICATION — Build the GlfwApplication library. Depends on GLFW.
• MAGNUM_WITH_GLXAPPLICATION — Build the GlxApplication library. Depends on X11. Requires MAGNUM_TARGET_GL to be enabled.
• MAGNUM_WITH_SDL2APPLICATION — Build the Sdl2Application library. Depends on SDL2.
• MAGNUM_WITH_XEGLAPPLICATION — Build the XEglApplication library. Enables also building of the GL library.
• MAGNUM_WITH_WINDOWLESSCGLAPPLICATION — Build the WindowlessCglApplication library. Requires MAGNUM_TARGET_GL to be enabled.
• MAGNUM_WITH_WINDOWLESSEGLAPPLICATION — Build the WindowlessEglApplication library. Requires MAGNUM_TARGET_GL to be enabled.
• MAGNUM_WITH_WINDOWLESSGLXAPPLICATION — Build the WindowlessGlxApplication library. Requires MAGNUM_TARGET_GL to be enabled.
• MAGNUM_WITH_WINDOWLESSIOSAPPLICATION — Build the WindowlessIosApplication library. Requires MAGNUM_TARGET_GL to be enabled.
• MAGNUM_WITH_WINDOWLESSWGLAPPLICATION — Build the WindowlessWglApplication library. Requires MAGNUM_TARGET_GL to be enabled.

None of the context libraries is built by default. Similarly to the application libraries, they are always built as static. You need them only if you chose to not use any of the application libraries above (see Using custom platform toolkits for more information):

• MAGNUM_WITH_CGLCONTEXT — Build the CGL context handling library. Requires MAGNUM_TARGET_GL to be enabled.
• MAGNUM_WITH_EGLCONTEXT — Build the EGL context handling library. Requires MAGNUM_TARGET_GL to be enabled.
• MAGNUM_WITH_GLXCONTEXT — Build the GLX context handling library. Requires MAGNUM_TARGET_GL to be enabled.
• MAGNUM_WITH_WGLCONTEXT — Build the WGL context handling library. Requires MAGNUM_TARGET_GL to be enabled.

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

• MAGNUM_WITH_OPENGLTESTER — The GL::OpenGLTester class. Requires MAGNUM_TARGET_GL to be enabled; enables building of one of the windowless application libraries based on the target platform.
• MAGNUM_WITH_VULKANTESTER — The Vk::VulkanTester class. Requires MAGNUM_TARGET_VK to be enabled.

Magnum also contains a set of dependency-less plugins for importing essential file formats. Additional plugins are provided in a separate plugin repository, see Downloading and building plugins for more information. None of the plugins is built by default.

• MAGNUM_WITH_ANYAUDIOIMPORTER — Build the AnyAudioImporter plugin. Enables also building of the Audio library.
• MAGNUM_WITH_ANYIMAGECONVERTER — Build the AnyImageConverter plugin. Enables also building of the Trade library.
• MAGNUM_WITH_ANYIMAGEIMPORTER — Build the AnyImageImporter plugin. Enables also building of the Trade library.
• MAGNUM_WITH_ANYSCENECONVERTER — Build the AnySceneConverter plugin. Enables also building of the Trade library.
• MAGNUM_WITH_ANYSCENEIMPORTER — Build the AnySceneImporter plugin. Enables also building of the Trade library.
• MAGNUM_WITH_ANYSHADERCONVERTER — Build the AnyShaderConverter plugin. Enables also building of the ShaderTools library.
• MAGNUM_WITH_MAGNUMFONT — Build the MagnumFont plugin. Enables also building of the Text library and the TgaImporter plugin. Requires MAGNUM_TARGET_GL to be enabled.
• MAGNUM_WITH_MAGNUMFONTCONVERTER — Build the MagnumFontConverter plugin. Enables also building of the Text library and the TgaImageConverter plugin.
• MAGNUM_WITH_OBJIMPORTER — Build the ObjImporter plugin. Enables also building of the Trade library.
• MAGNUM_WITH_TGAIMPORTER — Build the TgaImporter plugin. Enables also building of the Trade library.
• MAGNUM_WITH_TGAIMAGECONVERTER — Build the TgaImageConverter plugin. Enables also building of the Trade library.
• MAGNUM_WITH_WAVAUDIOIMPORTER — Build the WavAudioImporter plugin. Enables also building of the Audio library.

There are also a few command-line utilities, also all disabled by default:

• MAGNUM_WITH_GL_INFO — Build the magnum-gl-info executable, which provides information about the engine OpenGL capabilities. Requires MAGNUM_TARGET_GL to be enabled; enables also building of the GL library and one of the windowless application libraries based on the target platform.
• MAGNUM_WITH_VK_INFO — Build the magnum-vk-info executable, which provides information about the engine Vulkan capabilities. Requires MAGNUM_TARGET_VK to be enabled; enables also building of the Vk library.
• MAGNUM_WITH_AL_INFO — Build the magnum-al-info executable, which provides information about the engine OpenAL capabilities. Enables also building of the Audio library.
• MAGNUM_WITH_DISTANCEFIELDCONVERTER — Build the magnum-distancefieldconverter executable for converting black&white images to distance field textures. Available only on desktop GL. Requires MAGNUM_TARGET_GL to be enabled; enables also building of the TextureTools and GL libraries and one of the windowless application libraries based on the target platform.
• MAGNUM_WITH_FONTCONVERTER — Build the magnum-fontconverter executable for converting fonts of different formats. Available only on desktop GL. Requires MAGNUM_TARGET_GL to be enabled; enables also building of the Text and GL libraries and one of the windowless application libraries based on the target platform.
• MAGNUM_WITH_IMAGECONVERTER — Build the magnum-imageconverter executable for converting images of different formats. Enables also building of the Trade library.
• MAGNUM_WITH_SCENECONVERTER — Build the magnum-sceneconverter executable for converting scenes of different formats. Enables also building of the MeshTools and SceneTools library.
• MAGNUM_WITH_SHADERCONVERTER — Build the magnum-shaderconverter executable for converting scenes of different formats. Enables also building of the ShaderTools library.

Options controlling the build:

• MAGNUM_BUILD_STATIC — Build all libraries as static. Default is shared, except on platforms such as Android or Emscripten that don't support dynamic linking.
• MAGNUM_BUILD_STATIC_PIC — Build static libraries with position-independent code. Enabled by default when building static libraries, disable if you don't need this feature. On Emscripten this option is always off.
• MAGNUM_BUILD_STATIC_UNIQUE_GLOBALS — Build static libraries in a way that keeps their globals unique even across different shared libraries. Enabled by default for static builds. May introduce additional overhead on some platforms, disable if you will only link static libraries to one final executable and won't use any dynamic plugins.
• MAGNUM_BUILD_STATIC_UNIQUE_GLOBALS_DLL_NAME — Name of a DLL in which to search for unique globals symbols. By default, the main executable is searched, which works in most cases except when Corrade is only linked to a DLL, such as in Python modules. The name is expected to be just a filename without any path. Used only on Windows and only if MAGNUM_BUILD_STATIC_UNIQUE_GLOBALS is enabled.
• MAGNUM_BUILD_PLUGINS_STATIC — Build plugins as static. By default, plugins are built as dynamic. Independent of the MAGNUM_BUILD_STATIC option to allow having static libraries with dynamic plugins and vice versa. To some extent it's also possible to have only a subset of plugins built as static — set MAGNUM_<PLUGIN>_BUILD_STATIC for particular plugins to ON or OFF to override this option.
• MAGNUM_BUILD_DEPRECATED — Build with deprecated features included. Enabled by default to preserve backwards compatibility, disabling it forces you to update your code whenever there's a breaking change in the APIs or in library behavior. It's however recommended to have this option disabled when deploying a final application as it can result in smaller binaries.
• MAGNUM_DISTANCEFIELDCONVERTER_STATIC_PLUGINS, MAGNUM_FONTCONVERTER_STATIC_PLUGINS, MAGNUM_IMAGECONVERTER_STATIC_PLUGINS, MAGNUM_SCENECONVERTER_STATIC_PLUGINS and MAGNUM_SHADERCONVERTER_STATIC_PLUGINS — Static plugins to link to the magnum-distancefieldconverter, magnum-fontconverter, magnum-imageconverter, magnum-sceneconverter and magnum-shaderconverter utilities, respectively. Intended for use in scenarios where both MAGNUM_BUILD_STATIC and MAGNUM_BUILD_PLUGINS_STATIC is enabled, in which case these executables don't have a possibility to load dynamic plugins from a filesystem. Plugins from the Magnum Plugins repository (and elsewhere) can be linked if it's added as a CMake subproject. Expects a semicolon-separated list of existing CMake targets, for example Magnum::AnyImageImporter;MagnumPlugins::StbImageImporter.
• Additional options are inherited from the CORRADE_BUILD_MULTITHREADED, CORRADE_BUILD_CPU_RUNTIME_DISPATCH and CORRADE_CPU_USE_IFUNC options specified when building Corrade.

The features used can be conveniently detected in depending projects both in CMake and C++ sources, see Usage with CMake and Magnum/Magnum.h for more information. See also Using Corrade with CMake and Corrade/Corrade.h for related info for the Corrade library. Note that each namespace documentation, all Platform library documentation and the GL::OpenGLTester class documentation contain more detailed information about dependencies, availability on particular platform and also guide how to enable given library for building and how to use it with CMake.

This list covers only the core Magnum features, see also features offered by Corrade, Magnum Plugins, Magnum Integration, Magnum Extras and Magnum Examples.

Libraries and static plugins built in Debug configuration (e.g. with CMAKE_BUILD_TYPE set to Debug) have a -d suffix to make it possible to have both debug and release libraries installed alongside each other. Dynamic plugins in Debug configuration are installed to magnum-d subdirectory instead of magnum. Headers and other files are the same for both debug and release configurations. The library and plugin distinction is handled semi-automatically when using Magnum in depending projects, see Usage with CMake for more information.

Particular platforms have additional requirements when it comes to location of installed files. The following variables are supported:

• LIB_SUFFIX — Setting this variable to 64 can be used to tell CMake to install to lib64/ instead of lib/. In most cases this variable is autodetected, so you don't need to set it yourself. On Android, if CMAKE_INSTALL_PREFIX points to the NDK sysroot, it gets automatically set to /${CMAKE_ANDROID_ARCH_TRIPLE}/${CMAKE_SYSTEM_VERSION} to put the binaries to correct location for given architecture and API level version.
• MAGNUM_DEPLOY_PREFIX — Used on Emscripten to override location where web demos and utilities (such as Magnum GL Info) are installed, so you can have libraries installed to a system location and utilities to your webserver, for example. Defaults to .. If a relative path is used, it's relative to CMAKE_INSTALL_PREFIX.

The following variables are deprecated and provided only for backwards compatibility if MAGNUM_BUILD_DEPRECATED isn't disabled.

• MAGNUM_INCLUDE_INSTALL_PREFIX — Overrides location where platform-independent include files, CMake scripts and other files are installed. For NDK versions before r19, CMake on Android by default searched for binaries in <ndk>/platforms/android-<api>/arch-<arch>/usr based on target API and platform, but for headers in a central location at <ndk>/toolchains/llvm/prebuilt/<host>/sysroot/usr and this was used to handle that case. Nowadays please use NDK r19 and newer, with the unified sysroot layout. Defaults to .. If a relative path is used, it's relative to CMAKE_INSTALL_PREFIX.
• MAGNUM_TARGET_HEADLESS — Alias to MAGNUM_TARGET_EGL.
• MAGNUM_TARGET_DESKTOP_GLES — Inverse of MAGNUM_TARGET_EGL if MAGNUM_TARGET_GLES is enabled.

Various plugin interfaces search for plugins in locations and order documented in Corrade::PluginManager::implicitPluginSearchPaths(), Trade::AbstractImporter::pluginSearchPaths() and equivalent functions in other plugin interfaces. In most cases the implicit behavior does the right thing, but if you need to override those, use the MAGNUM_PLUGINS_DIR, MAGNUM_PLUGINS_DEBUG_DIR and MAGNUM_PLUGINS_RELEASE_DIR CMake variables. Those are empty by default, which means no hardcoded path is used. Another option is supplying the plugin search path to the Corrade::PluginManager::Manager constructor either using the same CMake variables (passed through to preprocessor, see Usage with CMake) or via any other means. All builtin Magnum utilities such as Image conversion utility also provide a way to override the plugin directory via the --plugin-dir command-line option.

Building and running tests

If you want to build also the tests (which are not built by default), enable MAGNUM_BUILD_TESTS in CMake. The tests use Corrade's TestSuite framework and can be run either manually (the binaries are located in Test/ subdirectories in the build directory) or using

ctest --output-on-failure

in the build directory. It's not needed to install anything anywhere to run the tests.

The Audio library has tests which require OpenAL to be able to create a context. That is the case on most platforms, so they are enabled by default. In case it's not possible to have OpenAL context (such as when running Emscripten tests under Node.js), you can disable building of them with MAGNUM_BUILD_AL_TESTS. The tests are suffixed with ALTest so they can be also selectively included/excluded when running CTest, e.g.:

ctest -E ALTest # run everything except tests requiring OpenAL context

Platforms which have windowless GL context creation implemented (currently all platforms except Emscripten, Windows RT and Android) can build also tests for OpenGL functionality. You can enable them with MAGNUM_BUILD_GL_TESTS. All GL tests are suffixed with GLTest so they can be also selectively included/excluded when running CTest, e.g.:

ctest -R GLTest # run only tests requiring OpenGL context

Tests requiring Vulkan to work are also disabled by default, enable them with MAGNUM_BUILD_VK_TESTS.

By default the tests are compiled as part of the implicit ALL target. Use the CORRADE_TESTSUITE_TEST_TARGET CMake variable to create a dedicated target for building just the tests. See the documentation of the corrade_add_test() CMake macro for more information.

Cross-compiling for UWP / Windows RT

As said above, you need a native build of the corrade-rc executable and Corrade built for Windows RT. The below script assumes that native Corrade build is installed in C:/Sys and the installation path for WinRT dependencies is in C:/Sys-winrt.

You need at least Windows 8.1, Visual Studio 2015 and Windows 8.1 Store/Phone SDK installed. Windows RT applications support OpenGL only through ANGLE, which is currently limited to OpenGL ES. Download and build ANGLE according to the instructions above, but use project files from the winrt/ directory instead. Starting with version 2.0.4, SDL has support for WinRT applications — download the source from https://www.libsdl.org/download-2.0.php and use project files from the VisualC-WinRT directory. Because WinRT applications run in a sandbox, it's recommended to build the library as static so you don't have to bundle all the DLLs. Example is below:

mkdir build-winrt && cd build-winrt
cmake .. ^
    -DCMAKE_SYSTEM_NAME=WindowsStore ^
    -DCMAKE_SYSTEM_VERSION=10 ^
    -DCMAKE_INSTALL_PREFIX="C:/Sys-winrt" ^
    -DMAGNUM_BUILD_STATIC=ON ^
    -DMAGNUM_WITH_SDL2APPLICATION=ON ^
    -G "Visual Studio 14 2015" ..
cmake --build .

Change WindowsStore to WindowsPhone if you want to build for Windows Phone instead. When done, you can install the package using cmake --build . --target install to make it available to depending projects.

Cross-compiling for Windows using MinGW-w64

You will need a MinGW-w64 version of the compiler, i.e. the mingw-w64-gcc ArchLinux package, and also Corrade built for MinGW.

Create build directories for 32b/64b build and run cmake and the build command in them. You may need to modify the basic-mingw-w64-32.cmake / basic-mingw-w64-64.cmake files and CMAKE_INSTALL_PREFIX to suit your distribution filesystem hierarchy and also specify path where Corrade is installed in CMAKE_PREFIX_PATH.

mkdir build-mingw-w64-32 && cd build-mingw-w64-32
cmake .. \
    -DCMAKE_TOOLCHAIN_FILE=../toolchains/archlinux/basic-mingw-w64-32.cmake \
    -DCMAKE_INSTALL_PREFIX=/usr/i686-w64-mingw32
cmake --build .

mkdir build-mingw-w64-64 && cd build-mingw-w64-64
cmake .. \
    -DCMAKE_TOOLCHAIN_FILE=../toolchains/archlinux/basic-mingw-w64-64.cmake \
    -DCMAKE_INSTALL_PREFIX=/usr/x86_64-w64-mingw32
cmake --build .

Then you can install the package using cmake --build . --target install to make it available to depending projects.

Cross-compiling for Emscripten

You will need Emscripten installed and configured and Corrade built for Emscripten. The toolchains require CMake 3.7 or newer to properly set compiler and linker flags. If you are on Windows, this blog post may be helpful.

There are two toolchain files. The generic/Emscripten.cmake is for the classical (asm.js) build, the generic/Emscripten-wasm.cmake is for a WebAssembly build. Don't forget to adapt EMSCRIPTEN_PREFIX variable in generic/Emscripten*.cmake to path where Emscripten is installed; you can also pass it explicitly on command-line using -DEMSCRIPTEN_PREFIX. Default is /usr/lib/emscripten. Emscripten supports dynamic libraries only to simplify porting and they are generally slower, thus MAGNUM_BUILD_STATIC is implicitly enabled.

Then create build directory and run cmake and the build command in it. You can omit specifying CORRADE_RC_EXECUTABLE if natively-built corrade-rc is accessible through PATH.

WebGL 1.0 (GLES 2.0 equivalent) is enabled by default, switch to 2.0 (GLES 3.0 equivalent) by disabling MAGNUM_TARGET_GLES2. If you enable one of the Magnum GL Info or Magnum OpenAL Info utilities, you can override their install location by setting MAGNUM_DEPLOY_PREFIX — putting them for example in your webserver root.

mkdir build-emscripten && cd build-emscripten
cmake .. \
    -DCMAKE_TOOLCHAIN_FILE="../toolchains/generic/Emscripten.cmake" \
    -DCMAKE_BUILD_TYPE=Release \
    -DCMAKE_PREFIX_PATH=/usr/lib/emscripten/system \
    -DCMAKE_INSTALL_PREFIX=/usr/lib/emscripten/system \
    -DCORRADE_RC_EXECUTABLE=/path/to/corrade-rc \
    -DMAGNUM_DEPLOY_PREFIX=/srv/http/magnum \
    -DMAGNUM_WITH_SDL2APPLICATION=ON
cmake --build .

Then you can install the library using cmake --build . --target install to make it available to depending projects.

If you have Node.js installed, you can also build and run unit tests using ctest. See the MAGNUM_BUILD_TESTS option above.

For ArchLinux there are also prepared package files in package/archlinux, named PKGBUILD-emscripten, PKGBUILD-emscripten-webgl2, PKGBUILD-emscripten-noopt, PKGBUILD-emscripten-noopt-webgl2, PKGBUILD-emscripten-wasm and PKGBUILD-emscripten-wasm-webgl2, see above for more information. The first two are for WebGL 1 / WebGL 2 optimized asm.js build (slow to compile), the second for unoptimized build (faster to compile) and the third for WebAssembly build.

Cross-compiling for iOS

You will need macOS with Xcode installed.

Set CMAKE_OSX_ROOT to the SDK you want to target and enable all desired architectures in CMAKE_OSX_ARCHITECTURES. Be sure to set CMAKE_INSTALL_PREFIX to prefix where you store other iOS dependencies such as Corrade built for iOS or a SDL2 iOS build. You can omit specifying CORRADE_RC_EXECUTABLE if natively-built corrade-rc is accessible through PATH.

As every application is in its own sandbox, it doesn't make sense to build shared libraries (although it is supported). Enable MAGNUM_BUILD_STATIC to build static libraries. Dynamically loaded plugins are not supported on iOS at the moment, thus MAGNUM_BUILD_PLUGINS_STATIC is implicitly enabled. OpenGL ES 2.0 is enabled by default, switch to 3.0 by disabling MAGNUM_TARGET_GLES2.

mkdir build-ios && cd build-ios
cmake .. \
    -DCMAKE_TOOLCHAIN_FILE=../toolchains/generic/iOS.cmake \
    -DCMAKE_OSX_SYSROOT=/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk \
    -DCMAKE_OSX_ARCHITECTURES="arm64;armv7;armv7s" \
    -DCMAKE_INSTALL_PREFIX=~/ios-libs \
    -DCORRADE_RC_EXECUTABLE=/path/to/corrade-rc \
    -DMAGNUM_BUILD_STATIC=ON \
    -DMAGNUM_BUILD_PLUGINS_STATIC=ON \
    -DMAGNUM_TARGET_GLES2=OFF \
    -DMAGNUM_WITH_SDL2APPLICATION=ON \
    -G Xcode
cmake --build .

Then you can install the library using cmake --build . --target install to make it available to depending projects.

Cross-compiling for Android

You will need Android NDK installed and configured and Corrade built for Android. The guide assumes NDK r19+ with unified Clang toolchain, which in turn requires at least CMake 3.16.

Create a build directory and run cmake and the build command in it. Set CMAKE_SYSTEM_NAME to Android to enable the cross-compilation, CMAKE_ANDROID_STL_TYPE to use libc++, CMAKE_SYSTEM_VERSION to minimal API version level you wish to use and CMAKE_ANDROID_ARCH_ABI to target platform ABI. Check the CMake Android cross-compiling documentation for further information. You can omit specifying CORRADE_RC_EXECUTABLE if natively-built corrade-rc is accessible through PATH. Note that MAGNUM_BUILD_STATIC is implicitly enabled, because manually loading all depending shared libraries using JNI would be too inconvenient. The engine is built for OpenGL ES 2.0 by default, switch to 3.0 by disabling MAGNUM_TARGET_GLES2.

If you set CMAKE_INSTALL_PREFIX to /usr subdirectory of the particular Android platform sysroot (as shown below), Magnum's buildsystem will also pick a LIB_SUFFIX corresponding to a particular ABI and version, which in turn makes the package automatically discoverable when compiling depending projects, both with vanilla CMake and with Gradle. Another option is to explicitly set CMAKE_PREFIX_PATH to the install location in depending projects.

mkdir build-android-arm64 && cd build-android-arm64
cmake .. \
    -DCMAKE_SYSTEM_NAME=Android \
    -DCMAKE_SYSTEM_VERSION=24 \
    -DCMAKE_ANDROID_ARCH_ABI=arm64-v8a \
    -DCMAKE_ANDROID_STL_TYPE=c++_static \
    -DCMAKE_BUILD_TYPE=Release \
    -DCMAKE_INSTALL_PREFIX=/opt/android-ndk/toolchains/llvm/prebuilt/linux-x86_64/sysroot/usr \
    -DCMAKE_FIND_ROOT_PATH=/opt/android-ndk/toolchains/llvm/prebuilt/linux-x86_64/sysroot \
    -DCMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX=/aarch64-linux-android/24 \
    -DCORRADE_RC_EXECUTABLE=/path/to/corrade-rc \
    -DMAGNUM_TARGET_GLES2=OFF \
    -DMAGNUM_WITH_ANDROIDAPPLICATION=ON
cmake --build .

Then you can install the library using cmake --build . --target install to make it available to depending projects.

For ArchLinux there is also a prepared package file in package/archlinux/, named PKGBUILD-android-arm64; see above for more information.

CircleCI

In package/ci/ there is a circle.yml file with Linux GCC 4.8, Linux ARM64, macOS, Linux desktop GLES2/GLES3, Emscripten WebGL1/WebGL2, AddressSanitizer, ThreadSanitizer, Android x86 GLES2/GLES3/Vulkan and iOS x86_64 GLES3 configuration. Online at https://circleci.com/gh/mosra/magnum.

AppVeyor

In package/ci/ there is an appveyor.yml file with Windows desktop MSVC, clang-cl, MinGW, Windows desktop GLES2/GLES3 and Windows RT GLES3 configuration. Online at https://ci.appveyor.com/project/mosra/magnum.

Codecov.io

Linux, Linux GLES, macOS and Windows MinGW builds contribute to a combined code coverage report, available online at https://codecov.io/gh/mosra/magnum.