Preparation

Installing RSB

Currently, the 0.7 version of RSB can be installed in the following ways :

• Binary downloads (only for tools)
• Debian packages
• PyPi package (Python implementation)
• From source

Binary Downloads of RSB Tools

1. Download the tools binary from the appropriate location:

   • Linux i686
   • Linux x86_64
   • MacOS x86_64
   • Windows 7 i686

2. After the download, the tools file has to be made executable in most cases. This can be done for example by executing

   chmod +x tools
   

   in the download directory.

3. The various tools are provided as symbolic links to the single tools binary. When invoked, it prints a list of these links and offers to create them:

   $ ./tools
   [...]
   Create missing links now [yes/no]? y
   Creating symbolic link info -> tools
   [...]
   

   Note

   The links can also be created as follows:

   Non-interactively

   $ ./tools create-links
   

   Manually

   $ for alias in info logger call ; do ln -s tools ${alias} ; done
   

From Source

Note

In case you are unfamiliar with the git version control system, have a look at our short GIT primer.

1. The whole source tree of RSB can be obtained from the repository located at “0.7” branch of https://code.cor-lab.org/git/rsb.git.. URLs of individual implementations:

   Language	Repository URL
   C++	“0.7” branch of https://code.cor-lab.org/git/rsb.git. cpp
   Java	“0.7” branch of https://code.cor-lab.org/git/rsb.git. java
   Python	“0.7” branch of https://code.cor-lab.org/git/rsb.git. python
   Common Lisp	“0.7” branch of https://code.cor-lab.org/git/rsb.git. cl
   Matlab	“0.7” branch of https://code.cor-lab.org/git/rsb.git. matlab

   Additionally, the internal protocol, which is required for a from-source installation is available at “0.7” branch of https://code.cor-lab.org/git/rsb.git. protocol.

   Note

   There is currently an issue with the automatic replacement of the git URLs in this documentation. For all URLs there should not be a space between git. and the specific suffix.

2. Build and install an implementation

   • Installing the C++ Implementation of RSB
   • Installing the Common Lisp Implementation of RSB
   • Installing the Java Implementation of RSB

Debian Packages

Debian packages for several versions of Ubuntu GNU/Linux are available from the CoR-Lab package repository.

1. The following repository source line has to be added to /etc/apt/sources.list:

   deb http://packages.cor-lab.de/ubuntu/ RELEASENAME main

   where RELEASENAME is the appropriate Ubuntu release name.

2. After that, packages can be installed via

   $ sudo apt-get install PACKAGES
   

   where PACKAGES is the appropriate subset of rsb0.7 rsb-tools-cpp0.7 rsb-tools-cl0.7.

Note

This installation method only works with Ubuntu GNU/Linux. More information can be found here.

PyPI Packages

For python, platform-unspecific packages are pushed to the central repository server and can hence be installed with pip or easy_install.

1. The installation of the Python implementation of RSB requires the Google Protocol Buffers module on your system. Depending on whether pip or easy_install is used do one of the following:

   $ easy_install protobuf
   

   $ pip install protobuf
   

   Note

   These commands will install protobuf for the whole system and require root permissions. If you only want to install protobuf for your local user, add the --user option to the call of easy_install or pip install. The same applies for the subsequently described installation of rsb-python itself.

2. The rsb-python module can be installed by using one of the following funtions:

   $ easy_install "rsb-python<0.8"
   

   $ pip install "rsb-python<0.8"
   

   Note

   These commands will currently install rsb-python in version 0.7 as this is at the time of writing the stable version. This will be changed once the backport of this rst file was done.

3. If you plan to use the spread transport, you need to additionally install the python spread module which is available at: http://www.spread.org/files/SpreadModule-1.5spread4.tgz The version of this module which is pushed to the PyPI is outdated and does not work with spread version 4. You need to compile this module on your own.

Running the Examples

TODO

Troubleshooting

