Getting started » Downloading and building plugins

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 https://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.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 Extras, Magnum Integration 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-plugins # or mingw-w64-i686-magnum-plugins

Similarly to ArchLinux, there is one package in the package/msys/magnum-plugins 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-plugins && cd magnum-plugins
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 Integration.

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-plugins && cd magnum-plugins
ln -s package/debian .
dpkg-buildpackage --no-sign

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 package/debian/rules. Watch out, as indentation has to be done using tabs, not spaces.

There are also Debian packages for Magnum Extras, Magnum Integration 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 https://github.com/mosra/magnum-plugins && cd magnum-plugins
cd package/gentoo
sudo ebuild dev-libs/magnum-plugins/magnum-plugins-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 Extras, Magnum Integration and Magnum Examples.

Packages for Fedora, openSUSE and other RPM-based Linux distributions

Spec files for RPM-based distributions are in the package/rpm/ directory. In addition you will need to install the following dependencies in order to build the packages (assuming Fedora Linux):

sudo dnf install fedora-packager rpmdevtools

After that, make sure you build and install the Corrade and Magnum RPM packages first, and run the build.sh script. Internally it queries the Git version, makes a tarball, may ask you to install appropriate dependencies if not present already, and then builds the package.

./package/rpm/build.sh

At the end, if everything succeeds, you'll have the newly built packages located in ~/rpmbuild/RPMS. The script will print their names at the end.

If you want to pass additional flags to CMake or enable / disable additional features, edit the *.spec file.

There are also RPM packages for Magnum Extras, Magnum Integration 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

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

When installing from the *.rb files you need to install the Corrade and Magnum Homebrew packages first. As the plugins depend on a variety of 3rd party libraries, it's possible to control a subset that gets built and installed:

• --with-devil, --with-faad2 and --with-harfbuzz enable building of DevIlImageImporter, Faad2AudioImporter and HarfBuzzFont, respectively. None of these plugins are built by default.
• --without-assimp, --without-freetype, --without-glslang, --without-libpng, --without-libspng, --without-jpeg, --without-openexr, --without-spirv-tools, --without-zstd and --without-webp disable building of AssimpImporter, FreeTypeFont, GlslangShaderConverter, PngImporter and PngImageConverter, JpegImporter and JpegImageConverter, OpenExrImporter and OpenExrImageConverter, SpirvToolsShaderConverter, zstd support in BasisImporter and BasisImageConverter, and WebPImporter, respectively. These plugins are all implicitly built otherwise.

Plugins not listed above are built always. If you want to pass additional flags to CMake or enable / disable other features, edit the *.rb file.

There are also Homebrew packages for Magnum Extras, Magnum Integration and Magnum Examples.

CMake Package Manager / CPM

If you're using CPM, adding Magnum Plugins as a dependency can be done with the following, together with the Corrade and Magnum packages. If you're fetching the master branch, it's recommended to disable GIT_SHALLOW to perform a full clone including all tags. If not, the build prints a warning about being unable to fetch a Git version for the versionPlugins.h header, and will generate a fallback file instead.

CPMAddPackage(
    NAME corrade
    GIT_REPOSITORY https://github.com/mosra/corrade.git
    GIT_TAG master
    GIT_SHALLOW NO)

CPMAddPackage(
    NAME magnum
    GIT_REPOSITORY https://github.com/mosra/magnum.git
    GIT_TAG master
    GIT_SHALLOW NO)

CPMAddPackage(
    NAME magnum-plugins
    GIT_REPOSITORY https://github.com/mosra/magnum-plugins.git
    GIT_TAG master
    GIT_SHALLOW NO)

You'll most likely want to enable / disable additional features, or perhaps pass additional flags to CMake, which can be done via OPTIONS. Note that some features will require additional dependencies and may also rely on Magnum features that are not enabled by default, see their documentation for more information.

CPMAddPackage(
    NAME magnum-plugins
    ...
    OPTIONS
        "MAGNUM_WITH_GLTFIMPORTER ON"
        "MAGNUM_WITH_STBIMAGEIMPORTER ON")

CPM can be used also for Magnum Extras and Magnum Integration.

Vcpkg package

Magnum Plugins 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 Plugins with all its dependencies is done like this:

vcpkg install magnum-plugins

Note that just a subset of plugins 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-plugins[assimpimporter,ddsimporter]

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

vcpkg install magnum-plugins[*]

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

Enabling or disabling features

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

