Using Corrade with CMake

Guide how to find and use Corrade with CMake build system.

Contents

Corrade uses CMake build system for both building and integration into your projects. The logic is in module FindCorrade.cmake distributed with the library in modules/ directory, you are encouraged to copy it into your project and add path to the file to CMAKE_MODULE_PATH. Otherwise, if CMake won't be able to find this file in predefined locations, it will error out even if Corrade might be installed on the system.

Note that the module file is updated as the library evolves, you are encouraged to update your copy from time to time to avoid strange building issues.

If you installed the library to non-standard location (other than /usr, e.g. /home/xyz/projects), set CMAKE_PREFIX_PATH to that directory to help CMake find it.

Basic usage is:

find_package(Corrade REQUIRED)

This module tries to find the base Corrade library and then defines the following:

  • Corrade_FOUND — Whether the base library was found
  • CORRADE_LIB_SUFFIX_MODULE — Path to CorradeLibSuffix.cmake module, which tries to autodetect value of LIB_SUFFIX variable

This command will try to find only the base library, not the optional components, which are:

Example usage with specifying additional components is:

find_package(Corrade REQUIRED Utility TestSuite)

For each component is then defined:

  • Corrade_*_FOUND — Whether the component was found
  • Corrade::* — Component imported target

The package is found if either debug or release version of each library is found. If both debug and release libraries are found, proper version is chosen based on actual build configuration of the project (i.e. Debug build is linked to debug libraries, Release build to release libraries).

Corrade conditionally defines CORRADE_IS_DEBUG_BUILD preprocessor variable in case build configuration is Debug (not Corrade itself, but build configuration of the project using it). Useful e.g. for selecting proper plugin directory.

Corrade defines the following custom target properties:

  • CORRADE_CXX_STANDARD — C++ standard to require when compiling given target. Does nothing if CMAKE_CXX_FLAGS already contains particular standard setting flag or if given target contains CXX_STANDARD property. Allowed value is 11, 14 or 17. See also the CORRADE_CXX_STANDARD C++ macro, which allows for checking of used C++ standard in a portable way.
  • INTERFACE_CORRADE_CXX_STANDARD — C++ standard to require when using given target. Does nothing if CMAKE_CXX_FLAGS already contains particular standard setting flag or if given target contains CMAKE_CXX_STANDARD property. Allowed value is 11, 14 or 17.
  • CORRADE_USE_PEDANTIC_FLAGS — Enable additional compiler/linker flags. Boolean. The particular flags are contained in the CORRADE_PEDANTIC_COMPILER_OPTIONS and CORRADE_PEDANTIC_COMPILER_DEFINITIONS variables.

These properties are inherited from directory properties, meaning that if you set them on directories, they get implicitly set on all targets in given directory (with a possibility to do target-specific overrides). All Corrade libraries have the INTERFACE_CORRADE_CXX_STANDARD property set to 11, meaning that you will always have at least C++11 enabled once you link to any Corrade library.

Features of found Corrade library are exposed in these variables, they are also available as preprocessor variables if you include Corrade/Corrade.h:

  • CORRADE_GCC47_COMPATIBILITY — Defined if compiled with compatibility mode for GCC 4.7
  • CORRADE_MSVC2017_COMPATIBILITY — Defined if compiled with compatibility mode for MSVC 2017
  • CORRADE_MSVC2015_COMPATIBILITY — Defined if compiled with compatibility mode for MSVC 2015
  • CORRADE_BUILD_DEPRECATED — Defined if compiled with deprecated APIs included
  • CORRADE_BUILD_STATIC — Defined if compiled as static libraries. Default are shared libraries.
  • CORRADE_TARGET_UNIX — Defined if compiled for some Unix flavor (Linux, BSD, macOS, iOS, Android, ...)
  • CORRADE_TARGET_APPLE — Defined if compiled for Apple platforms
  • CORRADE_TARGET_IOS — Defined if compiled for iOS (device or simulator)
  • CORRADE_TARGET_IOS_SIMULATOR — Defined if compiled for iOS Simulator
  • CORRADE_TARGET_WINDOWS — Defined if compiled for Windows
  • CORRADE_TARGET_WINDOWS_RT — Defined if compiled for Windows RT
  • CORRADE_TARGET_EMSCRIPTEN — Defined if compiled for Emscripten
  • CORRADE_TARGET_ANDROID — Defined if compiled for Android
  • CORRADE_PLUGINMANAGER_NO_DYNAMIC_PLUGIN_SUPPORT — Defined if PluginManager doesn't support dynamic plugin loading due to platform limitations
  • CORRADE_TESTSUITE_TARGET_XCTEST — Defined if TestSuite is targetting Xcode XCTest
  • CORRADE_UTILITY_USE_ANSI_COLORS — Defined if ANSI escape sequences are used for colored output with Utility::Debug on Windows

Besides all the defines above, the Corrade/Corrade.h additionally defines CORRADE_TARGET_X86 and CORRADE_TARGET_ARM based on target architecture. They are not exposed in CMake because the meaning is unclear on platforms with multi-architecture binaries.

