SourceXtractorPlusPlus  0.13
Please provide a description of the project.
HowTo register a new plugin

Except of the core framework of SExtractor, all the rest of its functionality is built as plugins. This HowTo explains the concept of the SExtractor plugin system and how to register a new plugin.

Note
This HowTo does not provide information of what you can add in a plugin. For this information you can refer to the other HowTos.

Note that SExtractor defines all its classes in the namespace SExtractor. The following coding snippets assumed that the code is in the SExtractor namespace for brevity.

Implementing the Plugin interface

To create any SExtractor plugin you must create a new class that implements the Plugin interface:

class ExamplePlugin : public Plugin {
std::string getIdString() const override;
void registerPlugin(PluginAPI& plugin_api) override;
}

Implementing the Plugin interface requires to implement two methods. The first one, Plugin::getIdString(), should return a string with the name of your plugin. This name will be used by SExtractor when it needs to refer to the plugin, for example in the log messages. You should try to avoid very generic names, to minimize the possibility of name conflicts.

The second method, Plugin::registerPlugin(), is the method where you have to register all your plugin components to the SExtractor. The registration is done via the given PluginAPI object, which gives you access to the three classes which are needed to do anything a plugin can do:

  • ConfigManager : Provides the necessary tools for defining new configuration parameters
  • TaskFactoryRegistry : Provides the necessary tools for registering new source properties and their computation tasks
  • OutputRegistry : Provides the necessary tools for adding new columns at the output catalog

The full description of how to use these classes is out of the scope of this HowTo. You can see what you can implement using the plugin framework by refering to the rest of the HowTos.

Registering your Plugin class

After you implement your Plugin class, you need to register it, so SExtractor will be aware of its existence. SExtractor plugin framework supports two different ways of doing that.

Static plugins

The first (static plugins) is used for plugins which are compiled and linked directly to the SExtractor executable. These plugins are considered as the core SExtractor plugins and they require a re-compiling of the full SExtractor project. They are always available and there is no way to enable or disable them at runtime. To register your plugin this way, you must add in your plugin .cpp file (the one which will be linked to SExtractor) the following lines:

static StaticPlugin<ExamplePlugin> example_plugin_plugin;

You can chose as variable name anything, as the variable itself is not going to be used. The StaticPlugin will do the registration of your plugin in its constructor. The static keyword will limit the visibility of the variable to your plugin .cpp file, so there is no risk of name conflicts.

Note
You should not add the above line in your .h file! This would result with your plugin being registered every time its header file is included

Runtime plugins

The second type (runtime plugins) are the plugins that SExtractor can detect at runtime. These plugins are not linked to the SExtractor executable, so they do not require a re-compilation of SExtractor. They can be compiled independently, requiring only the headers of SExtractor being available. The use of this type of plugins makes easier the development of new features and the third party contribution. To register your plugin this way, you must add in your plugin .h file the following lines:

#include <boost/dll/alias.hpp>
std::shared_ptr<Plugin> createExamplePlugin() {
return std::make_shared<ExamplePlugin>();
}
BOOST_DLL_ALIAS(createExamplePlugin, create_plugin)

This will allow SExtractor to create new instances of your plugin by using the provided factory method. As this code has to be in the header file of your plugin, you should give a good name to the factory method, to avoid name conflicts. Alternatively, you can make the factory method a static method of your plugin.

Note
You can only register a single runtime plugin per library file (.so). Failing to do so, will result to redefinition errors during the linking of your plugin.

After you build your library file you need to let SExtractor know that it contains a plugin. This is done by copying the library file (.so) in the SExtractor plugin directory (set by the parameter --plugin-directory) and enabling it by using the parameter --plugin, for example --plugin libExamplePlugin (without the file extension). Note that you can use the --plugin option multiple times, to load multiple plugins.

Note that SExtractor uses the Boost.DLL library for loading the runtime plugins. This library has been introduced at version 1.61 of boost. If your boost library is newer than this, you can use the SExtractor runtime plugin functionality directly. If you have an older version of boost but newer than 1.55, you can still use the runtime plugin functionality by downloading the DLL library from here and by setting the environment variable BOOST_DLL_INSTALL_DIR before configuring the SExtractor project. If your boost version is 1.53 or less, you can use only the static plugins.

std::string
STL class.
std::shared_ptr
STL class.
StaticPlugin.h
Plugin.h