Magnum
Downloading and building

Table of Contents

Guide how to download and build Magnum on different platforms.

Minimal set of tools and libraries required for building is:

Note that full feature set is available only on GCC 4.8.1 and Clang 3.1.

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 compressed archive or use the command line:

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

Compilation, installation

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

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 MinGW-w64 or MSVC 2013 compiler. It's then up to you whether you will use QtCreator, Visual Studio or do the build from 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. Then 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 you can also use QtCreator (just QtCreator, you don't need the full Qt SDK). Configure it to use CMake and either 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 new make install build rule.

Enabling or disabling features

The libraries are build as shared by default. If you are developing for 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 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 -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. The library and plugin distinction is handled semi-automatically when using Magnum in depending projects, see Usage with CMake for more information.

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. 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 TARGET_* CMake parameters you can target other platforms. Note that some features are available for desktop OpenGL only, see Functionality requiring desktop OpenGL.

By default the engine is built in a way that allows having multiple 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 Usage with CMake and Corrade/Corrade.h for additional information.

By default the engine is built with nearly everything except Audio library, plugins and application libraries (see below). Using WITH_* CMake parameters you can specify which parts will be built and which not:

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). Choose the one which suits your requirements and your platform best:

None of the context libraries is built by default. You need them only if you choose to not use any application library (see Using custom platform toolkits for more information):

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

Magnum also contains a set of dependency-less plugins for importing essential file formats. Additional plugins are provided in 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 disabled by default:

Some of these utilities operate with plugins and they search for them in the default plugin locations. You can override those locations using 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, all Platform libraries and the OpenGLTester 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.

Building and running unit tests

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

ctest --output-on-failure

in build directory. On Windows the tests require the library to be installed with DLLs accessible through PATH. See 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 (version 1.8 with Markdown support is used, but older versions should do good job too) and additionally uses TeX for math formulas. The documentation can be build by running

doxygen

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

Related projects

The engine itself is kept as small as possible with only little dependencies. Additional functionality, often depending on external libraries, is provided in separate repositories. Various importer plugins for image, audio and 3D model formats are maintained in Plugins repository, Integration with various external math and physics libraries is provided by Integration library.

Prepared packages

ArchLinux packages

In package/archlinux directory is currently one package for Git development build. The package is also in AUR under the same name.

There are also a few development PKGBUILDs in package/archlinux, which allow you to build and install the package directly from source tree without downloading anything. The native PKGBUILDs also contain check() function which will run all unit tests before packaging.

Gentoo ebuilds

Gentoo Git ebuild is available in package/gentoo directory.

DEB packages

There is also package/debian/ directory with all files needed for building Debian packages. You need to have corrade-dev DEB package installed and in addition also 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:

ln -s package/debian .
dpkg-buildpackage

This will compile binary and development packages, which will then appear in parent directory. If you need to modify CMake flags (enabling/disabling some features, for example), modify the last entry in debian/rules.

Homebrew formulas

macOS Homebrew formulas are in package/homebrew directory. Either use the *.rb files directly or use the tap at https://github.com/mosra/homebrew-magnum :

brew install --HEAD mosra/magnum/magnum

Building for ANGLE on Windows

Magnum is able to run on ANGLE OpenGL-to-D3D translator. Download the code from https://github.com/MSOpenTech/angle and use 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 -DTARGEET_GLES2=OFF \
    -DWITH_SDL2APPLICATION=ON
cmake --build .

Crosscompiling

For crosscompiling 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, crosscompilation will fail.

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

git submodule init
git submodule update

Note that CMake for some reason treats CMAKE_PREFIX_PATH and CMAKE_INSTALL_PREFIX differently while crosscompiling 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.

Crosscompiling for Windows RT

As said above, you need native build of corrade-rc executable. 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 2013 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 instructions above, but use project files from the winrt/ directory instead. Version 2.0.4 of 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 for depending projects.

