Getting started » Downloading and building

Guide how to download and build Magnum on different platforms.

Prepared packages

The easiest way to install Magnum is to use one of the ready-made packages for your platform of choice. See Manual build if you want to have more control and Cross-compiling for cross-compiling to other platforms.

The engine itself is kept as small as possible with only minimal dependencies. In order to use extra functionality, often depending on external libraries, you need to build also packages of additional repositories. Various importer plugins for image, audio and 3D model formats are maintained in the Plugins repository, integration with external math and physics libraries is provided by Integration libraries and other extra features are in the Extra libraries. Various examples are provided by the Example repository.

Vcpkg packages on Windows

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

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

vcpkg install --head corrade 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 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.

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 git://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.xz

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 Integration, Magnum Extras and Magnum Examples.

Packages for Debian, Ubuntu and derivatives

Prebuilt packages of the latest stable version for Ubuntu 14.04, 16.04 and 18.04 are available through a PPA. To install packages related to Magnum and Corrade, you can add the repository and then install the packages with the following commands:

sudo add-apt-repository ppa:chrome/magnum.graphics
sudo apt-get update
sudo apt-get install magnum magnum-dev

For more information about these packages, please visit the PPA page.

To build your own package, 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 git://github.com/mosra/magnum && cd magnum
ln -s package/debian .
dpkg-buildpackage

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 Integration, Magnum Extras 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 git://github.com/mosra/magnum && cd magnum
cd package/gentoo
sudo ebuild dev-libs/magnum/magnum-99999.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 Integration, Magnum Extras 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

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 Integration, Magnum Extras and Magnum Examples.

Manual build

Minimal set of tools and libraries required for building is:

  • C++ compiler with good C++11 support. Compilers which are tested to have everything needed are GCC >= 4.7, Clang >= 3.1 and MSVC >= 2015. On Windows you can also use MinGW-w64.
  • CMake >= 2.8.12
  • Corrade — Plugin management and utility library. See Corrade download and installation guide for more information.

Additional functionality is provided separately in Magnum Plugins, Magnum Integration, Magnum Extras and Magnum Examples.

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 git://github.com/mosra/magnum.git

Relevant information about CMake usage was 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 \
    -DWITH_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.

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 either MSVC or the MinGW-w64 compiler. It's then up to you whether you will use QtCreator, Visual Studio or anoother IDE or do the build from a command line. Note that for most convenient usage it's best 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).

Using Visual Studio

On Windows CMake by default creates Visual Studio project files.

The most straightforward way to build and install the library is again via the command line. The bonus point is that you don't even need to wait for Visual Studio to load:

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

If you want to build and install from Visual Studio, just open the Magnum.sln project file generated by CMake in the build directory.

Using QtCreator

