Downloading and building Corrade

Vcpkg packages on Windows

Corrade is available as a Vcpkg package. After setting up Vcpkg like described in the README, you can install latest stable version of Corrade like this:

vcpkg install corrade

To install the latest Git revision, use

vcpkg install corrade --head

This by default installs a 32-bit dynamic version of the package, you can use vcpkg install corrade:x64-windows or vcpkg install corrade: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.

Not all features are installed by default, only those that are implicitly enabled in Enabling or disabling features. To opt-in or opt-out of additional features, you can use the following syntax; feature names are simply names of CMake WITH_* options but lowercase. See the feature documentation for more information.

vcpkg install corrade[pluginmanager,testsuite]

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 Corrade 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 corrade and edit OPTIONS in vcpkg_configure_cmake().

ArchLinux packages

Package for the latest stable release is maintained in the community repo. Installing is as simple as this:

sudo pacman -S corrade

In package/archlinux/corrade-git there is a package for Git development build. The package is also in AUR as corrade-git.

There are also a quite 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 the source tree. Example usage:

git clone git://github.com/mosra/corrade && cd corrade
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 corrade-*.pkg.tar.xz

Edit the PKGBUILDs if you want to pass additional flags to CMake or enable / disable additional features.

Packages for Debian, Ubuntu and derivatives

The package/debian/ directory contains all files needed for building Debian packages. In addition you will need dpkg-dev and debhelper packages. Building is easy, just change directory to package root, link or copy package/debian directory there and run dpkg-buildpackage:

git clone git://github.com/mosra/corrade && cd corrade
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 ../corrade*.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.

Gentoo Linux ebuilds

Gentoo Git ebuild is available in the package/gentoo directory. Build and install the package like this:

git clone git://github.com/mosra/corrade && cd corrade
cd package/gentoo
sudo ebuild dev-libs/corrade/corrade-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.

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

Spec files for RPM-based distributions is in package/rpm/ directory. In addition you will need the rpm-build package and a ~/.rpmmacros file, which contains at least this:

%_topdir /directory/where/to/store/rpms
%_tmppath /directory/where/to/do/compilation
%packager Your Name <your@email.com>

First you need to download or create source tarball. Source tarball can be downloaded from GitHub (URL is in spec file), or in the package/ directory there is a script make-github-like-archive.sh, which generates exactly the same tarballs.

The downloaded or generated tarball must be moved or copied to %{_topdir}/SOURCES directory, so rpmbuild can find it.

When you have the sources, go to package/rpm/ directory and run this:

rpmbuild -bb corrade.spec

This will compile and generate library and development RPM for Corrade in %{_topdir}/RPMS. Install it like this:

rpm -U corrade*.rpm

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

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 Corrade:

brew install mosra/magnum/corrade

To install the latest Git revision, use

brew install --HEAD mosra/magnum/corrade

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

Downloading the sources

The source is available on GitHub: https://github.com/mosra/corrade. Clone the repository with your favorite IDE or Git GUI, download currrent snapshot as a compressed archive or use the command line:

git clone git://github.com/mosra/corrade.git

CMake primer

Corrade uses CMake as a build system and provides modules for CMake-based depending projects. That said, you need CMake to build Corrade itself, but you are not forced to use it in your project. If you are familiar enough with CMake, you can skip this section and go straight to building. Otherwise be sure to read this so you don't get lost later.

CMake is a meta-build system, which means that it generates platform-specific build files that then need to be processed (e.g. on Linux it generates Makefiles that are then processed with make).

The most straightforward way to use CMake is via the command line. First create a build directory, then run cmake with a parameter specifying where root CMakeLists.txt is, and then run the actual build command. You can either use the platform-specific tool (like make) or use the platform-independent cmake --build:

mkdir build && cd build
cmake ..
cmake --build .

Or you can use some IDE, for example QtCreator. Open project's root CMakeLists.txt file within it, QtCreator then asks you where to create the build directory, allows you to specify initial CMake parameters and then you can just press Configure and everything is ready to be built.

Corrade build is controlled using plenty of configuration variables, which are listed and described below. The variables can be specified either on command-line with -Dname=value, for example:

cmake -DBUILD_TESTS=ON ..

Boolean variables accept ON, OFF, True or False. If using QtCreator, you can enter -Dname=value into the Arguments field when running CMake. You can also use CMake GUI or ccmake for more convenient variable specification. You can run itfrom command-line, pointing it to your build dir:

cd build
cmake-gui . # or ccmake

Or you can start it as is common on your system and then point it to the build dir. It will then select the source dir automatically and populates list of available configuration variables. Each configuration variable provided by Corrade is documented (hover on it to see the tooltip). After configuring, press Configure and Generate and you are ready to build the project using your platform's build system. If you are using QtCreator, it will detect the changes afterwards and reparse the project accordingly, so you don't need to re-run CMake from within it.

