melodic noetic   Show EOL distros: 

Example

To understand how pluginlib works, let's consider a small example. First, suppose that a polygon_interface Package exists containing a polygon base class. Let's also say that there are two different kinds of polygons supported in the system: a rectangle which lives in the rectangle_plugin Package and a traingle that lives in the triangle_plugin Package. The implementers of both the rectangle_plugin and triangle_plugin Packages would include special export lines in their manifest.xml file telling the rosbuild system that they intend to provide plugins for the polygon class in the polygon_interface Package. These export lines, in effect, register the plugins with the rosbuild system. This means that someone wishing to see all polygon plugins available in the system can run a simple rospack query which will return a list of available plugins, in this case, rectangle and traingle.

Providing a Plugin

Adding a Plugin to the Plugin List

In order to allow a plugin to be dynamically loaded, it must be added to a plugin list for the relevant plugin type. This list can be defined in any .cpp file that is compiled in the library containing a plugin. To help with this process, pluginlib defines three macros in the plugin_macros.h file to help with this process. For the example above, we might create a plugin_list.cpp file that looks as follows and compile it into the librectangle library:

   1 #include <pluginlib/plugin_macros.h>
   2 #include <polygon_interface/polygon.h>
   3 #include <rectangle_package/rectangle.h>
   4 
   5 //register the rectangle as a polygon plugin
   6 BEGIN_PLUGIN_LIST(polygon_namespace::polygon)
   7 REGISTER_PLUGIN(rectangle_namespace::rectangle)
   8 END_PLUGIN_LIST

The Plugin Description File

The plugin description file is an xml file that serves to store all the important information about a plugin in a machine readable format. It contains information about the library the plugin is in, the name of the plugin, the type of the plugin, etc. If we consider the rectangle_plugin package discussed above, the plugin description file, we'll call it rectangle_plugin.xml, would look something like this:

   1 <library path="lib/librectangle">
   2   <plugin name="rectangle" class="rectangle_namespace::rectangle" type="polygon_namespace::polygon">
   3   <description>
   4   This is a rectangle plugin
   5   </description>
   6   </plugin>
   7 </library>

For a detailed description of plugin description files and their associated tags/attributes please see the following documentation.

Exporting a Plugin

In order to allow plugin users to access information, a plugin provider must point to its plugin descritption file in its manifest.xml inside the export tag block. Considering the rectangle_plugin package again, the relevant lines would look as follows:

   1 <export>
   2   <polygon_interface polygon="${prefix}/rectangle_plugin.xml" />
   3 </export>

For a detailed discussion of exporting a plugin, please see the following documentation.

Important Note: In order for the above export command to work properly, the providing package must depend directly on the package containing the plugin interface. For example, the rectangle_plugin must have the line below in its manifest.xml:

  <depend package="polygon_interface" />

Using a Plugin

pluginlib provides a PluginLoader tool available in the plugin_loader.h header that makes it quick and easy to use provided plugins. For detailed documentation of the code-level API for this tool please see pluginlib::PluginLoader documentation. Below, we'll show a simple example of using the PluginLoader to create an instance of a rectangle in some code that uses a polygon:

   1 #include <pluginlib/plugin_loader.h>
   2 #include <polygon_interface/polygon.h>
   3 
   4 //... some code ...
   5 
   6 pluginlib::PluginLoader poly_loader("polygon_interface", "polygon");
   7 polygon_namespace::polygon* poly = poly_loader.createPluginInstance("rectangle");
   8 
   9 //... use the polygon
  10 

Tutorials

Links to relevant tutorials

Troubleshooting

Review Process