Using Corrade with CMake

Using Corrade that was externally built and installed

The main logic is in the FindCorrade.cmake module distributed with the engine in the modules/ directory, you are encouraged to copy it into your project and add path to the file to CMAKE_MODULE_PATH:

# Path where FindCorrade.cmake can be found, adapt as needed
set(CMAKE_MODULE_PATH "${PROJECT_SOURCE_DIR}/modules/" ${CMAKE_MODULE_PATH})

find_package(Corrade REQUIRED ...) # see below

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. There are other Find modules that you might need for particular features or platforms, see the full list below. Each library that needs one of the extra modules also mentions the requirement in its documentation. Note that the module files areupdated as the library evolves, you are encouraged to update your copies 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.

Using Corrade as a CMake subproject

A self-contained alternative to a shared instance of the libraries, is to add the repositories directly into your project (as Git submodules, bundling downloaded archives etc.), and then to use CMake's add_subdirectory() command to compile them on demand. With this approach, you don't need to care about manually installing Corrade, however the usual tradeoffs when bundling code apply — slower full rebuilds, IDEs having more to parse etc. In this case, build-time options can be set() before calling add_subdirectory(). Note that, unless you require CMake 3.13 at least, it's necessary to use the CACHE ... FORCE arguments in order to have the options set properly. For example:

set(CORRADE_WITH_TESTSUITE OFF CACHE BOOL "" FORCE) # disable what you don't use
add_subdirectory(corrade EXCLUDE_FROM_ALL) # so only things you use are built

find_package(Corrade REQUIRED ...) # see below

Note that the use of add_subdirectory() does not replace the configuration necessary for an installed version of Corrade. The modules/ directory and calls to find_package() are needed in both the installed and the subproject case for a properly configured environment.

To simplify your project setup, the subproject globally configures CMAKE_RUNTIME_OUTPUT_DIRECTORY and friends to <CONFIG>/bin / <CONFIG>/lib directories inside your build directory. This makes the subproject workflow easier when dynamically-loaded plugins are involved; and on Windows it makes it possible to run built executables without having to do a $PATH setup for dependency DLLs. If your project already configures CMAKE_{RUNTIME,LIBRARY,ARCHIVE}_OUTPUT_DIRECTORY, those will get used instead (and you can also set your own output directories after the add_subdirectory() call, which will make Corrade keep the above). If you want to disable this behavior altogether and keep all executables and libraries in their implicit locations, set those variables to an empty string (as opposed to nothing at all, which is the same as if the variable is not set) — Corrade will detect and respect that:

# I'm happy with having binaries scattered around the build dir
set(CMAKE_RUNTIME_OUTPUT_DIRECTORY "")
set(CMAKE_LIBRARY_OUTPUT_DIRECTORY "")
set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY "")

add_subdirectory(corrade EXCLUDE_FROM_ALL)

Finding the package and its components

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
• CORRADE_INCLUDE_INSTALL_PREFIX — Prefix where to put platform-independent include and other files, defaults to .. If a relative path is used, it's relative to CMAKE_INSTALL_PREFIX.

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

• Containers — Containers library
• Interconnect — Interconnect library
• Main — Main library
• PluginManager — PluginManager library
• TestSuite — TestSuite library
• Utility — Utility library
• rc — corrade-rc executable

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 the 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 either of the CXX_STANDARD or COMPILE_FEATURES properties. Allowed value is 11, 14, 17 or 20. 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, 17 or 20.
• 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_MSVC_COMPATIBILITY — Defined if compiled with compatibility mode for MSVC 2019+ without the /permissive- flag set
• 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 features included
• CORRADE_BUILD_STATIC — Defined if compiled as static libraries. Default are shared libraries.
• CORRADE_BUILD_STATIC_UNIQUE_GLOBALS — Defined if static libraries keep their globals unique even across different shared libraries. Enabled by default for static builds.
• CORRADE_BUILD_MULTITHREADED — Defined if compiled in a way that makes it possible to safely use certain Corrade features simultaneously in multiple threads.
• CORRADE_BUILD_CPU_RUNTIME_DISPATCH — Defined if built with code paths optimized for multiple architectres with the best matching variant selected at runtime based on detected CPU features
• 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_TARGET_GCC — Defined if compiling with GCC or GCC-compatible Clang
• CORRADE_TARGET_CLANG — Defined if compiling with Clang or any of its variants
• CORRADE_TARGET_APPLE_CLANG — Defined if compiling with Apple's Clang
• CORRADE_TARGET_CLANG_CL — Defined if compiling with Clang-CL (Clang with a MSVC frontend)
• CORRADE_TARGET_MSVC — Defined if compiling with MSVC or Clang with a MSVC frontend
• CORRADE_TARGET_MINGW — Defined if compiling under MinGW
• CORRADE_CPU_USE_IFUNC - Defined if GNU IFUNC is allowed to be used for runtime dispatch in the Cpu library
• 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 targeting 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_CXX_STANDARD, CORRADE_TARGET_X86 and related x86-specific variables, CORRADE_TARGET_ARM and related ARM-specific variables, CORRADE_TARGET_POWERPC, CORRADE_TARGET_WASM and related WebAssembly-specific variables, CORRADE_TARGET_32BIT, CORRADE_TARGET_BIG_ENDIAN, CORRADE_TARGET_LIBCXX, CORRADE_TARGET_LIBSTDCXX and CORRADE_TARGET_DINKUMWARE based on target architecture, standard and STL used. They are not exposed in CMake because the meaning is unclear with projects that mix more different C++ standards / STL implementations or on platforms with multi-architecture binaries.

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

Other CMake modules

The modules/ directory of Corrade sources contains more useful CMake modules. If a library requires presence of any of these, it mentions them in its usage documentation.

• 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

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

corrade_add_resource(<name> <input> [SINGLE])

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

corrade_add_resource(binary_contents binary.dat SINGLE)
# resourceData_binary_contents and resourceSize_binary_contents should be then
# directly referenced by application sources
add_executable(app ... ${binary_contents})

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

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

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

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

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