/**
\page yarp_plugins Ways to compile YARP plugins

\tableofcontents

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.

\section yarp_plugins_warning 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.

\section yarp_plugins_basics The basics

For runtime loading of plugins, it is important to enable
the following CMake flag when compiling those plugins:
 \li 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:

 \li YARP_COMPILE_DEVICE_PLUGINS
 \li 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:

 \li ENABLE_yarpmod_fakebot = ON
 \li 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).

\section yarp_plugins_listing Listing plugins available at runtime

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

\verbatim
$ ./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
\endverbatim

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.


\section yarp_plugins_config Plugin configuration files

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

  \li the name of the library that implements the plugin
  \li the location of that library
  \li 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:
  \li 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
  \li the name of the carrier that the plugin corresponds to, as determined in the carrier's implementation of Carrier::getName, OR
  \li 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:
\code
[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
\endcode

The `code` line can have single byte wildcards with the following
slightly odd syntax (subject to revision):
\code
code (any) (any) "\0\0" (any) (any) "\0\0"
\endcode
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:
\code
[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 ...)
\endcode

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:
\code
style capability
default_capability /path/to/your/yarp/build
\endcode
and then set a `YARP_POLICY` environment variable to
`plugins` (matching the name of the ini file you placed in the `.yarp`/`yarp` directory).

\section yarp_plugins_library 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:
\code
[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")
\endcode

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

*/
