Robotics Service Bus

Plugins

  .. seealso::

     :ref:`specification-plugin`

        Details about :term:`plugin` s

  .. envvar:: RSB_PLUGINS_CPP_PATH

     A list of ``:``-separated directory names which should be

     searched to locate |project| :term:`plugin` s.

  .. envvar:: RSB_PLUGINS_CPP_LOAD

     A list of ``:``-separated :term:`plugin` names which should be

     loaded during |project| initialization.

  TODO other languages

   plugin

     A particular extension of |project|'s functionality, such as a

     :term:`transport` implementation or a :term:`converter`, packaged

     as runtime-loadable code.

     See :ref:`specification-plugin`.

.. _specification-plugin:

=========

 Plugins

=========

Overview

========

Plugins are loaded at initialization time

* This means, registration of provided :term:`converter` s and

  :term:`connector` s happens during initialization

* This is required in order for |project| to be able inquire about

  capabilities and configuration of :term:`converter` s and

  :term:`connector` s

Selection and loading of plugins is configured using the usual

mechanism

An implementation-language-specific section configures

* Means of locating plugins (e.g. searchpath, classpath,

  :envvar:`PYTHONPATH`)

* Names of the plugins that should be loaded

C++ Plugins

===========

* Are shared objects

* Configuration via options

  ``plugins.cpp.path``

    Colon separated list of directories in which expanded

    (e.g. ``rsbspread`` -> :samp:`{DIRECTORY}/librsbspread.so` on

    Linux) plugin libraries will be searched.

  ``plugins.cpp.load``

    Colon separated list of plugins that should be loaded. (Names do

    not include prefixes like ``lib`` of suffixes like ``.so`` or

    ``.dll``)

Configuration Examples:

.. code-block:: ini

   [plugins.cpp]

   path = /vol/vampire/lib:/vol/cor/lib

   load = rsbspread:rsbvampire # no "libX" or filetype suffix like ".so"

.. code-block:: sh

   RSB_PLUGINS_CPP_PATH=/vol/cor/lib

Java Plugins

============

* Are Jar files?

* Configuration via options

  ``plugins.java.path``

     TODO

  ``plugins.java.load``

    Colon-separated list of plugins that should be loaded.

Python Plugins

==============

* Are eggs?

* Configuration via options

        plugins.python.path: Colon separated list of directories which get added to sys.path?

        plugins.python.load: Colon separated list of plugins that should be loaded.

Common Lisp Plugins

===================

    Are ASDF-Systems

    Configuration via options

        plugins.lisp.path

        plugins.lisp.load: Colon separated list of plugins that should be loaded.

Default Plugin Searchpath

=========================

#. :samp:`{HOME}/.rsb{VERSION}/plugins`

#. :samp:`{PREFIX}/lib/rsb{VERSION}/plugins`

where :samp:`{HOME}` is the home directory of the current user,

:samp:`{PREFIX}` is the prefix into which |project| has been installed

and :samp:`{VERSION}` are the major and minor components of the

current |project| version (|version| for this version). Example:

#. :file:`/homes/juser/.rsb0.8/plugins`

#. :file:`/usr/lib/rsb0.8/plugins`

Implementations

===============

=========== ==================================================================

Language    File(s)

=========== ==================================================================

C++         *implemented as part of the RSC library*

Java        *not yet implemented*

Python      *not yet implemented*

Common Lisp *not yet implemented*

=========== ==================================================================

   specification-plugin

.. _tutorial-plugins:

=================

 Writing Plugins

=================

.. seealso::

   :ref:`specification-plugin`

     :term:`Plugin` specification

C++

===

In the C++ implementation of |project|, a :term:`plugin` is a

dynamically loadable library which defines the two symbols

#. ``rsc_plugin_init``

#. ``rsc_plugin_shutdown``

Any library can be made into an |project| plugin by adding file,

usually called :file:`Plugin.cc`, defining these two symbols. The

:file:`Plugin.cc` file of a minimal |project| :term:`plugin` looks

like this:

.. literalinclude:: /../rsb-cpp/examples/plugin/Plugin.cpp

   :language: c++

   :lines:    26-

Extending |project|

===================

Various aspects (called "extension points" here) of |project| can be

extended. This is usually achieved by writing :term:`plugin` s, each

of which adds a specific capability such as a new :term:`converter` or

:term:`transport`.

.. toctree::

   :maxdepth: 1

   tutorial-plugins