On Windows, besides other IDEs, you can also use QtCreator (just QtCreator, you don't need the full Qt SDK). Configure it to use CMake and either the MSVC compiler or MinGW-w64 and then just open project's root CMakeLists.txt file within it. QtCreator then asks you where to create build directory, allows you to specify initial CMake parameters (e.g. CMAKE_PREFIX_PATH and CMAKE_INSTALL_PREFIX) and then you can just press Configure and everything is ready to be built.

After the initial import you might want to reconfigure some CMake variables, see below for more information.

Installation to given prefix can be done from within QtCreator by adding a new make install build rule.

Enabling or disabling features

The libraries are build as shared by default. If you are developing for a platform which doesn't support shared libraries or if you just want to link them statically, enable BUILD_STATIC to build the libraries as static. Building of static plugins is controlled with a separate BUILD_PLUGINS_STATIC variable. If you plan to use the static libraries and plugins with shared libraries later, enable also position-independent code with BUILD_STATIC_PIC. If you want to build with another compiler (e.g. Clang), pass -DCMAKE_CXX_COMPILER=clang++ to CMake.

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.
  • 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.
  • MAGNUM_INCLUDE_INSTALL_PREFIX — Used on Android to override location where platform-independent include files, CMake scripts and other files are installed. CMake on Android by default searches for binaries in <ndk>/platforms/android-<api>/arch-<arch>/usr based on target API and platform, but looks for headers in a central location at <ndk>/sysroot/usr. Defaults to .. If a relative path is used, it's relative to CMAKE_INSTALL_PREFIX.

The library is constantly evolving and thus some APIs are deprecated and then later removed in favor of better ones. To preserve backwards compatibility, Magnum is by default built with all deprecated APIs included. However, to make your code more robust and future-proof, it's recommended to build the library with BUILD_DEPRECATED disabled.

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.

  • TARGET_GL — Build libraries with OpenGL interoperability enabled. Enabled by default when 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.
  • TARGET_GLES — Target OpenGL ES. Available only when WITH_GL is enabled.
  • TARGET_GLES2 — Target OpenGL ES 2.0 instead of 3.0 and later. Available only when WITH_GL is set. Currently enabled by default when TARGET_GLES is set.
  • TARGET_DESKTOP_GLES — Target OpenGL ES on desktop, i.e. use OpenGL ES emulation in desktop OpenGL drivers. Available on Linux and Windows, though might not be supported by all drivers. Available only when WITH_GL is enabled.
  • TARGET_HEADLESS — Build command-line utilities for use on a headless machine. Basically it means that EGL with no display attachment is being used everywhere instead of platform-specific toolkits like CGL, GLX or WGL. Supported mainly on OpenGL ES drivers. Available only when WITH_GL is enabled.
  • TARGET_VK — Build libraries with Vulkan interoperability enabled. Enabled by default when 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 in a way that allows having multiple independent thread-local Magnum contents. This might cause some performance penalties — if you are sure that you will never need such feature, you can disable it via the BUILD_MULTITHREADED option.

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.

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

  • WITH_AUDIO — Build the Audio library. Depends on OpenAL, not built by default.
  • WITH_DEBUGTOOLS — Build the DebugTools library.
  • WITH_GL — Build the GL library. Enabled automatically if WITH_SHADERS or WITH_TEXT is enabled.
  • WITH_MESHTOOLS — Build the MeshTools library. Enables also building of the Trade library.
  • WITH_PRIMITIVES — Build the Primitives library. Enables also building of the Trade library.
  • WITH_SCENEGRAPH — Build the SceneGraph library. Enabled automatically if WITH_SHAPES is enabled.
  • WITH_SHADERS — Build the Shaders library. Enables also building of the GL library.
  • WITH_SHAPES deprecated — Build the Shapes library. Enables also building of the SceneGraph library.
  • WITH_TEXT — Build the Text library. Enables also building of the TextureTools and GL libraries.
  • WITH_TEXTURETOOLS — Build the TextureTools library. Enabled automatically if WITH_TEXT or WITH_DISTANCEFIELDCONVERTER is enabled.
  • WITH_TRADE — Build the Trade library.
  • WITH_VK — Build the Vk library

There are more involved component dependencies that are not described here (for example the DebugTools has some functionality that gets built only when SceneGraph is enabled, which then makes it dependent on Shaders and other things), but the CMake buildsystem takes care of these and only the relevant toggleable options are shown in CMake GUI or ccmake.

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.

  • WITH_ANDROIDAPPLICATION — Build the AndroidApplication library. Available only on Android. Enables also building of the GL library.
  • WITH_GLFWAPPLICATION — Build the GlfwApplication library. Depends on GLFW.
  • WITH_GLUTAPPLICATION deprecated — Build the GlutApplication library. Depends on GLUT. Enables also building of the GL library.
  • WITH_GLXAPPLICATION — Build the GlxApplication library. Depends on X11. Enables also building of the GL library.
  • WITH_SDL2APPLICATION — Build the Sdl2Application library. Depends on SDL2.
  • WITH_XEGLAPPLICATION — Build the XEglApplication library. Enables also building of the GL library.
  • WITH_WINDOWLESSCGLAPPLICATION — Build the WindowlessCglApplication library. Enables also building of the GL library.
  • WITH_WINDOWLESSEGLAPPLICATION — Build the WindowlessEglApplication library. Enables also building of the GL library.
  • WITH_WINDOWLESSGLXAPPLICATION — Build the WindowlessGlxApplication library. Enables also building of the GL library.
  • WITH_WINDOWLESSIOSAPPLICATION — Build the WindowlessIosApplication library. Enables also building of the GL library.
  • WITH_WINDOWLESSWGLAPPLICATION — Build the WindowlessWglApplication library. Enables also building of the GL library.
  • WITH_WINDOWLESSWINDOWSEGLAPPLICATION — Build the WindowlessWindowsEglApplication library. Enables also building of the GL library.

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):

  • WITH_CGLCONTEXT — Build the CGL context handling library. Enables also building of the GL library.
  • WITH_EGLCONTEXT — Build the EGL context handling library. Enables also building of the GL library.
  • WITH_GLXCONTEXT — Build the GLX context handling library. Enables also building of the GL library.
  • WITH_WGLCONTEXT — Build the WGL context handling library. Enables also building of the GL library.

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

  • WITH_OPENGLTESTER — The GL::OpenGLTester class. Enables also building of the GL library and one of the windowless application libraries based on the target platform.

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.

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

  • WITH_GL_INFO — Build the magnum-gl-info executable, which provides information about the engine OpenGL capabilities. Enables building of one of the windowless application libraries based on the target platform.
  • WITH_AL_INFO — Build the magnum-al-info executable, which provides information about the engine OpenAL capabilities.
  • WITH_DISTANCEFIELDCONVERTER — Build the magnum-distancefieldconverter executable for converting black&white images to distance field textures. Enables also building of the TextureTools library. Available only on desktop GL. Enables building of one of the windowless application libraries based on the target platform.
  • WITH_FONTCONVERTER — Build the magnum-fontconverter executable for converting fonts of different formats. Enables also building of the Text library. Available only on desktop GL. Enables building of one of the windowless application libraries based on the target platform.
  • WITH_IMAGECONVERTER — Build the magnum-imageconverter executable for converting images of different formats.

