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 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
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:
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:
AssimpImporter— AssimpImporter plugin
ColladaImporter— ColladaImporter plugin
DdsImporter— DdsImporter plugin
DevIlImageImporter— DevIlImageImporter plugin
DrFlacAudioImporter— DrFlacAudioImporter plugin
DrWavAudioImporter— DrWavAudioImporter plugin
FreeTypeFont— FreeTypeFont plugin
HarfBuzzFont— HarfBuzzFont plugin
JpegImporter— JpegImporter plugin
MiniExrImageConverter— MiniExrImageConverter plugin
OpenGexImporter— OpenGexImporter plugin
PngImageConverter— PngImageConverter plugin
PngImporter— PngImporter plugin
StanfordImporter— StanfordImporter plugin
StbImageConverter— StbImageConverter plugin
StbImageImporter— StbImageImporter plugin
StbTrueTypeFont— StbTrueTypeFont plugin
StbVorbisAudioImporter— StbVorbisAudioImporter plugin
TinyGltfImporter— TinyGltfImporter plugin
Some plugins expose their internal state through separate libraries. The libraries are:
OpenDdl— OpenDdl library
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
Workflows without imported targets are deprecated and the following variables are included just for backwards compatibility and only if MAGNUM_
MAGNUMPLUGINS_*_LIBRARIES— Expands to
MagnumPlugins::*target directly instead.
See also Magnum usage with CMake for more information.
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::