Workflows without imported targets are deprecated and the following variables are included just for backwards compatibility and only if CORRADE_BUILD_DEPRECATED is enabled:

  • CORRADE_*_LIBRARIES — Expands to Corrade::* target. Use Corrade::* target directly instead.
  • CORRADE_CXX_FLAGS — Additional pedantic compile flags. Use CORRADE_USE_PEDANTIC_FLAGS per-target property or CORRADE_PEDANTIC_COMPILER_DEFINITIONS / CORRADE_PEDANTIC_COMPILER_OPTIONS list variables instead.

Note that each namespace contains more detailed guide how to use given library with CMake.

Other CMake modules

The modules/ directory contains more useful CMake modules:

  • FindNodeJs.cmake — CMake module for finding Node.js. Copy this to your module directory if you want to run TestSuite unit tests when building for Emscripten.

Macros and functions

Add unit test using Corrade's TestSuite

corrade_add_test(<test name>
                 <sources>...
                 [LIBRARIES <libraries>...]
                 [FILES <files>...]
                 [ARGUMENTS <arguments>...])

Test name is also executable name. You can use LIBRARIES to specify libraries to link with instead of using target_link_libraries(). The Corrade::TestSuite target is linked automatically to each test. Note that the enable_testing() function must be called explicitly. Arguments passed after ARGUMENTS will be appended to the test command line. ARGUMENTS are supported everywhere except when CORRADE_TESTSUITE_TARGET_XCTEST is enabled.

You can list files needed by the test in the FILES section. If given filename is relative, it is treated relatively to CMAKE_CURRENT_SOURCE_DIR. The files are added to the REQUIRED_FILES target property. On Emscripten they are bundled to the executable and available in the virtual filesystem root. On Android they are copied along the executable to the target. In case of Emscripten and Android, if the file is absolute or contains .., only the leaf name is used. Alternatively you can have a filename formatted as <input>@<output>, in which case the <input> is treated as local filesystem location and <output> as remote/virtual filesystem location. The remote location can't be absolute or contain .. / @ characters.

Unless CORRADE_TESTSUITE_TARGET_XCTEST is set, test cases run on an iOS device are created as bundles with bundle identifier set to CMake project name by default. Use the cache variable CORRADE_TESTSUITE_BUNDLE_IDENTIFIER_PREFIX to change it to something else.

Compile data resources into application binary

corrade_add_resource(<name> <resources.conf>)

Depends on corrade-rc, which is part of Corrade utilities. This command generates resource data using given configuration file in current build directory. Argument name is name under which the resources can be explicitly loaded. Variable name contains compiled resource filename, which is then used for compiling library / executable. On CMake >= 3.1 the resources.conf file can contain UTF-8-encoded filenames. See Resource management for more information. Example usage:

corrade_add_resource(app_resources resources.conf)
add_executable(app source1 source2 ... ${app_resources})

Add dynamic plugin

corrade_add_plugin(<plugin name>
                   "<debug binary install dir>;<debug library install dir>"
                   "<release binary install dir>;<release library install dir>"
                   <metadata file>
                   <sources>...)

The macro adds preprocessor directive CORRADE_DYNAMIC_PLUGIN. Additional libraries can be linked in via target_link_libraries(plugin_name ...). On DLL platforms, the plugin DLLs and metadata files are put into <debug binary install dir> /<release binary install dir> and the *.lib files into <debug library install dir> /<release library install dir>. On non-DLL platforms everything is put into <debug library install dir>/<release library install dir>.

corrade_add_plugin(<plugin name>
                   <debug install dir>
                   <release install dir>
                   <metadata file>
                   <sources>...)

Unline the above version this puts everything into <debug install dir> on both DLL and non-DLL platforms. If <debug install dir> is set to CMAKE_CURRENT_BINARY_DIR (e.g. for testing purposes), the files are copied directly, without the need to perform install step. Note that the files are actually put into configuration-based subdirectory, i.e. ${CMAKE_CURRENT_BINARY_DIR}/${CMAKE_CFG_INTDIR}. See documentation of CMAKE_CFG_INTDIR variable for more information.

Add static plugin

corrade_add_static_plugin(<plugin name>
                          "<binary install dir>;<library install dir>"
                          <metadata file>
                          <sources>...)

The macro adds preprocessor directive CORRADE_STATIC_PLUGIN. Additional libraries can be linked in via target_link_libraries(plugin_name ...). The <binary install dir> is ignored and included just for compatibility with the corrade_add_plugin() command, everything is installed into <library install dir>. Note that plugins built in debug configuration (e.g. with CMAKE_BUILD_TYPE set to Debug) have -d suffix to make it possible to have both debug and release plugins installed alongside each other.

corrade_add_static_plugin(<plugin name>
                          <install dir>
                          <metadata file>
                          <sources>...)

Equivalent to the above with <library install dir> set to <install dir>. If <install dir> is set to CMAKE_CURRENT_BINARY_DIR (e.g. for testing purposes), no installation rules are added.

Find corresponding DLLs for library files

corrade_find_dlls_for_libs(<output variable> <libs>...)

Available only on Windows, for all *.lib files tries to find corresponding DLL file. Useful for bundling dependencies for e.g. WinRT packages.