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 package
- ArchLinux packages
- MSYS2 packages
- Packages for Debian, Ubuntu and derivatives
- Gentoo Linux ebuilds
- Homebrew formulas for macOS
Vcpkg package
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
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 MAGNUM_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 https://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.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 and Magnum Examples.
MSYS2 packages
MSYS2 package for the latest stable release is mantained in the official repos. Installing is as simple as this:
pacman -S mingw-w64-x86_64-magnum-integration # or mingw-w64-i686-magnum-integration
Similarly to ArchLinux, there is one package in the package/msys/magnum-integration
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 corresponding Corrade and Magnum MSYS2 packages. Example usage:
git clone https://github.com/mosra/magnum-integration && cd magnum-integration 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.
Packages for Debian, Ubuntu and derivatives
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 https://github.com/mosra/magnum-integration && cd magnum-integration ln -s package/debian . dpkg-buildpackage --no-sign
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 package/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 https://github.com/mosra/magnum-integration && cd magnum-integration cd package/gentoo sudo ebuild dev-libs/magnum-integration/magnum-integration-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 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:/
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 # 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 brew upgrade --fetch-HEAD mosra/magnum/magnum-integration
When installing from the *.rb
files you need to install the Corrade and Magnum Homebrew packages first. As the integration libs depend on a variety of 3rd party libraries, it's possible to control a subset that gets built and installed:
--with-dartsim
enables building of DartIntegration. This library is not built by default.--without-eigen
,--without-glm
and--without-bullet
disable building of EigenIntegration, GlmIntegration and BulletIntegration, respectively. These libraries are all implicitly built otherwise.
Libraries not listed above are not enabled for building. 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:/
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 MAGNUM_BUILD_STATIC
to build the libraries as static. If you plan to use them with shared libraries later, enable also position-independent code with MAGNUM_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:
MAGNUM_WITH_BULLET
— Build the BulletIntegration library. Depends on Bullet Physics (or, in case of Emscripten, see below)MAGNUM_WITH_DART
— Build the DartIntegration library. Depends on DART.MAGNUM_WITH_EIGEN
— Build the EigenIntegration library. Depends on Eigen.MAGNUM_WITH_GLM
— Build the GlmIntegration library. Depends on GLM.MAGNUM_WITH_IMGUI
— Build the ImGuiIntegration library. Depends on Dear ImGui — if you are on Vcpkg, it will "just work", otherwise you need to download the sources and pointIMGUI_DIR
to their directory so CMake can find them.MAGNUM_WITH_OVR
— Build the OvrIntegration library. Depends on the Oculus SDK.
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.
Using dependencies from Emscripten Ports
When building for Emscripten, by enabling the following options you can use dependencies from Emscripten Ports:
MAGNUM_USE_EMSCRIPTEN_PORTS_BULLET
— Build BulletIntegration using the version from Emscripten Ports. Requires CMake 3.13 and newer and is equivalent to passing-s USE_BULLET=1
to the compiler. Please note that currently (September 2019), the version there is still the old 2.82 from 2013.
If Emscripten doesn't have the ports cached yet, due to parallel compilation it might happen that while one job is downloading and building the port, another will fail due to headers not being installed yet. Restarting the compilation second time usually works, if you want a reliable way instead, you can do it via embuilder.py
, for example:
embuilder.py build bullet
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
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:/
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:/
Codecov.io
Linux, Linux GLES, macOS and Windows MinGW builds contribute to a combined code coverage report, available online at https:/