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:

BUILD_SHARED_LIBS = ON

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:

YARP_COMPILE_DEVICE_PLUGINS
YARP_COMPILE_CARRIER_PLUGINS

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:

ENABLE_yarpmod_fakebot = ON
ENABLE_yarpcar_human_carrier = ON

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:

the name of the library that implements the plugin
the location of that library
the name of a C function within that library that it can query for information about the plugin in a standard way.

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

the name of the device that the plugin corresponds to, which should match whatever was given in a CMake YARP_PREPARE_DEVICE(devicename ...) call, OR
the name of the carrier that the plugin corresponds to, as determined in the carrier's implementation of Carrier::getName, OR
the first 8 bytes sniffed on an incoming TCP connection.

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 etc/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 etc/yarp/plugins.

YARP looks for etc/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

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 etc/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).

Table of Contents

Warning to YARP users

The basics

Listing plugins available at runtime

Plugin configuration files

Finding library files