Corrade::PluginManager namespace

Plugin management.

This library contains Manager, which takes care of loading, unloading and instancing plugins. There is also an AbstractPlugin class, which is the base of all plugins. See Plugin management for a brief introduction to how plugins work.

This library is built if CORRADE_WITH_PLUGINMANAGER is enabled when building Corrade. To use this library with CMake, request the PluginManager component of the Corrade package and link to the Corrade::PluginManager target:

find_package(Corrade REQUIRED PluginManager)

# ...
target_link_libraries(your-app PRIVATE Corrade::PluginManager)

See also Downloading and building Corrade and Using Corrade with CMake for more information.

Classes

class AbstractManager
Base for plugin managers.
template<class Interface>
class AbstractManagingPlugin
Base class for plugin interfaces with access to associated manager.
class AbstractPlugin
Base class for plugin interfaces.
template<class T>
class Manager
Plugin manager.
class PluginMetadata
Plugin metadata.

Enums

enum class LoadState: unsigned short { NotFound = 1 << 0, WrongPluginVersion = 1 << 1, WrongInterfaceVersion = 1 << 2, WrongMetadataFile = 1 << 3, UnresolvedDependency = 1 << 4, LoadFailed = 1 << 5, Static = 1 << 6, Loaded = (1 << 7) | LoadState::Static, NotLoaded = 1 << 8, UnloadFailed = 1 << 9, Required = 1 << 10, Used = 1 << 11 }
Plugin load state.

Typedefs

using LoadStates = Containers::EnumSet<LoadState>
Plugin load states.

Functions

auto operator<<(Utility::Debug& debug, PluginManager::LoadState value) -> Utility::Debug&
Debug output operator.
auto operator<<(Utility::Debug& debug, PluginManager::LoadStates value) -> Utility::Debug&
Debug output operator.
auto implicitPluginSearchPaths(Containers::StringView libraryLocation, Containers::StringView hardcodedPath, Containers::StringView relativePath) -> Containers::Array<Containers::String> new in 2020.06
Implicit plugin search paths.

Enum documentation

enum class Corrade::PluginManager::LoadState: unsigned short
#include <Corrade/PluginManager/AbstractManager.h>

Plugin load state.

Enumerators
NotFound

The plugin cannot be found. Returned by AbstractManager::loadState() and AbstractManager::load().
WrongPluginVersion

The plugin is build with different version of plugin manager and cannot be loaded. Returned by AbstractManager::load().
WrongInterfaceVersion

The plugin uses different interface than the interface used by plugin manager and cannot be loaded. Returned by AbstractManager::load().
WrongMetadataFile

The plugin doesn't have any associated *.conf metadata file or the metadata file contains errors. Returned by AbstractManager::loadState() and AbstractManager::load().
UnresolvedDependency

The plugin depends on another plugin, which cannot be loaded (e.g. not found or wrong version). Returned by AbstractManager::load(). Note that plugins may have cross-manager dependencies, and to resolve these you need to explicitly pass a manager instance containing the dependencies to AbstractManager::registerExternalManager().
LoadFailed

The plugin failed to load for other reason (e.g. linking failure). Returned by AbstractManager::load().
Static

The plugin is static. Returned by AbstractManager::loadState() and AbstractManager::load().
Loaded

The plugin is successfully loaded. Returned by AbstractManager::loadState() and AbstractManager::load(). The value includes value of LoadState::Static, see LoadStates for more information. In Emscripten, Windows RT, iOS and CORRADE_TARGET_ANDROID the value is equivalent to LoadState::Static.
NotLoaded

The plugin is not loaded. Plugin can be unloaded only if is dynamic and is not required by any other plugin. Returned by AbstractManager::loadState() and AbstractManager::load().
UnloadFailed

The plugin failed to unload. Returned by AbstractManager::unload().
Required

The plugin cannot be unloaded because another plugin is depending on it. Unload that plugin first and try again. Returned by AbstractManager::unload().
Used

AbstractManager::unload() returns this if the plugin has an active instance and cannot be unloaded. Destroy all instances and try again. AbstractManager::load() returns this if loading a file path directly and a plugin with the same name already exists.

Typedef documentation

