Downloading and building Corrade

Guide how to download and build Corrade on different platforms.

Minimal set of tools required for building and using Corrade is:

  • C++ compiler with good C++11 support. Compilers which are tested to have everything needed are GCC >= 4.8.1, Clang >= 6 (or equivalently Apple Clang** >= 10) and MSVC >= 2015. For Windows you can also use Clang-CL** or MinGW-w64.
  • CMake >= 3.5

CMake is not a strict requirement, it's also possible to use Corrade with custom buildsystems. Building Corrade without CMake is possible if you recreate its buildsystem yourself, but it's neither supported nor recommended.

Single-header libraries

Selected Corrade functionality is available as single-header libraries for easier integration into your projects. See Single-header libraries for more information.

Using Corrade as a CMake subproject

Corrade can be bundled in your project with the add_subdirectory() CMake command. See Using Corrade as a CMake subproject for more information.

Prepared packages

The easiest way to install Corrade is to use one of the ready-made packages for your platform of choice. See Manual build if you want to have more control and Cross-compiling for cross-compiling to other platforms.

Conan package

Starting from version 2018.10, stable releases of Corrade are available in the Conan package manager. You can install a stable version by checking out the Git repository and executing the conan create command:

git clone https://github.com/mosra/corrade && cd corrade
conan create . magnum/stable -tf package/conan/test_package

The -tf argument is optional and ensures the package is built correctly by executing a simple test file.

Hunter package

Starting from version 2018.10, stable releases of Corrade are available in the Hunter CMake-driven package manager. See the corrade package documentation for details.

Vcpkg package

Corrade is available as a Vcpkg package. After setting up Vcpkg as described in their README, it is recommended to set the "default triplet". You can do this by setting the VCPKG_DEFAULT_TRIPLET variable, e.g. to x64-windows — refer to the documentation on triplets for other options.

You can then install latest stable version of Corrade like this:

vcpkg install corrade

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 CORRADE_WITH_* options but lowercase, e.g.:

vcpkg install corrade[pluginmanager,testsuite]

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

vcpkg install corrade[*]

For more information, see the documentation on feature packages.

Packages installed using Vcpkg can be used in Visual Studio straight away — all you need to do is to #include the headers you want and 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 Vcpkg to pass additional flags to CMake during installation of a package, use the edit command, e.g. 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 https://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.zst

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

MSYS2 packages

MSYS2 package for the latest stable release is maintained in the official repos. Installing is as simple as this:

pacman -S mingw-w64-x86_64-corrade # or mingw-w64-i686-corrade

Similarly to ArchLinux, there is one package in the package/msys/corrade 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. Example usage:

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

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

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

But often you may want to install the latest Git revision instead:

brew install --HEAD mosra/magnum/corrade

# If already installed, use the following to upgrade
brew upgrade --fetch-HEAD mosra/magnum/corrade

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

Manual build

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 https://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 -DCORRADE_BUILD_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 MSVC, clang-cl 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).

Using Visual Studio

On Windows CMake by default creates Visual Studio project files.

The most straightforward way to build and install the library is again via the command line. The bonus point is that you don't even need to wait for Visual Studio to load:

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

If you want to build and install from Visual Studio, just open the Corrade.sln project file generated by CMake in the build directory.

Using QtCreator