The variables can also be modified directly by editing CMakeCache.txt in the build dir, although that is the least recommended way.

Via command line (on Linux/Unix)

On Unix-based OSes, the library can be built and installed using these four commands:

mkdir build && cd build
cmake -DCMAKE_INSTALL_PREFIX=/usr ..
make
make install # sudo may be needed

See below for additional configuration options.

If you plan to install the library to a non-standard location (other than /usr, e.g. /home/xyz/projects) you might want to set CMAKE_INSTALL_RPATH to lib/ subdir of given prefix (thus /home/xyz/projects/lib) so the dynamic libraries can be found at runtime.

Building on Windows

On Windows you can use either MSVC or the MinGW-w64 compiler. It's then up to you whether you will use QtCreator, Visual Studio or another IDE or do the build from a command line. Note that for most convenient usage it's best to use some dedicated directory (e.g. C:/Sys) for installing dependencies instead of putting each dependency to its own directory in C:/Program Files or elsewhere. Then you can just add its bin/ subdir (e.g. C:/Sys/bin) to %PATH% so all the DLLs are found when running the executables. If you are using MinGW-w64, the C:/MinGW directory is in most cases already prepared for exactly this.

Then, when running CMake, set CMAKE_INSTALL_PREFIX value to that directory (e.g. -DCMAKE_INSTALL_PREFIX=C:/Sys).

mkdir build && cd build
cmake -DCMAKE_INSTALL_PREFIX="C:/Sys" ..
cmake --build .
cmake --build . --target install

Enabling or disabling features

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 BUILD_STATIC to build the libraries as static. If you plan to use them with shared libraries later, enable also position-independent code with BUILD_STATIC_PIC. If you want to build with another compiler (e.g. Clang), pass -DCMAKE_CXX_COMPILER=clang++ to CMake.

Libraries built in Debug configuration (e.g. with CMAKE_BUILD_TYPE set to Debug) have a -d suffix to make it possible to have both debug and release libraries installed alongside each other. Headers and other files are the same for both debug and release configurations. This distinction is handled automatically when using the library in depending projects, see Using Corrade with CMake for more information.

By default the library expects standards-conforming compiler. However, for portability, compatibility mode for older compilers is provided. The build system tries to autodect it, but in some rare cases you may need to enable the compatibility mode explicitly:

• GCC47_COMPATIBILITY — Enable for compiling with compatibility mode for GCC 4.7. Note that you need to enable this explicitly also if you are building with Clang and use libstdc++ from GCC 4.7.
• MSVC2017_COMPATIBILITY — Enable for compiling with compatibility mode for Microsoft Visual C++ 2017.
• MSVC2015_COMPATIBILITY — Enable for compiling with compatibility mode for Microsoft Visual C++ 2015.

Corrade will detect the compiler used and refuses to build (or be used) if some required compatibility mode is not enabled. On the other hand, if any of these is enabled, Corrade will refuse to build (or be used) with a compiler that doesn't match given compatibility mode.

Particular platforms have additional requirements when it comes to location of installed files. The following variables are supported:

• LIB_SUFFIX — Setting this variable to 64 can be used to tell CMake to install to lib64/ instead of lib/. In most cases this variable is autodetected, so you don't need to set it yourself.
• CORRADE_INCLUDE_INSTALL_PREFIX — Used on Android to override location where platform-independent include files, CMake scripts and other files are installed. CMake on Android by default searches for binaries in <ndk>/platforms/android-<api>/arch-<arch>/usr based on target API and platform, but looks for headers in a central location at <ndk>/sysroot/usr. Defaults to .. If a relative path is used, it's relative to CMAKE_INSTALL_PREFIX.

The library is constantly evolving and thus some APIs are deprecated and then later removed in favor of better ones. To preserve backwards compatibility, Corrade is by default built with all deprecated APIs included. However, to make your code more robust and future-proof, it's recommended to build the library with BUILD_DEPRECATED disabled.

By default the library is built with everything included. Using the following WITH_* CMake options you can specify which parts will be built and which not:

• WITH_INTERCONNECT — Build the Interconnect library. Enables also building of the Utility library.
• WITH_PLUGINMANAGER — Build the PluginManager library. Enables also building of the Utility library.
• WITH_TESTSUITE — Build the TestSuite library. Enables also building of the Utility library.
• WITH_UTILITY — Build the Utility library. Enabled automatically if WITH_INTERCONNECT, WITH_PLUGINMANAGER or WITH_TESTSUITE is enabled. The Containers library and corrade-rc executable is built along with this library.

Platform-specific options:

• UTILITY_USE_ANSI_COLORS — if building for Windows, this will use ANSI escape codes in Utility::Debug instead of WINAPI functions. Note that you need at least Windows 10 or non-standard console emulator to display them properly. Note that when compiling for Windows RT this option is implicitly enabled, because the WINAPI functions are not available for this target.
• TESTSUITE_TARGET_XCTEST — if building for Xcode on macOS or iOS, this will make the TestSuite tests compatible with the XCTest framework and thus runnable directly from Xcode and also directly on iOS.

The features used can be conveniently detected in depending projects both in CMake and C++ sources, see Using Corrade with CMake and Corrade/Corrade.h for more information.

Note that each namespace documentation contains more detailed guide how to enable given library for building and how to use it with CMake.

Building and running tests

If you want to build also the tests (which are not built by default), enable BUILD_TESTS in CMake. The tests use Corrade's own TestSuite framework and can be run either manually (the binaries are located in Test/ subdirectories in the build directory) or using

ctest --output-on-failure

in the build directory. On Windows the tests require the library to be installed with DLLs accessible through %PATH%. See the above Windows documentation for more information.

Building documentation

The documentation (which you are currently reading) is written in Doxygen and additionally uses LaTeX for math formulas. Documentation using the stock HTML theme can be build by running

doxygen

in the root directory (i.e. where Doxyfile is). The resulting HTML documentation will be in the build/doc/ directory. You might need to create the build/ directory if it doesn't exist yet.

The documentation can be also generated using the m.css Doxygen theme. Use Doxyfile-mcss for a local build, the Doxyfile-public is meant for the publicly available documentation at http://doc.magnum.graphics/corrade/. The resulting documentation will be either in build/doc-mcss/ or build/doc-public/.

Building examples

The library comes with a handful of examples, contained in the src/examples/ directory. Documentation for them is available on the Examples page. The examples require Corrade to be installed and they are built separately:

mkdir build-examples && cd build-examples
cmake ../src/examples
cmake --build .

Cross-compiling for Windows RT

As said above, you need a native build of the corrade-rc executable. The below script assumes that a native Corrade build is installed in C:/Sys and the installation path for WinRT is in C:/Sys-winrt. You need at least Windows 8.1, Visual Studio 2015 and Windows 8.1 Store/Phone SDK installed. Because WinRT applications run in a sandbox, it's recommended to build the library as static so you don't have to bundle all the DLLs. Example:

mkdir build-winrt && cd build-winrt
cmake .. ^
    -DCORRADE_RC_EXECUTABLE="C:/Sys/bin/corrade-rc.exe" ^
    -DCMAKE_INSTALL_PREFIX="C:/Sys-winrt" ^
    -DBUILD_STATIC=ON ^
    -DCMAKE_SYSTEM_NAME=WindowsStore ^
    -DCMAKE_SYSTEM_VERSION=8.1 ^
    -G "Visual Studio 14 2015"
cmake --build .

Change WindowsStore to WindowsPhone if you want to build for Windows Phone instead. When done, you can install the package using cmake --build . --target install to make it available to depending projects.

Cross-compiling for Windows using MinGW-w64

You will need a MinGW-w64 version of the compiler and libraries, i.e. the mingw-w64-gcc ArchLinux package.

Create build directories for 32b/64b build and run cmake and the build command in them. You may need to modify the basic-mingw-w64-32.cmake / basic-mingw-w64-64.cmake files and CMAKE_INSTALL_PREFIX to suit your distribution filesystem hierarchy.

mkdir build-mingw-w64-32 && cd build-mingw-w64-32
cmake .. \
    -DCMAKE_TOOLCHAIN_FILE=../toolchains/archlinux/basic-mingw-w64-32.cmake \
    -DCMAKE_INSTALL_PREFIX=/usr/i686-w64-mingw32
cmake --build .

mkdir build-mingw-w64-64 && cd build-mingw-w64-64
cmake .. \
    -DCMAKE_TOOLCHAIN_FILE=../toolchains/archlinux/basic-mingw-w64-64.cmake \
    -DCMAKE_INSTALL_PREFIX=/usr/x86_64-w64-mingw32
cmake --build .

Then you can install the package using cmake --build . --target install to make it available to depending projects.

Cross-compiling for Emscripten

You will need Emscripten installed and configured. The toolchains require CMake 3.7 or newer to properly set compiler and linker flags.

There are two toolchain files. The generic/Emscripten.cmake is for the classical (asm.js) build, the generic/Emscripten-wasm.cmake is for a WebAssembly build. Don't forget to adapt EMSCRIPTEN_PREFIX variable in generic/Emscripten*.cmake to path where Emscripten is installed; you can also pass it explicitly on command-line using -DEMSCRIPTEN_PREFIX. Default is /usr/lib/emscripten. Emscripten supports dynamic libraries only to simplify porting and they are generally slower, thus BUILD_STATIC is implicitly enabled.