Some of these utilities operate with plugins and they search for them in the default plugin locations. You can override these locations using the MAGNUM_PLUGINS_DIR and MAGNUM_PLUGINS_[DEBUG|RELEASE]_DIR variables, much like when using Magnum from dependent projects — see Usage with CMake for more information. In particular, if you specify them as relative paths, the path will be taken relative to executable location, which is useful for making relocatable installations.

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.

Building and running tests

If you want to build also the tests (which are not built by default), enable 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. On Windows the tests require the library to be installed with DLLs accessible through %PATH%. See the above Windows documentation for more information.

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 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 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

Building documentation

The documentation (which you are currently reading) is written in Doxygen and additionally uses LaTeX for math formulas. Documentation using the stock HTML theme can be build by running

doxygen

in the root directory (i.e. where Doxyfile is). The resulting HTML documentation will be in the build/doc/ directory. You might need to create the build/ directory if it doesn't exist yet. If Corrade with generated documentation is placed in the corrade directory next to magnum, the documentation will be crosslinked with Corrade's one. If related projects (magnum-plugins, magnum-extras, magnum-integration and magnum-examples, see below) are places along these, their documentation will be also included in generated output.

The documentation can be also generated using the m.css Doxygen theme. Use Doxyfile-mcss for a local build, the Doxyfile-public is meant for the publicly available documentation at https://doc.magnum.graphics/magnum/. The resulting documentation will be either in build/doc-mcss/ or build/doc-public/.

Building for ANGLE on Windows

Magnum is able to run on the ANGLE OpenGL-to-D3D translator. Download the code from https://github.com/MSOpenTech/angle and use the provided Visual Studio solution to build it. Put the resulting libGLESv2/libEGL libraries and GLES2/GLES3/EGL includes to a location where CMake can find them or set CMAKE_PREFIX_PATH accordingly. ANGLE supports only OpenGL ES, thus you need to enable TARGET_GLES. The engine is built for OpenGL ES 2.0 by default, switch to 3.0 by disabling TARGET_GLES2.

mkdir build-angle && cd build-angle
cmake .. ^
    -DCMAKE_PREFIX_PATH=<path-to-ANGLE-installation> ^
    -DTARGET_GLES=ON ^
    -DTARGET_GLES2=OFF ^
    -DWITH_SDL2APPLICATION=ON
cmake --build .

See ANGLE for more information about using ANGLE.

Cross-compiling

For cross-compiling you need to have both target and native version of Corrade installed, because Corrade needs to run corrade-rc utility on the host system as part of the build process. If native version of corrade-rc is not found on the system, cross-compilation will fail.

You also need to have the toolchains submodule updated. Either run the following command, or, if you build from source archive, download a snapshot of the toolchains repository from https://github.com/mosra/toolchains and put the contents in the toolchains/ subdirectory.

