corrade-2020.06/doc/plugin-management.dox

/*
    This file is part of Corrade.

    Copyright © 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014, 2015, 2016,
                2017, 2018, 2019, 2020 Vladimír Vondruš <mosra@centrum.cz>

    Permission is hereby granted, free of charge, to any person obtaining a
    copy of this software and associated documentation files (the "Software"),
    to deal in the Software without restriction, including without limitation
    the rights to use, copy, modify, merge, publish, distribute, sublicense,
    and/or sell copies of the Software, and to permit persons to whom the
    Software is furnished to do so, subject to the following conditions:

    The above copyright notice and this permission notice shall be included
    in all copies or substantial portions of the Software.

    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
    THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
    FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
    DEALINGS IN THE SOFTWARE.
*/

namespace Corrade {
/** @page plugin-management Plugin management
@brief Developing, loading and using plugins.

@tableofcontents
@m_footernavigation

The @ref PluginManager::Manager class provides hierarchical plugin management
functions. Main features:

-   Plugin manager version and plugin interface version checks to avoid
    unexpected behavior
-   Both static and dynamic plugin support
-   Plugin dependecies and aliases
-   Usage checks, the manager doesn't allow plugin unload if there are any
    active plugin instances

This tutorial will give you a brief introduction into how plugins are defined,
compiled and managed.

@section plugin-management-interface Plugin interface

Plugin interface is a class with virtual methods, defining the way how to work
with a particular plugin.

Every plugin interface has to be derived from @ref PluginManager::AbstractPlugin
and reimplement the
@ref PluginManager::AbstractPlugin::AbstractPlugin(PluginManager::AbstractManager&, const std::string&)
constructor. This is needed for instance use checks, as described above. Plugin
classes derived from that interface need to reimplement the constructor too, of
course.

Additionaly, an interface string should be provided by overriding the
@ref PluginManager::AbstractPlugin::pluginInterface() function in order to have
an additional safety check for interface compatibility. The macro takes a
string which uniquely names that particular interface. A good practice is to
use "Java package name"-style syntax because this makes the name as unique as
possible. The interface name should also contain a version identifier to make
sure the plugin will not be loaded with incompatible interface version. If this
function is not overriden, the default implementation returns @cpp "" @ce and
effectively makes the interface compatibility check a no-op.

To make lives of the users easier, we can define a list of paths where the
plugins will be searched for using
@ref PluginManager::AbstractPlugin::pluginSearchPaths() "pluginSearchPaths()".
The paths can be either absolute (for example hardcoding a system-wide
installation path) or relative (relative to the executable file). In this case
the plugins will be right next to the executable, so just a single entry
with @cpp "" @ce will do. If we wouldn't specify the search paths, the user
would need to pass a plugin search path to the plugin manager constructor.

@dontinclude pluginmanager/AbstractAnimal.h
@skip class AbstractAnimal
@until };
@until };

@section plugin-management-plugin Plugin definition

Every plugin is represented by a class derived from a particular plugin
interface. The plugin class is then registered as a static or a dynamic plugin.
Every plugin also needs to have an associated metadata file, which contains
information about plugin dependencies and optionally also plugin-specific data. Full
specification of plugin metadata file syntax can be found in the
@ref PluginManager::PluginMetadata class documentation.

First we define one static plugin, which will be included in the application
out-of-the-box:

@dontinclude pluginmanager/Canary.cpp
@skip class Canary
@until };

After defining the plugin we have to register it with the
@ref CORRADE_PLUGIN_REGISTER() macro. The first argument is plugin name (which
will be used when instancing the plugin), second argument is name of the plugin
class and third is the name of used plugin interface.

@code{.cpp}
CORRADE_PLUGIN_REGISTER(Canary, Canary,
    "cz.mosra.corrade.Examples.AbstractAnimal/1.0")
@endcode

And a corresponding configuration file, `Canary.conf`:

@include pluginmanager/Canary.conf

Then we define one dynamic plugin. Note that the macro for registering dynamic
plugin is the same, the only difference will be in `CMakeLists.txt`, as you
will see below. This way you can decide at compile time which plugins will be
dynamic, which will be static, or, for example, which will be compiled directly
into the library/application, so they can be used directly without the plugin
manager.

@dontinclude pluginmanager/Dog.cpp
@skip class Dog
@until };

@code{.cpp}
CORRADE_PLUGIN_REGISTER(Dog, Dog,
    "cz.mosra.corrade.Examples.AbstractAnimal/1.0")
@endcode

And a corresponding configuration file, `Dog.conf`:

@include pluginmanager/Dog.conf

@section plugin-management-compilation Plugin compilation

Requiring the Corrade package using @cmake find_package() @ce will define two
useful macros for plugin compilation:

@dontinclude pluginmanager/CMakeLists.txt
@skip find_package
@until corrade_add_static_plugin

The @ref corrade-cmake-add-plugin "corrade_add_plugin()" macro takes plugin
name as first argument, second argument is a directory where to install the
plugin files, third argument is name of configuration file and after that comes
one or more source files. We use the build directory for storing the plugins to
avoid the need for installation.

@note Note that on Windows a plugin DLL can't have unresolved references and
    thus needs to be explicitly linked to all its dependencies, even if they
    would be later at runtime correctly supplied by the plugin manager.

The @ref corrade-cmake-add-static-plugin "corrade_add_static_plugin()" macro is
similar to the above, except that it creates a static plugin instead of a
dynamic one.

@section plugin-management-management Plugin management

Now it's time to initialize @ref PluginManager::Manager and make use of the
plugins. @ref PluginManager::Manager is a templated class and that means it
will load and make available only plugins with the interface specified as
template.

In order to make the plugin manager find the static plugins, we have to import
them with the @ref CORRADE_PLUGIN_IMPORT() macro (for example at the beginning
of the @cpp main() @ce function). It takes a plugin name as an argument.

@note To make users of your plugins happier, you can for example provide a
    "static plugin import file" that calls the above macro together with a
    @ref CORRADE_AUTOMATIC_INITIALIZER(), so all the users have to do is to
    @cpp #include @ce it. For even more convenience,  you can tell CMake to
    attach this file automatically every time given static plugin is linked
    to a target using the @cmake target_sources() @ce command.

This example application will load plugin specified as command-line argument
and then displays brief info about a given animal. For convenient argument
parsing and usage documentation we used @ref Utility::Arguments.

@dontinclude pluginmanager/main.cpp
@skip int main
@until }
@until }
@until }
@until }
@until }
@until }
@until }
@until }

Compile the application with a simple CMake @cmake add_executable() @ce
command and don't forget to link in all the static plugins compiled above:

@dontinclude pluginmanager/CMakeLists.txt
@skip add_executable
@until target_link_libraries

After a successful compilation we can run the application with plugin name
as an argument:

@code{.shell-session}
$ ./PluginTest --help
Usage:
    ./PluginTest [-h|--help] [--] plugin

Displays info about given animal.

Arguments:
  plugin            animal plugin name
  -h, --help        display this help message and exit

$ ./PluginTest Canary
Using plugin 'I'm allergic to canaries!'

Name:      Achoo
Leg count: 2
Has tail:  yes

$ ./PluginTest Dog
Using plugin 'A simple dog plugin'

Name:      Doug
Leg count: 4
Has tail:  yes
@endcode

The full file content is linked below. Full source code is also available in
the [GitHub repository](https://github.com/mosra/corrade/tree/master/src/examples/pluginmanager).

-   @ref pluginmanager/AbstractAnimal.h "AbstractAnimal.h"
-   @ref pluginmanager/Canary.cpp "Canary.cpp"
-   @ref pluginmanager/Canary.conf "Canary.conf"
-   @ref pluginmanager/Dog.cpp "Dog.cpp"
-   @ref pluginmanager/Dog.conf "Dog.conf"
-   @ref pluginmanager/main.cpp "main.cpp"
-   @ref pluginmanager/CMakeLists.txt "CMakeLists.txt"

@example pluginmanager/AbstractAnimal.h @m_examplenavigation{plugin-management,pluginmanager/} @m_footernavigation
@example pluginmanager/Canary.cpp @m_examplenavigation{plugin-management,pluginmanager/} @m_footernavigation
@example pluginmanager/Canary.conf @m_examplenavigation{plugin-management,pluginmanager/} @m_footernavigation
@example pluginmanager/Dog.cpp @m_examplenavigation{plugin-management,pluginmanager/} @m_footernavigation
@example pluginmanager/Dog.conf @m_examplenavigation{plugin-management,pluginmanager/} @m_footernavigation
@example pluginmanager/main.cpp @m_examplenavigation{plugin-management,pluginmanager/} @m_footernavigation
@example pluginmanager/CMakeLists.txt @m_examplenavigation{plugin-management,pluginmanager/} @m_footernavigation

 */
}