See Platform::Sdl2Application documentation for more information about building your projects for WinRT.

Crosscompiling for Windows using MinGW-w64

Note
This guide is tailored mainly for crosscompiling from ArchLinux. For this system there is also prepared mingw-w64-magnum development package in package/archlinux, named PKGBUILD-mingw-w64. See above for more information.

You will need MinGW-w64 versions of the compiler and all dependent libraries (Corrade), i.e. these ArchLinux packages:

Then create build directories for 32b/64b build and run cmake and 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 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 for depending projects.

Crosscompiling for Emscripten

You will need Emscripten installed and configured. The toolchains require CMake 3.7 or newer to properly set compiler and linker flags.

There are two toolchain files. The generic/Emscripten.cmake is for the classical (asm.js) build, the generic/Emscripten-wasm.cmake is for 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 build command in it. Be sure to set CMAKE_INSTALL_PREFIX to path contained in EMSCRIPTEN_TOOLCHAIN_PATH.

WebGL 1.0 (GLES 2.0 equivalent) is enabled by default, switch to 2.0 (GLES 3.0 equivalent) by disabling TARGET_GLES2.

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 \
    -DWITH_SDL2APPLICATION=ON
cmake --build .

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

If you have Node.js installed, you can also build and run unit tests using ctest. See BUILD_TESTS 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 Platform::Sdl2Application documentation for more information about building your projects for Emscripten.

Crosscompiling for iOS

You will need macOS and Xcode installed.

Set CMAKE_OSX_ROOT to 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 or SDL2.

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. You might also have problems using dynamic plugins, enable BUILD_PLUGINS_STATIC to build also plugins as static. 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 for depending projects.

See Platform::Sdl2Application documentation for more information about building your projects for iOS.

Crosscompiling for Android ARM and x86

You will need Android NDK installed and configured.

Don't forget to adapt ANDROID_NDK_ROOT in generic/Android-*.cmake to path where NDK is installed. Default is /opt/android-ndk. Adapt also ANDROID_SYSROOT to your preferred API level. You might also need to update ANDROID_TOOLCHAIN_PREFIX and ANDROID_TOOLCHAIN_ROOT to fit your system.

Then create build directory and run cmake and build command in it. Be sure to set CMAKE_INSTALL_PREFIX to /usr subdirectory of ANDROID_SYSROOT and specify path where Corrade is installed in CMAKE_PREFIX_PATH.

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-arm && cd build-android-arm
cmake .. \
    -DCMAKE_TOOLCHAIN_FILE="../toolchains/generic/Android-ARM.cmake" \
    -DCMAKE_BUILD_TYPE=Release \
    -DCMAKE_PREFIX_PATH=/opt/android-ndk/platforms/android-19/arch-arm/usr \
    -DCMAKE_INSTALL_PREFIX=/opt/android-ndk/platforms/android-19/arch-arm/usr \
    -DTARGET_GLES=ON -DTARGET_GLES2=OFF \
    -DWITH_ANDROIDAPPLICATION=ON
cmake --build .

mkdir build-android-x86 && cd build-android-x86
cmake .. \
    -DCMAKE_TOOLCHAIN_FILE="../toolchains/generic/Android-x86.cmake" \
    -DCMAKE_BUILD_TYPE=Release \
    -DCMAKE_PREFIX_PATH=/opt/android-ndk/platforms/android-19/arch-x86/usr \
    -DCMAKE_INSTALL_PREFIX=/opt/android-ndk/platforms/android-19/arch-x86/usr \
    -DTARGET_GLES=ON -DTARGET_GLES2=OFF \
    -DWITH_ANDROIDAPPLICATION=ON
cmake --build .

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

For ArchLinux there are also prepared package files in package/archlinux, named PKGBUILD-android-arm and PKGBUILD-android-x86, see above for more information.

See Platform::AndroidApplication documentation 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 Clang, 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. The Linux build has code coverage reports available online at https://coveralls.io/github/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.