git submodule update --init

Note that CMake for some reason treats CMAKE_PREFIX_PATH and CMAKE_INSTALL_PREFIX differently while cross-compiling and you may need to add dependency paths to both CMAKE_PREFIX_PATH and CMAKE_FIND_ROOT_PATH to make it able to find the dependencies.

Cross-compiling for 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:

mkdir build-winrt && cd build-winrt
cmake .. ^
    -DCMAKE_SYSTEM_NAME=WindowsStore ^
    -DCMAKE_SYSTEM_VERSION=10 ^
    -DCORRADE_RC_EXECUTABLE="C:/Sys/bin/corrade-rc.exe" ^
    -DCMAKE_INSTALL_PREFIX="C:/Sys-winrt" ^
    -DBUILD_STATIC=ON ^
    -DWITH_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.

See Windows for more information about building your projects for WinRT.

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.

See Windows for more information about building your projects for Windows.

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 BUILD_STATIC is implicitly enabled.

Then create build directory and run cmake and the build command in it.

WebGL 1.0 (GLES 2.0 equivalent) is enabled by default, switch to 2.0 (GLES 3.0 equivalent) by disabling 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 \
    -DMAGNUM_DEPLOY_PREFIX=/srv/http/magnum \
    -DWITH_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 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.

See JavaScript, HTML5 and WebGL for more information about building your projects for Emscripten.

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.

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

Please note that BUILD_MULTITHREADED is supported only since Xcode 7.3 and doesn't work on i386 iOS Simulator, you need to disable it in order to build for older platforms.

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 \
    -DBUILD_STATIC=ON \
    -DBUILD_PLUGINS_STATIC=ON \
    -DTARGET_GLES2=OFF \
    -DWITH_SDL2APPLICATION=ON \
    -G Xcode
cmake --build .

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

See iOS documentation for more information about building your projects for iOS.

Crosscompiling for Android

You will need Android NDK installed and configured and Corrade built for Android. CMake 3.7 is required, as it has Android support builtin. The supported toolchain is now Clang with libc++, GCC is not supported anymore.

Create a build directory and run cmake and the build command in it. Set CMAKE_SYSTEM_NAME to Android to enable the crosscompilation, CMAKE_ANDROID_NDK_TOOLCHAIN_VERSION and CMAKE_ANDROID_STL_TYPE to use Clang with 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.

If you set CMAKE_INSTALL_PREFIX to /usr subdirectory of the particular Android platform sysroot, the package will get found automatically when compiling subprojects. Gradle and other Android buildsystems expect platform-independent includes and other files to be stored in a central location, you can set MAGNUM_INCLUDE_INSTALL_PREFIX to /usr subdirectory of the global NDK sysroot. Another option is to explicitly set CMAKE_PREFIX_PATH to the install location in depending projects.

Note that 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 TARGET_GLES2.

mkdir build-android-arm64 && cd build-android-arm64
cmake .. \
    -DCMAKE_SYSTEM_NAME=Android \
    -DCMAKE_SYSTEM_VERSION=22 \
    -DCMAKE_ANDROID_ARCH_ABI=arm64-v8a \
    -DCMAKE_ANDROID_NDK_TOOLCHAIN_VERSION=clang \
    -DCMAKE_ANDROID_STL_TYPE=c++_static \
    -DCMAKE_BUILD_TYPE=Release \
    -DCMAKE_INSTALL_PREFIX=/opt/android-ndk/platforms/android-22/arch-arm/usr \
    -DMAGNUM_INCLUDE_INSTALL_PREFIX=/opt/android-ndk/sysroot/usr \
    -DTARGET_GLES2=OFF \
    -DWITH_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.

See Android for more information about building your projects for Android.

Continuous Integration

Travis

In package/ci/ there is a travis.yml file with Linux GCC 4.7, macOS, Linux desktop GLES2/GLES3, iOS GLES2/GLES3, Emscripten WebGL1/WebGL2, Android GLES2/GLES3, AddressSanitizer and ThreadSanitizer configuration. Online at https://travis-ci.org/mosra/magnum.

AppVeyor

In package/ci/ there is an appveyor.yml file with Windows desktop MSVC, MinGW, Windows desktop GLES2/GLES3 and Windows RT GLES2/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.