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.
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.
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. To compile YARP device and carrier plugins respectively, select:
This will bring up a list of possible devices and carriers to choose from, 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).
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.
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:
YARP_PREPARE_DEVICE(devicename ...)call, OR
To get from this point to activating the right plugin, YARP uses a set of "fingerprint" files. For a carrier they look like this:
code line can have single byte wildcards with the following slightly odd syntax (subject to revision):
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:
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
YARP is configured to aggregate
plugin.ini files in a directory called
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 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 on Windows) containing:
and then set a
YARP_POLICY environment variable to
plugins (matching the name of the ini file you placed in the
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:
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).