Getting started » Plugin usage with CMake

Guide how to find and use static Magnum plugins with CMake build system.

Contents

If you are going to use dynamic plugins (the default) via plugin manager, they don't need to be handled via CMake. The manager will look for them at runtime at specified location and loads them dynamically. However, if they are built as static (see Downloading and building plugins for more information), they need to be linked into the executable and then explicitly imported. Also if you are going to use them as dependencies, you need to find the dependency and then link to it.

The logic is in module FindMagnumPlugins.cmake distributed in plugin repository in modules/ directory, you are encouraged to copy it into your project and add path to the files to CMAKE_MODULE_PATH. Otherwise, if CMake won't be able to find this file in predefined locations, it will error out even if Magnum plugins 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 or its dependencies to non-standard location (other than /usr, e.g. /home/xyz/projects), set CMAKE_PREFIX_PATH to that directory to help CMake find it. You can enter more different dirs if you separate them with semicolons.

Basic usage is:

find_package(MagnumPlugins REQUIRED)

This command tries to find Magnum plugins and then defines:

  • MagnumPlugins_FOUND — Whether Magnum plugins were found

This command will not try to find any actual plugin. The plugins are:

Some plugins expose their internal state through separate libraries. The libraries are:

Note that each plugin class / library namespace contains more detailed information about dependencies, availability on particular platform and also guide how to enable given library in build and use it with CMake.

Example usage with specifying the plugins is:

find_package(MagnumPlugins REQUIRED FreeTypeFont PngImporter)

For each plugin is then defined:

  • MagnumPlugins_*_FOUND — Whether the plugin was found
  • MagnumPlugins::* — Plugin imported target

The package is found if either debug or release version of each requested plugin is found. If both debug and release plugins are found, proper version is chosen based on actual build configuration of the project (i.e. Debug build is linked to debug plugins, Release build to release plugins). See Usage with CMake for more information about autodetection of MAGNUM_PLUGINS_DIR.

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

  • MAGNUMPLUGINS_*_LIBRARIES — Expands to MagnumPlugins::* target. Use MagnumPlugins::* target directly instead.

See also Magnum usage with CMake for more information.

Other CMake modules

The modules/ directory contains more useful CMake modules:

  • FindFreetype.cmake — CMake module for finding FreeType. This is a forked version of the upstream module that works properly with static builds of FreeType, linking all its dependencies. Copy this to your module directory if you built the Text::FreeTypeFont plugin as static and it was also linked to a static FreeType build.
  • FindHarfBuzz.cmake — CMake module for finding HarfBuzz. Copy this to your module directory if you want to find and link to Text::HarfBuzzFont.

See also relevant section for the main Magnum project.

« Usage with CMake | Getting started | Integration library usage with CMake »