How-To write cross-platform plugins

Sometimes we need to extend the functionality of our program at run-time. OS APIs for this let you load shared libraries, and then find symbols within them by name.

This works well for C symbols, but when it comes to C++, things start to break down. So instead of trying to deal with this in a complicated manner that takes into account symbol mangling across compilers and platforms, the typical approach is to return a pointer from the plugin to some data structure that we can use to access the symbols we want.

In practice, though, this is a void * that the caller of the plugin code needs to cast to whichever data structure it represents. So for each plugin, you also need some header file that defines the type(s) to cast to. Treat it like an interface.

Because of this approach of casting a void *, we’d like a run-time check to see if the cast is reasonably safe. For that, we embed a “plugin type” in the plugin. And because interfaces can change even when the type of plugin does not, we also add a plugin version.

As the plugin interface, you could use a class with pure virtual functions, or take a more manual approach. We’ll do the latter here just to demonstrate it.

Plugin code (plugin.h)

#include <functional>
#include <string>

namespace bar {

using foo_function = std::function<void (std::string const &)>;

struct my_interface
{
  foo_function  foo;
  // TODO you can add as many things as you'd like.
};

} // namespace bar

With this plugin interface, you can now define the plugin code:

Plugin code (plugin.cpp)

#include <liberate/sys/plugin.h>
#include "plugin.h"

namespace bar {

// Some implementation of foo_function
void plugin_foo(std::string const &)
{
  // do something
}

// We need an instance of my_interface, and might as well make it a global
// variable.
my_interface interface = { plugin_foo };

// With the interface declared, let's create plugin metadata.

liberate::sys::plugin_meta meta =
{
  42, // The user-defined plugin/interface type
  1,  // The user-defined version of this interface type
  &interface, // A reference to the interface data
  nullptr,    // Always empty.
};

} // namespace bar

// We cannot quite escape Window's need to declare exported functions,
// but that's alright.
#if defined(_WIN32) || defined(__CYGWIN__) || defined(__MINGW32__)
  #define PLUGIN_EXPORT __declspec(dllexport)
#else
  #define PLUGIN_EXPORT
#endif

extern "C" {

// The main plugin interface is a C function named "liberate_plugin_meta"
// that returns a liberate::sys::plugin_meta instance. Note that it would
// also be possible to dynamically allocate things, but the global variable
// is actually easier here.
PLUGIN_EXPORT void *
liberate_plugin_meta()
{
  return &bar::meta;
}

} // extern "C"

As you can see, the amount of metadata to manage in the plugin code is not particularly much. We’ll leave compilation of the plugin code out of this guide, because it depends on your build system. But if you’re using meson, you might want to look at the shared_module reference entry.

What’s still missing is how to use the plugin in practice.

Plugin usage

#include <liberate/sys/plugin.h>
#include "plugin.h"

using namespace liberate::sys;

plugin_meta const * meta = nullptr;

// We need a pointer to the metadata structure. If an appropriate function
// was found, and it yielded a pointer, then the meta structure will now
// be filled.
auto success = load_plugin(meta, "path/to/plugin.so");

// We only know how to deal with the plugin type '42' in version '1' here.
if (meta.type != 42 || meta.version != 1) {
  exit(1);
}

// The plugin interface is of type my_interface.
auto iface = static_cast<bar::my_interface>(meta->data);

// And we can now invoke functions in it, etc.
iface->foo("Hello, world!");

Note that the meta->plugin_handle field is now set; you initialized it to a nullptr in the plugin code. It contains a handle to the loaded plugin in a platform dependent format. This then allows you to unload the plugin again. Unloading also frees the metadata structure.

Unload plugin

unload_plugin(meta);

assert(meta == nullptr);

Managing the installation location of plugins, etc. is not in scope for this library.