• MAGNUM_WITH_ASSIMPIMPORTER — Build the AssimpImporter plugin. Depends on Assimp.
• MAGNUM_WITH_ASTCIMPORTER — Build the AstcImporter plugin.
• MAGNUM_WITH_BASISIMAGECONVERTER — Build the BasisImageConverter plugin. Depends on Basis Universal.
• MAGNUM_WITH_BASISIMPORTER — Build the BasisImporter plugin. Depends on Basis Universal — if you are on Vcpkg, it will "just work", otherwise you need to download the sources and point BASIS_UNIVERSAL_DIR to their directory so CMake can find them.
• MAGNUM_WITH_BCDECIMAGECONVERTER — Build the BcDecImageConverter plugin.
• MAGNUM_WITH_CGLTFIMPORTER deprecated — Build the CgltfImporter plugin.
• MAGNUM_WITH_DDSIMPORTER — Build the DdsImporter plugin.
• MAGNUM_WITH_DEVILIMAGEIMPORTER — Build the DevIlImageImporter plugin. Depends on DevIL.
• MAGNUM_WITH_DRFLACAUDIOIMPORTER — Build the DrFlacAudioImporter plugin.
• MAGNUM_WITH_DRMP3AUDIOIMPORTER — Build the DrMp3AudioImporter plugin.
• MAGNUM_WITH_DRWAVAUDIOIMPORTER — Build the DrWavAudioImporter plugin.
• MAGNUM_WITH_ETCDECIMAGECONVERTER — Build the EtcDecImageConverter plugin.
• MAGNUM_WITH_FAAD2AUDIOIMPORTER — Build the Faad2AudioImporter plugin. Depends on FAAD2.
• MAGNUM_WITH_FREETYPEFONT — Build the FreeTypeFont plugin. Depends on FreeType.
• MAGNUM_WITH_GLSLANGSHADERCONVERTER — Build the GlslangShaderConverter plugin. Depends on Glslang.
• MAGNUM_WITH_GLTFIMPORTER — Build the GltfImporter plugin.
• MAGNUM_WITH_GLTFSCENECONVERTER — Build the GltfSceneConverter plugin.
• MAGNUM_WITH_HARFBUZZFONT — Build the HarfBuzzFont plugin. Enables also building of the FreeTypeFont plugin. Depends on HarfBuzz.
• MAGNUM_WITH_ICOIMPORTER — Build the IcoImporter plugin.
• MAGNUM_WITH_JPEGIMAGECONVERTER — Build the JpegImageConverter plugin.
• MAGNUM_WITH_JPEGIMPORTER — Build the JpegImporter plugin. Depends on [libJPEG](https://ijg.org.
• MAGNUM_WITH_KTXIMAGECONVERTER — Build the KtxImageConverter plugin.
• MAGNUM_WITH_KTXIMPORTER — Build the KtxImporter plugin.
• MAGNUM_WITH_MESHOPTIMIZERSCENECONVERTER — Build the MeshOptimizerSceneConverter plugin.
• MAGNUM_WITH_MINIEXRIMAGECONVERTER — Build the MiniExrImageConverter plugin.
• MAGNUM_WITH_OPENEXRIMAGECONVERTER — Build the OpenExrImageConverter plugin. Depends on OpenEXR.
• MAGNUM_WITH_OPENEXRIMPORTER — Build the OpenExrImporter plugin. Depends on OpenEXR.
• MAGNUM_WITH_OPENGEXIMPORTER — Build the OpenGexImporter plugin. Enables also building of the OpenDdl library.
• MAGNUM_WITH_PNGIMAGECONVERTER — Build the PngImageConverter plugin. Depends on libPNG.
• MAGNUM_WITH_PNGIMPORTER — Build the PngImporter plugin. Depends on libPNG.
• MAGNUM_WITH_PRIMITIVEIMPORTER — Build the PrimitiveImporter plugin.
• MAGNUM_WITH_SPIRVTOOLSSHADERCONVERTER — Build the SpirvToolsShaderConverter plugin. Depends on SPIRV-Tools.
• MAGNUM_WITH_SPNGIMPORTER — Build the SpngImporter plugin. Depends on libspng.
• MAGNUM_WITH_STANFORDIMPORTER — Build the StanfordImporter plugin.
• MAGNUM_WITH_STANFORDSCENECONVERTER — Build the StanfordSceneConverter plugin.
• MAGNUM_WITH_STBDXTIMAGECONVERTER — Build the StbDxtImageConverter plugin.
• MAGNUM_WITH_STBIMAGECONVERTER — Build the StbImageConverter plugin.
• MAGNUM_WITH_STBIMAGEIMPORTER — Build the StbImageImporter plugin. Enabled automatically if MAGNUM_WITH_TINYGLTFIMPORTER is enabled.
• MAGNUM_WITH_STBRESIZEIMAGECONVERTER — Build the StbResizeImageConverter plugin.
• MAGNUM_WITH_STBTRUETYPEFONT — Build the StbTrueTypeFont plugin.
• MAGNUM_WITH_STBVORBISAUDIOIMPORTER — Build the StbVorbisAudioImporter plugin.
• MAGNUM_WITH_TINYGLTFIMPORTER deprecated — Build the TinyGltfImporter plugin.
• MAGNUM_WITH_UFBXIMPORTER — Build the UfbxImporter plugin.
• MAGNUM_WITH_WEBPIMAGECONVERTER — Build the WebPImageConverter plugin.
• MAGNUM_WITH_WEBPIMPORTER — Build the WebPImporter plugin.

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

• MAGNUM_WITH_OPENDDL — Build the OpenDdl library. Enabled automatically if MAGNUM_WITH_OPENGEXIMPORTER is enabled.

Options controlling the build are a subset of the options used by Magnum:

• MAGNUM_BUILD_STATIC — Build all libraries as static. Default is shared, except on platforms such as Android or Emscripten that don't support dynamic linking.
• MAGNUM_BUILD_STATIC_PIC — Build static libraries with position-independent code. Enabled by default when building static libraries, disable if you don't need this feature. On Emscripten this option is always off.
• MAGNUM_BUILD_PLUGINS_STATIC — Build plugins as static. By default, plugins are built as dynamic. Independent of the MAGNUM_BUILD_STATIC option to allow having static libraries with dynamic plugins and vice versa. To some extent it's also possible to have only a subset of plugins built as static — set MAGNUM_<PLUGIN>_BUILD_STATIC for particular plugins to ON or OFF to override this option.
• Additional options are inherited from the CORRADE_BUILD_MULTITHREADED and MAGNUM_BUILD_STATIC_UNIQUE_GLOBALS options specified when building Magnu,

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.

Libraries and 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.

CircleCI

In package/ci/ there is a circle.yml file with Linux GCC 4.8, Linux ARM64, macOS, Emscripten, AddressSanitizer, ThreadSanitizer, Android x86 and iOS x86_64 configuration. Online at https://circleci.com/gh/mosra/magnum-plugins.

AppVeyor

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