1. Problem (applies to C++, Python)

   Communication over spread does not work anymore. Spread settings are ignored.

   Solution

   Starting with version 0.7, RSB uses a transport that implements a custom TPC-based protocol to facilitate the easy use of the framework without dependencies on 3rd party libraries. In order to use to the old spread transport the configuration needs to be changed.

   This can be changed in three ways:

   1. Globally for all RSB programs (or running under a particular UNIX user)

      Create or modify a RSB configuration file /etc/rsb.conf or ~/.config/rsb.conf to contain the following lines:

      [transport.spread]
      enabled = 1
      [transport.socket]
      enabled = 0
      

      Lines 3 and 4 can be omitted to enable both transport s in parallel.

   2. Locally for the current directory

      Create a RSB configuration file $(pwd)/rsb.conf with the same contents as described above.

   3. For the current shell

      Set and export environment variables as follows:

      $ export RSB_TRANSPORT_SPREAD_ENABLED=1
      $ export RSB_TRANSPORT_SOCKET_ENABLED=0
      

2. Problem (applies to C++,Common Lisp,Python)

   How can I configure the TCP-based transport?

   Solution

   The TCP-based transport can be configured locally or globally by placing the following content in /etc/rsb.conf, ~/.config/rsb.conf or $(pwd)/rsb.conf:

   [transport.socket]
   enabled = 1
   host    = HOSTNAME
   port    = 4444
   server  = auto
   

   HOSTNAME can be localhost (if all processes are going to run on the same node), a host name of an IP address.

   Note

   The above configuration uses server = auto which causes the initial RSB process to create the specified server and subsequent processes to connect to that server.

3. Problem (applies to C++)

   I compiled and installed successfully, but RSB binaries/libraries produce linker errors at runtime.

   Solution

   The C++ implementation of RSB is built without fixed rpath by default. As a result, installed RSB binaries and libraries do not contain information regarding the location of their dependencies. This potentially causes runtime linking to fail because the dependencies cannot be located.

   There are two possible solutions:

   1. Building and installing RSB with fixed rpath

      This can be achieved by configuring RSB with

      $ cmake -DCMAKE_INSTALL_RPATH_USE_LINK_PATH=TRUE
      

      This instructs CMake to set the rpath of installed libraries and executables to the values used for building them. Normally the rpath is stripped at installation time.

   2. Use of the LD_LIBRARY_PATH environment variable

      When the value of LD_LIBRARY_PATH contains the directory/directories into which RSB (and its dependencies) have been installed, these dependencies can be located at runtime. LD_LIBRARY_PATH can be set, for example, like this:

      $ export LD_LIBRARY_PATH=PREFIX/lib
      

      where PREFIX is the prefix directory into which RSB and its dependencies have been installed.

      Warning

      This workaround is not permanent and has to be repeated for each new shell that should be able to execute RSB binaries or RSB-based programs.

4. Problem (applies to Common Lisp)

   When I start any of the tools, the following happens:

   $ logger socket://localhost:7777
   WARNING:
     Failed to load Spread library: Unable to load any of the alternatives:
     ("libspread-without-signal-blocking.so" "libspread.so" "libspread.so.2"
      "libspread.so.2.0" "libspread.so.1").
     Did you set LD_LIBRARY_PATH?
     Spread transport will now be disabled.
   [execution continues, but Spread transport does not work]
   

   Solution

   Place one of the mentioned Spread libraries on the system library search path or set LD_LIBRARY_PATH appropriately.

5. Problem (applies to all implementations)

   When a listener in my component receives certain event s, it crashes and complains about missing converter s. For example like this:

   $ ./myconponent
   [...]
   terminate called after throwing an instance of 'rsc::runtime::NoSuchObject'
     what():  No converter for wire-schema or data-type `.rst.vision.Image'.
   Available converters: {
     bool: *rsb::converter::BoolConverter[wireType = std::string, wireSchema = bool, dataType = bool] at 0x9d0b80
     [...]
   }

   Solution

   There can be several solutions to this problem.

   1. The listener could receive unexpected events. This can be diagnosed using the logger. If the listener does indeed receive unexpected events, the problem can be fixed by letting the offending informer or the listener itself operate on a different scope.
   2. The converter configuration could be wrong. If the listener only receives expected events, it may be missing a suitable converter. This problem can be solved by registering a suitable converter.
   3. The converter registration could happen after the listener has already been created. In that case, the listener would use the “old” set of converters.