Getting started » Downloading and building plugins

Vcpkg packages on Windows

Magnum Plugins are available as a Vcpkg package. After setting up Vcpkg like described in the README, you can install latest stable version of Magnum Plugins with all its dependencies like this:

vcpkg install magnum-plugins

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

vcpkg install corrade --head
vcpkg install magnum --head
vcpkg install magnum-plugins --head

This by default installs a 32-bit dynamic version of the package, you can use vcpkg install magnum-plugins:x64-windows or vcpkg install magnum-plugins:x64-windows-static to install a 64-bit (static) version instead. You can also use the VCPKG_DEFAULT_TRIPLET variable to change the default — see the Vcpkg triplet documentation for more information.

Note that just a subset of plugins isinstalled 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. See the feature documentation for more information.

vcpkg install magnum-plugins[assimpimporter,ddsimporter]

Packages installed using Vcpkg can be used straight away in Visual Studio — all you need to do is to #include the headers you want, 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 to pass additional flags to CMake, run vcpkg edit magnum-plugins and edit OPTIONS in vcpkg_configure_cmake().

There are also Vcpkg packages for 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-plugins

In package/archlinux/magnum-plugins-git there is a package for Git development build. The package is also in AUR as magnum-plugins-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-plugins && cd magnum-plugins
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-plugins-*.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 Integration, Magnum Extras and Magnum Examples.

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 git://github.com/mosra/magnum-plugins && cd magnum-plugins
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-plugins*.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 Integration, 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 Plugins like this:

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

brew install mosra/magnum/magnum-plugins

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

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

Enabling or disabling features

Similarly to Magnum, the plugins are build as shared by default. If you are developing for a platform that doesn't support dynamic library loading or if you just want to link them statically, enable BUILD_PLUGINS_STATIC to build the plugins as static. If you plan to use the static plugins with shared libraries later, enable also position-independent code with BUILD_STATIC_PIC. Dynamic plugins are loaded by the manager on request at runtime, potentially saving memory when the plugin is not needed, static plugins must be linked in at compile time. Some plugins expose their internal state through separate libraries, their static build can be controlled using the BUILD_STATIC option.

Static plugins built in the Debug configuration (e.g. with CMAKE_BUILD_TYPE set to Debug) have a -d suffix, dynamic plugins in Debug configuration are installed to the magnum-d subdirectory, similarly to what is done when building Magnum itself.

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

• WITH_ASSIMPIMPORTER — Build the AssimpImporter plugin. Depends on Assimp.
• WITH_COLLADAIMPORTER — Build the ColladaImporter plugin. Depends on Qt4.
• WITH_DDSIMPORTER — Build the DdsImporter plugin.
• WITH_DEVILIMAGEIMPORTER — Build the DevIlImageImporter plugin. Depends on DevIL.
• WITH_DRFLACAUDIOIMPORTER — Build the DrFlacAudioImporter plugin.
• WITH_DRWAVAUDIOIMPORTER — Build the DrWavAudioImporter plugin.
• WITH_FREETYPEFONT — Build the FreeTypeFont plugin. Depends on FreeType.
• WITH_HARFBUZZFONT — Build the HarfBuzzFont plugin. Enables also building of the FreeTypeFont plugin. Depends on HarfBuzz.
• WITH_JPEGIMPORTER — Build the JpegImporter plugin. Depends on libJPEG.
• WITH_MINIEXRIMAGECONVERTER — Build the MiniExrImageConverter plugin.
• WITH_OPENGEXIMPORTER — Build the OpenGexImporter plugin. Enables also building of the OpenDdl library.
• WITH_PNGIMAGECONVERTER — Build the PngImageConverter plugin. Depends on libPNG.
• WITH_PNGIMPORTER — Build the PngImporter plugin. Depends on libPNG.
• WITH_STANFORDIMPORTER — Build the StanfordImporter plugin.
• WITH_STBIMAGECONVERTER — Build the StbImageConverter plugin.
• WITH_STBIMAGEIMPORTER — Build the StbImageImporter plugin. Enabled automatically if WITH_TINYGLTFIMPORTER is enabled.
• WITH_STBTRUETYPEFONT — Build the StbTrueTypeFont plugin.
• WITH_STBVORBISAUDIOIMPORTER — Build the StbVorbisAudioImporter plugin.
• WITH_TINYGLTFIMPORTER — Build the TinyGltfImporter plugin. Enables also building of the StbImageImporter plugin.

Some plugins expose their internal state through separate libraries and you can control their build separately:

• WITH_OPENDDL — Build the OpenDdl library. Enabled automatically if WITH_OPENGEXIMPORTER is enabled.

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

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

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

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