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. 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(MAGNUM_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(MAGNUM_WITH_STBIMAGEIMPORTER ON CACHE BOOL "" FORCE) set(MAGNUM_WITH_TINYGLTFIMPORTER ON CACHE BOOL "" FORCE) add_subdirectory(magnum-plugins EXCLUDE_FROM_ALL) # So the StbImageImporter / TinyGltfImporter gets built implicitly add_dependencies(your-app MagnumPlugins::StbImageImporter MagnumPlugins::TinyGltfImporter)
Each plugin class provides further information about additional steps needed for a CMake subproject setup.
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:
AssimpImporter— AssimpImporter pluginAstcImporter— AstcImporter pluginBasisImageConverter— BasisImageConverter pluginBasisImporter— BasisImporter pluginBcDecImageConverter— BcDecImageConverter pluginCgltfImporterdeprecated — CgltfImporter pluginDdsImporter— DdsImporter pluginDevIlImageImporter— DevIlImageImporter pluginDrFlacAudioImporter— DrFlacAudioImporter pluginDrMp3AudioImporter— DrMp3AudioImporter pluginDrWavAudioImporter— DrWavAudioImporter pluginEtcDecImageConverter— EtcDecImageConverter pluginFaad2AudioImporter— Faad2AudioImporter pluginFreeTypeFont— FreeTypeFont pluginGlslangShaderConverter— GlslangShaderConverter pluginGltfImporter— GltfImporter pluginGltfSceneConverter— GltfSceneConverter pluginHarfBuzzFont— HarfBuzzFont pluginIcoImporter— IcoImporter pluginJpegImageConverter— JpegImageConverter pluginJpegImporter— JpegImporter pluginKtxImageConverter— KtxImageConverter pluginKtxImporter— KtxImporter pluginMeshOptimizerSceneConverter— MeshOptimizerSceneConverter pluginMiniExrImageConverter— MiniExrImageConverter pluginOpenExrImageConverter— OpenExrImageConverter pluginOpenExrImporter— OpenExrImporter pluginOpenGexImporter— OpenGexImporter pluginPngImageConverter— PngImageConverter pluginPngImporter— PngImporter pluginPrimitiveImporter— PrimitiveImporter pluginSpirvToolsShaderConverter— SpirvToolsShaderConverterSpngImporter— SpngImporter pluginStanfordImporter— StanfordImporter pluginStanfordSceneConverter— StanfordSceneConverter pluginStbDxtImageConverter— StbDxtImageConverter pluginStbImageConverter— StbImageConverter pluginStbImageImporter— StbImageImporter pluginStbResizeImageConverter— StbResizeImageConverter pluginStbTrueTypeFont— StbTrueTypeFont pluginStbVorbisAudioImporter— StbVorbisAudioImporter pluginStlImporter— StlImporter pluginTinyGltfImporterdeprecated — TinyGltfImporter pluginUfbxImporter— UfbxImporter pluginWebPImporter— WebPImporter 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 foundMagnumPlugins::*— 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.