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.
attachment:plugin_model.png
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: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 [:pluginlib/PluginDescriptionFile: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 [:pluginlib/PluginExport:documentation].
Using Plugins
This section will describe, in detail, how to use plugins that are available.
Tutorials
Links to relevant tutorials
[wiki:/Troubleshooting Troubleshooting]
[wiki:/Reviews Review Process]
