Downloading and building

ArchLinux packages

In package/archlinux there is a development package, similar to the ones in Magnum itself. They allow you to build and install the package directly from the source tree.

git clone https://github.com/mosra/magnum-bindings && cd magnum-bindings
cd package/archlinux
makepkg -fp PKGBUILD

The PKGBUILD also contains 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-bindings-*.pkg.tar.zst

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 Bindings with all its dependencies:

brew install mosra/magnum/magnum-bindings

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

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

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 setup.py or enable / disable additional features, edit the *.rb file.

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

Static build

In case Corrade or Magnum is built with CORRADE_BUILD_STATIC / MAGNUM_BUILD_STATIC, the corresponding bindings are compiled into a single dynamic module instead of one module per Corrade/Magnum library.

In this case, similarly to linking static plugins to Magnum’s own command-line utilities, you can use the MAGNUM_PYTHON_BINDINGS_STATIC_PLUGINS CMake variable to link static plugins to the Python module, assuming Magnum, Magnum Plugins and Magnum Bindings are all CMake subprojects. It’s a semicolon-separated list of existing CMake targets, for example Magnum::AnyImageImporter;MagnumPlugins::StbImageImporter.

On Unix platforms, Python by default loads the modules in isolated namespaces. That’s a good thing to do from a security point of view, nevertheless with static builds of Corrade and Magnum it will result in globals duplicated across the Corrade and Magnum modules (and also any other Python modules that use Magnum natively inside) unable to see each other in order to deduplicate themselves, causing strange issues. To solve that, the MAGNUM_BUILD_PYTHON_BINDINGS_RTLD_GLOBAL CMake option, which is enabled by default on static builds on Unix platforms, overrides Python’s module loading code to not load them in isolated namespaces using sys.setdlopenflags(). The override then happens inside import corrade and is in effect for the rest of the interpreter lifetime, to affect also any potential other modules depending on Magnum loaded later. See also CORRADE_BUILD_STATIC_UNIQUE_GLOBALS and MAGNUM_BUILD_STATIC_UNIQUE_GLOBALS in Corrade and Magnum for more information.

Running unit tests

Essential functionality of the bindings is tested using Python’s builtin unittest module. The tests currently assume a CMake build directory with all binaries already built located in a build/ directory in project root, running them is then a matter of:

cd src/python/magnum
python -m unittest

For code coverage, coverage.py is used. Get it via pip or as a system package.

pip install coverage # sudo might be needed

Running the unit tests with coverage enabled is then a matter of executing the following commands, the resulting HTML overview is located in htmlcov/index.html:

cd src/python/magnum
coverage run -m unittest
coverage html