Getting started » Downloading and building extras

ArchLinux packages

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

Gentoo Linux ebuilds

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

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

brew install mosra/magnum/magnum-extras

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

# 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
brew upgrade --fetch-HEAD mosra/magnum/magnum-extras

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

CMake Package Manager / CPM

If you're using CPM, adding Magnum Extras as a dependency can be done with the following, together with the Corrade, Magnum and optionally Magnum Plugins 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 versionExtras.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)

CPMAddPackage(
    NAME magnum-extras
    GIT_REPOSITORY https://github.com/mosra/magnum-extras.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 certain features may require additional dependencies, may also rely on Magnum features that are not enabled by default, or may require certain Magnum Plugins to be built in order to load them at runtime. See their documentation for more information.

CPMAddPackage(
    NAME magnum-extras
    ...
    OPTIONS
        "MAGNUM_WITH_UI ON")

CPM can be used also for Magnum Integration.

Vcpkg package

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

vcpkg install magnum-extras

Note that just a subset of extra 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-extras[ui]

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

vcpkg install magnum-extras[*]

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

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 libraries are built and you need to select them manually:

• MAGNUM_WITH_UI — Build the Ui library. Does not work on OpenGL ES 2.0 / WebGL 1.0 builds of Magnum. Enabled automatically if MAGNUM_WITH_PLAYER is enabled.

Besides libraries, the following apps are available, also all disabled by default:

• MAGNUM_WITH_PLAYER – Build the magnum-player executable
• MAGNUM_WITH_UI_GALLERY — Build the magnum-ui-gallery executable

Options controlling the build:

• MAGNUM_PLAYER_STATIC_PLUGINS — Static plugins to find and link to the magnum-player executable. Intended for use in scenarios where both Magnum and plugins are built as static, in which case the executable doesn't have a possibility to load dynamic plugins from a filesystem. Expects a semicolon-separated list of existing CMake targets, for example Magnum::AnyImageImporter;MagnumPlugins::StbImageImporter, for each of those a corresponding find_package() and target_link_libraries() is called.

Note that each 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 how to use it with CMake.

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://circleci.com/gh/mosra/magnum-extras.

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

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