On Windows, besides other IDEs, you can also use QtCreator (just QtCreator, you don't need the full Qt SDK). Configure it to use CMake and either the MSVC compiler or MinGW-w64 and then just open project's root CMakeLists.txt file within it. QtCreator then asks you where to create build directory, allows you to specify initial CMake parameters (e.g. CMAKE_PREFIX_PATH and CMAKE_INSTALL_PREFIX) and then you can just press Configure and everything is ready to be built.

After the initial import you might want to reconfigure some CMake variables, see below for more information.

Installation to given prefix can be done from within QtCreator by adding a new make install build rule.

Enabling or disabling features

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

  • CORRADE_WITH_INTERCONNECT — Build the Interconnect library. Enables also building of the Utility library.
  • CORRADE_WITH_MAIN — build The Main library. Enabled automatically if CORRADE_WITH_TESTSUITE is enabled.
  • CORRADE_WITH_PLUGINMANAGER — Build the PluginManager library. Enables also building of the Utility library.
  • CORRADE_WITH_TESTSUITE — Build the TestSuite library. Enables also building of the Utility and Main libraries.
  • CORRADE_WITH_UTILITY — Build the Utility library. Enables also building of the corrade-rc executable. Enabled automatically if CORRADE_WITH_INTERCONNECT, CORRADE_WITH_PLUGINMANAGER or CORRADE_WITH_TESTSUITE is enabled. The Containers library is built along with this library.
  • CORRADE_WITH_RC — Build the corrade-rc utility. Enabled automatically if CORRADE_WITH_UTILITY or anything depending on it is enabled. It's possible to build just this executable without anything else, for example when crosscompiling.

Options controlling the build:

  • CORRADE_BUILD_STATIC — Build all libraries as static. Default is shared, except on platforms such as Android or Emscripten that don't support dynamic linking.
  • CORRADE_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.
  • CORRADE_BUILD_STATIC_UNIQUE_GLOBALS — Build static libraries in a way that keeps their globals unique even across different shared libraries. Enabled by default for static builds. May introduce additional overhead on some platforms, disable if you will only link static libraries to one final executable and won't use any dynamic plugins.
  • CORRADE_BUILD_STATIC_UNIQUE_GLOBALS_DLL_NAME — Name of a DLL in which to search for unique globals symbols. By default, the main executable is searched, which works in most cases except when Corrade is only linked to a DLL, such as in Python modules. The name is expected to be just a filename without any path. Used only on Windows and only if CORRADE_BUILD_STATIC_UNIQUE_GLOBALS is enabled.
  • CORRADE_BUILD_DEPRECATED — Build with deprecated features included. Enabled by default to preserve backwards compatibility, disabling it forces you to update your code whenever there's a breaking change in the APIs or in library behavior. It's however recommended to have this option disabled when deploying a final application as it can result in smaller binaries.
  • CORRADE_BUILD_MULTITHREADED — Makes it possible to safely use certain Corrade features simultaneously in multiple threads. Enabled by default, disable if you don't need this and don't want to pay potential performance penalties coming from thread-local variables.
  • CORRADE_BUILD_CPU_RUNTIME_DISPATCH — Build with performance-critical code paths optimized for multiple architectures (such as SSE or AVX on x86), with the best matching variant selected at runtime based on detected CPU features. If not enabled, the library is built with just a single variant that's picked at compile time depending on target architecture flags being passed to the compiler. Enabled by default on platforms that support GNU IFUNC, which is currently only Linux with glibc and Android with API 30+. See also the CORRADE_CPU_USE_IFUNC option below and Automatic cached dispatch for details and information about performance tradeoffs.

Platform-specific options:

  • CORRADE_CPU_USE_IFUNC — Allow GNU IFUNC to be used for runtime dispatch in the Cpu library. Available only on platforms that support it, which is currently only Linux with glibc and Android with API 30+, and there enabled by default unless a problematic case is detected that may cause it to misbehave. See Automatic cached dispatch for details and information about performance tradeoffs.
  • CORRADE_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.
  • CORRADE_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.

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 a standards-conforming compiler. However, for portability, compatibility mode for some compilers is provided:

  • CORRADE_MSVC_COMPATIBILITY — Compiling with compatibility mode for Microsoft Visual C++ 2019+ without the /permissive- flag set. Enabled implicitly if MSVC (but not clang-cl) is detected. You can set it to OFF but then you're required to specify /permissive- for all code using Corrade.
  • CORRADE_MSVC2017_COMPATIBILITY — Compiling with compatibility mode for Microsoft Visual C++ 2017. Enabled implicitly if MSVC 2017 is detected, implies CORRADE_MSVC_COMPATIBILITY.
  • CORRADE_MSVC2015_COMPATIBILITY — Compiling with compatibility mode for Microsoft Visual C++ 2015. Enabled implicitly if MSVC 2015 is detected, implies CORRADE_MSVC2017_COMPATIBILITY and CORRADE_MSVC_COMPATIBILITY.

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. On Android, if CMAKE_INSTALL_PREFIX points to the NDK sysroot, it gets automatically set to /${CMAKE_ANDROID_ARCH_TRIPLE}/${CMAKE_SYSTEM_VERSION} to put the binaries to correct location for given architecture and API level version.

The following variables are deprecated and provided only for backwards compatibility if CORRADE_BUILD_DEPRECATED isn't disabled.

  • CORRADE_INCLUDE_INSTALL_PREFIX — Overrides location where platform-independent include files, CMake scripts and other files are installed. For NDK versions before r19, CMake on Android by default searched for binaries in <ndk>/platforms/android-<api>/arch-<arch>/usr based on target API and platform, but for headers in a central location at <ndk>/toolchains/llvm/prebuilt/<host>/sysroot/usr and this was used to handle that case. Nowadays please use NDK r19 and newer, with the unified sysroot layout. Defaults to .. If a relative path is used, it's relative to CMAKE_INSTALL_PREFIX.

Building and running tests

Building of tests is controlled by the following options:

  • CORRADE_BUILD_TESTS — Builds unit tests. Disabled by default.
  • CORRADE_BUILD_TESTS_FORCE_CPU_POINTER_DISPATCH — Force unit tests to be built with function-pointer-based dispatch for CPU-dependent functionality, independently of the CORRADE_BUILD_CPU_RUNTIME_DISPATCH and CORRADE_CPU_USE_IFUNC options. This makes it possible for the tests to verify all variants instead of just one, and is enabled by default. The overhead from function pointers may however be significant on certain platforms, skewing benchmark results. Disable it to make the tests use the same dispatch method as the rest of the library.
  • CORRADE_BUILD_TESTS_FORCE_WASM_SIMD128 — Force Emscripten unit tests to be built with -msimd128 independenently of CMAKE_CXX_FLAGS. Together with CORRADE_BUILD_TESTS_FORCE_CPU_POINTER_DISPATCH and presence of the CORRADE_ENABLE_SIMD128 preprocessor variable this makes it possible for the tests to verify also WebAssembly SIMD variants of CPU-dependent functionality instead of just the scalar version if the rest of the library is built without -msimd128. Enabled by default if CORRADE_BUILD_TESTS_FORCE_CPU_POINTER_DISPATCH is set and Node.js version 15+ is found, which has finalized WebAssembly SIMD support. Disable to make the tests use the same compilation flags as the rest of the library.

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. It's not needed to install anything anywhere to run the tests.

By default the tests are compiled as part of the implicit ALL target. Use the CORRADE_TESTSUITE_TEST_TARGET CMake variable to create a dedicated target for building just the tests. See the documentation of the corrade_add_test() CMake macro for more information.

Building documentation

The documentation is generated using Doxygen with the m.css Doxygen theme and additionally uses LaTeX for math formulas. Use doc/conf.py for a local build, the doc/conf-public.py is meant for the publicly available documentation at https://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 cross-compiling you need to have the toolchains submodule updated. Either run the following command, or, if you build from source archive, download a snapshot of the toolchains repository from https://github.com/mosra/toolchains and put the contents in the toolchains/ subdirectory.

git submodule update --init

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 is below, you can omit specifying CORRADE_RC_EXECUTABLE if natively-built corrade-rc is accessible through PATH.

mkdir build-winrt && cd build-winrt
cmake .. ^
    -DCORRADE_RC_EXECUTABLE="C:/Sys/bin/corrade-rc.exe" ^
    -DCMAKE_INSTALL_PREFIX="C:/Sys-winrt" ^
    -DCORRADE_BUILD_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 CORRADE_BUILD_STATIC is implicitly enabled.

Then create build directory and run cmake and the build command in it. You can omit specifying CORRADE_RC_EXECUTABLE if natively-built corrade-rc is accessible through 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 \
    -DCORRADE_RC_EXECUTABLE=/path/to/corrade-rc
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 CORRADE_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. You can omit specifying CORRADE_RC_EXECUTABLE if natively-built corrade-rc is accessible through PATH.

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

Please note that CORRADE_BUILD_MULTITHREADED is supported only since Xcode 7.3 and doesn't work on i386 iOS Simulator, you need to disable it in order to build for older platforms.

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 \
    -DCORRADE_RC_EXECUTABLE=/path/to/corrade-rc \
    -DCORRADE_BUILD_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. The guide assumes NDK r19+ with unified Clang toolchain, which in turn requires at least CMake 3.16.

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_STL_TYPE to use 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. You can omit specifying CORRADE_RC_EXECUTABLE if natively-built corrade-rc is accessible through PATH. Note that CORRADE_BUILD_STATIC is implicitly enabled, because manually loading all depending shared libraries using JNI would be too inconvenient.

If you set CMAKE_INSTALL_PREFIX to /usr subdirectory of the particular Android platform sysroot (as shown below), Corrade's buildsystem will also pick a LIB_SUFFIX corresponding to a particular ABI and version, which in turn makes the package automatically discoverable when compiling depending projects, both with vanilla CMake and with Gradle. Another option is to explicitly set CMAKE_PREFIX_PATH to the install location in depending projects.

mkdir build-android-arm64 && cd build-android-arm64
cmake .. \
    -DCMAKE_SYSTEM_NAME=Android \
    -DCMAKE_SYSTEM_VERSION=24 \
    -DCMAKE_ANDROID_ARCH_ABI=arm64-v8a \
    -DCMAKE_ANDROID_STL_TYPE=c++_static \
    -DCMAKE_BUILD_TYPE=Release \
    -DCMAKE_INSTALL_PREFIX=/opt/android-ndk/toolchains/llvm/prebuilt/linux-x86_64/sysroot/usr \
    -DCMAKE_FIND_ROOT_PATH=/opt/android-ndk/toolchains/llvm/prebuilt/linux-x86_64/sysroot \
    -DCMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX=/aarch64-linux-android/24 \
    -DCORRADE_RC_EXECUTABLE=/path/to/corrade-rc
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.

Continuous Integration

CircleCI

In package/ci/ there is a circle.yml file with Linux GCC 4.8, Linux ARM64, macOS, Emscripten (except SIMD, see the file for details), AddressSanitizer, ThreadSanitizer, Android x86 and iOS x86_64 configuration. Online at https://circleci.com/gh/mosra/corrade.

AppVeyor

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