Getting started » Downloading and building integration libraries

Guide how to download and build integration libraries for the Magnum engine.

The integration repository provides integration of various math and physics libraries with Magnum engine. They are not needed for essential usage, but it might get handy if you want to use something other than builtin components and seamlessly integrate them with the rest of the engine.

Prepared packages

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

Vcpkg packages on Windows

Magnum Integration libraries are available as a Vcpkg package. See the Magnum Vcpkg documentation for a more detailed introduction and a troubleshooting guide. Installing latest stable version of Magnum Integration with all its dependencies is done like this:

vcpkg install magnum-integration

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

vcpkg install --head corrade magnum magnum-integration

Note that just a subset of integration libraries is installed by default. To opt-in or opt-out of additional features, you can use the following syntax; feature names are simply names of CMake WITH_* options from the Enabling or disabling features section but lowercase, e.g.:

vcpkg install magnum-integration[bullet]

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

vcpkg install magnum-integration[*]

There are also Vcpkg packages for Magnum Plugins and Magnum Extras.

ArchLinux packages

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

There are also a few development packages for native 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 source tree. Example usage:

git clone git://github.com/mosra/magnum-integration && cd magnum-integration
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-integration-*.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 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-integration magnum-integration-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 and Magnum Debian packages installed and in addition also the dpkg-dev and debhelper packages. Building is easy, just change directory to package root, link or copy the package/debian directory there and run dpkg-buildpackage:

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

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

sudo dpkg -i ../magnum-integration*.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 and Magnum Examples.

Gentoo Linux ebuilds

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

git clone git://github.com/mosra/magnum-integration && cd magnum-integration
cd package/gentoo
sudo ebuild dev-libs/magnum-integration/magnum-integration-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 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 Integration with all dependencies:

brew install mosra/magnum/magnum-integration

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
brew install --HEAD mosra/magnum/magnum-integration

When installing from the *.rb files you need to install the Corrade and Magnum Homebrew packages 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 and Magnum Examples.

Manual build

The source is available on GitHub: https://github.com/mosra/magnum-integration. Building the integration libraries is very similar to building Magnum itself. See Downloading and building for additonal information about building and running tests, cross-compiling and platform-specific issues.

Enabling or disabling features

Similarly to Magnum, 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. If you plan to use them with shared libraries later, enable also position-independent code with BUILD_STATIC_PIC.

Libraries built in the Debug configuration (e.g. with CMAKE_BUILD_TYPE set to Debug) have a -d suffix, similarly to what is done when building Magnum itself.

By default no integration libraries are built and you need to select them manually:

Note that each *Integration namespace documentation contains more detailed information about its dependencies, availability on particular platforms and also a guide how to enable given library for building and hot to use it with CMake.

Building documentation

The documentation for integration libraries is built as part of of the main Magnum documentation. Clone the projects next to each other and continue as described in Building documentation.

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

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

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