typedef Containers::EnumSet<LoadState> Corrade::PluginManager::LoadStates
#include <Corrade/PluginManager/AbstractManager.h>

Plugin load states.

Useful when checking whether LoadState in in given set of values, for example:

if(loadState & (PluginManager::LoadState::WrongPluginVersion|
                PluginManager::LoadState::WrongInterfaceVersion)) {
    // ...
}

Note that LoadState::Loaded includes the value of LoadState::Static, so you can use loadState & PluginManager::LoadState::Loaded instead of much more verbose loadState & (PluginManager::LoadState::Loaded|PluginManager::LoadState::Static).

Function documentation

Utility::Debug& Corrade::PluginManager::operator<<(Utility::Debug& debug, PluginManager::LoadState value)
#include <Corrade/PluginManager/AbstractManager.h>

Debug output operator.

Utility::Debug& Corrade::PluginManager::operator<<(Utility::Debug& debug, PluginManager::LoadStates value)
#include <Corrade/PluginManager/AbstractManager.h>

Debug output operator.

Containers::Array<Containers::String> Corrade::PluginManager::implicitPluginSearchPaths(Containers::StringView libraryLocation, Containers::StringView hardcodedPath, Containers::StringView relativePath) new in 2020.06
#include <Corrade/PluginManager/AbstractPlugin.h>

Implicit plugin search paths.

Parameters
libraryLocation Absolute location of a dynamic library containing the plugin interface. Should be empty when the library is static or the plugin interface is defined directly inside an executable. Use Utility::Path::libraryLocation() to retrieve the location.
hardcodedPath Hardcoded path where to search for plugins. It's recommended to propagate this value from the buildsystem, keeping it empty by default.
relativePath A path where plugins are stored, relative to a usual library location
Returns A list of path to search for plugins. The returned strings are not guaranteed to be mutable, as they might reference global string literals.

Meant to be used to implement AbstractPlugin::pluginSearchPaths(). Produces a list of search paths in this order:

  1. hardcodedPath, if not empty, for example "/usr/lib64/magnum/imageconverters". This is meant to act as a last-hope override when everything else fails and unless there's a good reason to do so (like the ones listed below), it should be empty. Supplying an absolute path even when not needed may result in self-contained apps picking up system-wide plugins by accident, causing all sorts of ABI issues. The path can be relative as well, in which case the plugin manager joins path of Utility::Path::executableLocation() with it.
  2. "../PlugIns" joined with relativePath, if the system is macOS or iOS. Since it's a relative location, the plugin manager joins path of Utility::Path::executableLocation() with it. This is meant for bundles, where the main executable is expected to be stored in the MacOS directory and plugins in the PlugIns directory (note the capitalization). Apple docs for reference.
  3. The path of libraryLocation joined with relativePath, if libraryLocation is not empty. This will work for most cases of a dynamic system-wide install. For example with libraryLocation set to "/usr/lib/MagnumTrade.so" and relativePath to "magnum/imageconverters", it'll result in "/usr/lib/magnum/imageconverters" added to the search path. If a correct library location can't be detected reliably (for example due to symlinks), you to use hardcodedPath. This is done after the PluginIns path on Apple in order to make it possible for a bundle to ship and use its own plugins even if it may rely on system-installed libraries.
  4. "../lib" joined with relativePath, unless the system is Windows (because there plugin DLLs are not in a lib directory but next to the executable in bin instead). Since it's a relative location, the plugin manager joins path of Utility::Path::executableLocation() with it. This will work for most cases of a static system-wide install. For example with executable location being "/usr/bin/magnum-player" and relativePath set to "magnum/imageconverters", it'll result in "/usr/lib/magnum/imageconverters" added to the search path. If the system has the library dir lib64, lib/64/ or similar and there's no symlink that would make the above work, you need use hardcodedPath.
  5. relativePath alone, for example "magnum/imageconverters". Again, since it's a relative location, the plugin manager joins path of Utility::Path::executableLocation() with it. This will work for Windows and all relocatable installs, as it simply looks for the plugins next to the executable.

You're encouraged to pass hardcodedPath and relativePath as Containers::StringViewFlag::Global views (i.e., string view literals) — the values in points 1 and 5 will then be non-owning references to them, avoiding copies.

See also Plugin directories for more information.