Getting started » Plugin usage with CMake

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

If you are going to use dynamic plugins (the default) via a plugin manager, they don't need to be linked via CMake as the manager will look for them at runtime at specified location and loads them dynamically — but if you are using them via a CMake subproject, additional steps need to be taken so CMake knows you need them to be built.

If plugins 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.

Using Magnum Plugins that were externally built and installed

The main logic is in the FindMagnumPlugins.cmake module distributed in the modules/ directory of the plugins repository, you are encouraged to copy it into your project and add path to the files to CMAKE_MODULE_PATH:

# Path where FindMagnumPlugins.cmake can be found, adapt as needed
set(CMAKE_MODULE_PATH "${PROJECT_SOURCE_DIR}/modules/" ${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. There are other Find modules that you might need for particular features or platforms, see the list below. Note that the module files are updated 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 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.

Using Magnum Plugins as a CMake subproject

Continuing from Using Magnum as a CMake subproject, adding Magnum Plugins is very similar. Again, the Plugins build-time options have to be specified before the subdirectory gets added:

...

set(WITH_STBIMAGEIMPORTER ON CACHE BOOL "" FORCE) # enable what you need
add_subdirectory(magnum-plugins EXCLUDE_FROM_ALL)

find_package(MagnumPlugins REQUIRED ...) # see below

Please note that in case of the (by default) dynamic plugins, because these are loaded at runtime, CMake doesn't know we need them to be built — one option is to list them explicitly like shown below, another (but uglier) is to not use EXCLUDE_FROM_ALL on the magnum subdirectory, so everything is always built implicitly.

set(WITH_STBIMAGEIMPORTER ON CACHE BOOL "" FORCE)
set(WITH_TINYGLTFIMPORTER ON CACHE BOOL "" FORCE)
add_subdirectory(magnum-plugins EXCLUDE_FROM_ALL)

# So the StbImageImporter / TinyGltfImporter gets built implicitly
add_custom_target(plugins ALL DEPENDS
    MagnumPlugins::StbImageImporter
    MagnumPlugins::TinyGltfImporter)

Finding the package and its components

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.

See also Magnum usage with CMake for more information.

Other CMake modules

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

See also relevant section for the main Magnum project.