melodic noetic   Show EOL distros: 

Package Summary

The pluginlib package provides tools for writing and dynamically loading plugins using the ROS build structure. To work, these tools require plugin providers to register their plugins in the manifest.xml of their package. To make this clear, 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