Yet Another Robot Platform
No Matches
Ways to compile YARP plugins

This documents an area of YARP that is in flux: runtime plugins.

+ Collaboration diagram for Ways to compile YARP plugins:

This documents an area of YARP that is in flux: runtime plugins.

Subject to change during early 2013.

For examples in this section, we assume a Linux environment.

Historically, YARP plugins have been selected at compile-time, and linked with the YARP_init library. At the time of writing, this remains the default. However, it is now also possible to load YARP plugins at runtime.

Warning to YARP users

If you are a USER of YARP, rather than a PACKAGER of YARP then consider sticking with the default operation of plugins rather than runtime loading. Runtime loading adds extra ways for things to go wrong, and more paths to keep track of.

The basics

For runtime loading of plugins, it is important to enable the following CMake flag when compiling those plugins:

Only shared libraries (.so/.dll/.dylib) can be loaded at runtime. YARP plugins are enabled by default, in order to disable them you can set to OFF the following options:

The most important plugins are enabled by default, but you can select or deselect each plugin by changing the value of the corresponding option, for example:

This would give us a device called "fakebot" (that generates visual imagery from a simple simulated pan/tilt camera) and a carrier called "human" (a test carrier that actually requires a human agent to pass on messages from one port to another).

Listing plugins available at runtime

To list all plugins available at runtime, use "yarp plugin". Once YARP is compiled with the settings given in The basics, the list should include a carrier called "human" and a device called "fakebot":

$ ./bin/yarp plugin
List of runtime plugins:

carrier human
  human (type carrier) (name human) (library yarp_human) (part human_carrier) (code HUMANITY)
  found by linking to /.../yarp2/build/lib/libyarp_human.so

device fakebot
  fakebot (type device) (name fakebot) (library yarp_fakebot) (part fakebot)
  found by linking to /.../yarp2/build/lib/libyarp_fakebot.so

In fact, those plugins are also "compiled in" to YARP, as normal.

If we now recompile yarp with ENABLE_yarpmod_fakebot and ENABLE_yarpcar_human_carrier turned OFF, these plugins are no longer compiled into YARP. But unless we have actually removed the library files we already built (libyarp_fakebot.so and libyarp_human.so), YARP will still be able to find them and load them at runtime. Running ./bin/yarp plugin should give the same results as before.

Plugin configuration files

To load a plugin, YARP needs to know three things:

However, at the point where a plugin is needed, YARP will know just one of the following:

To get from this point to activating the right plugin, YARP uses a set of "fingerprint" files. For a carrier they look like this:

[plugin human] # "human" here is an arbitrary unique identifier
type carrier # is the plugin a "carrier" or a "device"?
name human # the name of the plugin, as far as users are concerned
library yarp_human # the name of the library containing the plugin
# (omitting OS-specific prefixes and suffixes)
part human_carrier # function name: match yarp_prepare_carrier(THIS_NAME ...)
code "HUMANITY" # the first 8 bytes on this kind of connection

The code line can have single byte wildcards with the following slightly odd syntax (subject to revision):

code (any) (any) "\0\0" (any) (any) "\0\0"

That would represent /..\0\0..\0\0/ in regular expression syntax.

For a device, the fingerprint files are similar, but don't need the code line:

[plugin fakebot] # "fakebot" here is an arbitrary unique identifier
type device # is the plugin a "carrier" or a "device"?
name fakebot # the name of the plugin, as far as users are concerned
library yarp_fakebot # the name of the library containing the plugin
# (omitting OS-specific prefixes and suffixes)
part fakebot # function name: match yarp_prepare_device(THIS_NAME ...)

It is fine for a fingerprint file to contain more than one plugin section. The name of the fingerprint is arbitrary, but the extension should be .ini. Examples can be found in the YARP source code, in subdirectories of the src/devices and src/carriers directories.

YARP is configured to aggregate plugin.ini files in a directory called yarp/plugins. The ini files are collected in this directory irrespective of whether the corresponding plugins are compiled or not. To add plugins not included with YARP, an ini file may be placed in yarp/plugins.

YARP looks for yarp/plugins using a yarp::os::ResourceFinder. If you don't already use configuration files with YARP, one way to get going would be to create a file in your home directory called .yarp/plugins.ini (or yarp\plugins.ini on Windows) containing:

style capability
default_capability /path/to/your/yarp/build
The main, catch-all namespace for YARP.
Definition dirs.h:16

and then set a YARP_POLICY environment variable to plugins (matching the name of the ini file you placed in the .yarp/yarp directory).

Finding library files

Each operating system has a convention for finding library files which YARP will also use (LD_LIBRARY_PATH etc), with one addition. Once the configuration files in yarp/plugins can be found, YARP will also use any "search" blocks it finds there. They look like this:

[search basic] # basic is an arbitrary unique identifier
path "/path/to/directory/to/try" # possible path to library
extension ".so" # extension the libraries use
prefix "lib" # prefix the libraries use
type "shared" # type of library (should always be "shared")

By default, YARP will add a search block in a file called path.ini which gives the path to where YARP libraries have been placed after compilation (or installation).