Then create build directory and run cmake and the build command in it. Be sure to set CMAKE_INSTALL_PREFIX to a path contained in EMSCRIPTEN_TOOLCHAIN_PATH.

mkdir build-emscripten && cd build-emscripten
cmake .. \
    -DCMAKE_TOOLCHAIN_FILE="../toolchains/generic/Emscripten.cmake" \
    -DCMAKE_BUILD_TYPE=Release \
    -DCMAKE_INSTALL_PREFIX=/usr/lib/emscripten/system
cmake --build .

Then you can install the library using cmake --build . --target install to make it available to depending projects.

If you have Node.js installed, you can also build and run unit tests using ctest. See the BUILD_TESTS option above.

For ArchLinux there are also prepared package files in package/archlinux, named PKGBUILD-emscripten and PKGBUILD-emscripten-wasm, see above for more information. The first file is for optimized asm.js build (slow to compile), the second for a WebAssembly build.

Cross-compiling for iOS

You will need macOS with Xcode installed.

Set CMAKE_OSX_ROOT to the SDK you want to target and enable all desired architectures in CMAKE_OSX_ARCHITECTURES. Set CMAKE_INSTALL_PREFIX to the prefix where you want to store your iOS dependencies for other projects.

As every application is in its own sandbox, it doesn't make sense to build shared libraries (although it is supported). Enable BUILD_STATIC to build static libraries.

mkdir build-ios && cd build-ios
cmake .. \
    -DCMAKE_TOOLCHAIN_FILE=../toolchains/generic/iOS.cmake \
    -DCMAKE_OSX_SYSROOT=/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk \
    -DCMAKE_OSX_ARCHITECTURES="arm64;armv7;armv7s" \
    -DCMAKE_INSTALL_PREFIX=~/ios-libs \
    -DBUILD_STATIC=ON \
    -G Xcode
cmake --build .

Then you can install the library using cmake --build . --target install to make it available to depending projects.

Cross-compiling for Android

You will need Android NDK installed and configured. CMake 3.7 is required, as it has Android support builtin. The supported toolchain is now Clang with libc++, GCC is not supported anymore.

Create a build directory and run cmake and the build command in it. Set CMAKE_SYSTEM_NAME to Android to enable the crosscompilation, CMAKE_ANDROID_NDK_TOOLCHAIN_VERSION and CMAKE_ANDROID_STL_TYPE to use Clang with libc++, CMAKE_SYSTEM_VERSION to minimal API version level you wish to use and CMAKE_ANDROID_ARCH_ABI to target platform ABI. Check the CMake Android cross-compiling documentation for further information.

If you set CMAKE_INSTALL_PREFIX to /usr subdirectory of the particular Android platform sysroot, the package will get found automatically when compiling subprojects. Gradle and other Android buildsystems expect platform-independent includes and other files to be stored in a central location, you can set CORRADE_INCLUDE_INSTALL_PREFIX to /usr subdirectory of the global NDK sysroot. Another option is to explicitly set CMAKE_PREFIX_PATH to the install location in depending projects.

Note that BUILD_STATIC is implicitly enabled, because manually loading all depending shared libraries using JNI would be too inconvenient.

mkdir build-android-arm64 && cd build-android-arm64
cmake .. \
    -DCMAKE_SYSTEM_NAME=Android \
    -DCMAKE_SYSTEM_VERSION=22 \
    -DCMAKE_ANDROID_ARCH_ABI=arm64-v8a \
    -DCMAKE_ANDROID_NDK_TOOLCHAIN_VERSION=clang \
    -DCMAKE_ANDROID_STL_TYPE=c++_static \
    -DCMAKE_BUILD_TYPE=Release \
    -DCMAKE_INSTALL_PREFIX=/opt/android-ndk/platforms/android-22/arch-arm64/usr \
    -DCORRADE_INCLUDE_INSTALL_PREFIX=/opt/android-ndk/sysroot/usr
cmake --build .

Then you can install the library using cmake --build . --target install to make it available to depending projects.

For ArchLinux there is also a prepared package file in package/archlinux/, named PKGBUILD-android-arm64; see above for more information.

Travis

In package/ci/ there is a travis.yml file with Linux GCC 4.7, macOS, iOS, Emscripten, Android, AddressSanitizer and ThreadSanitizer configuration. Online at https://travis-ci.org/mosra/corrade.

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/corrade.

Codecov.io

Linux, macOS and Windows MinGW builds contribute to a combined code coverage report, available online at https://codecov.io/gh/mosra/corrade.