YARP
Yet Another Robot Platform
Using YARP from python, java, ruby, C#, and other languages

Table of Contents

YARP is written in C++.

If you wish to use all the features of YARP in a program written in a different language, we recommend you use SWIG. This will create an interface to YARP for you in the language of your choice. At the time of writing, languages that have been tested with YARP and SWIG are: Java, Python, Perl, C#, TCL, and Ruby. If you are interested in a different language, check if it is in the list of languages supported by SWIG. If it is, getting YARP going should be easy, so don't despair. Just open an issue (or a pull request) on YARP issue tracker.

Overview of steps needed

First, install SWIG, at least version 3.0 .

Then, install any language-specific packages needed.

Now, we need to get YARP ready:

  • You'll need to have YARP installed or compiled on your computer. See Installing YARP for how to do that.
  • Check that your build of YARP is compatible with SWIG. It is best if YARP is compiled as a set of dynamic/shared libraries. If you compiled YARP yourself, make sure that the "BUILD_SHARED_LIBS" flag was turned on. If not, configure it with CMake and recompile. Precompiled YARP builds provide dynamic/shared libraries.
  • You'll also need an up-to-date copy of the YARP source code. This does not need to match the version of YARP you have installed (as long as it isn't too old). Any YARP package from version 2.3.20 on will do. Older packages will work if you replace "$YARP_ROOT/bindings" with "$YARP_ROOT/example/swig" throughout this tutorial. If you have git, you can get piping fresh YARP as follows: 
    git clone git://github.com/robotology/yarp.git

Now that we have all the prerequisites, it is time to configure and compile the YARP language bindings.

Installing SWIG on Linux

Just about every distribution of Linux has a "swig" package. To install from the command line in Debian or Ubuntu:

sudo apt-get install swig

If you are using Debian Jessie, you need to install swig3.0 to get a sufficiently recent version of swig.

Done? Now follow the language-specific steps in Overview of steps needed.

Installing SWIG on OSX

Some OSX versions have a version of SWIG pre-installed. We recommend you use homebrew to manage packages on OSX. Once you have homebrew, you may install swig as follows: 

brew install swig

Done? Now follow the language-specific steps in Overview of steps needed.

Installing SWIG on Windows

  • Download SWIG from the SWIG home page. Look for "Windows users should download..."
  • You should end up with a ZIP file that you unpack.
  • Remember where you unpack it! You'll need it later.
  • We recommend you set a SWIG_DIR environment variable that points to the directory in which you have unpacked SWIG. This is optional however. If you don't do it, you'll need to later tell CMake where you put SWIG (it won't find it automatically).

Done? Now follow the language-specific steps in Overview of steps needed.

YARP for Java

On Windows: Install the Java Development Kit (JDK). Its name changes from time to time. At the time of writing it was called "J2SE Development Kit 5.0" - get it from http://java.sun.com/javase/downloads/index.jsp

On Linux, you have a choice of Java implementations. There is Open JDK: 

sudo apt-get install openjdk-6-jdk

(replace "6" with "7" to taste). Or there is Sun's version (you may need to add a non-free repository to get this): 

sudo apt-get install sun-java6-jdk

On OSX, you may already have a JDK installed (details).

Once you have the Java SDK installed, you can compile the Java bindings enabling the CREATE_JAVA and PREPARE_CLASS_FILES options.

YARP for Python

For python on linux, be sure to install python development files, e.g. on Debian/Ubuntu: 

sudo apt-get install python-dev

If you have several versions of python installed, that is fine, but do check later during configuration that CMake finds the version you expected (click the "SHOW ADVANCED VALUES" checkbox and look for PYTHON_* variables).

On Windows, you can get python from http://www.python.org/getit/windows/

YARP for Matlab

The easiest way to use YARP from Matlab is via its Java bindings. Follow the instructions for Java: YARP for Java.

When you have the bindings built, make sure to add the path to the build directory in your matlab classpath.txt file. You can find out where this file is by typing in Matlab: 

which classpath.txt

You also need to add the directory build/lib library to your matlab librarypath.txt file. Once again you can find out where this file is by typing in Matlab: 

which librarypath.txt

Once you modified this files, restart matlab and load the Yarp bindings typing LoadYarp in Matlab.

Note
An highly experimental (and unsupported) version of Yarp SWIG bindings for Matlab directly using the C++ Mex API without using Java is available at https://github.com/robotology-playground/yarp-matlab-bindings .

YARP for Octave

For using Yarp from octave on Linux, be sure to install octave development packages, e.g. on Debian/Ubuntu: 

sudo apt-get install liboctave-dev

After Compiling YARP language bindings, make sure that Octave-Yarp binding library (i.e., yarp.oct) is in the octave Load-path list or manually set it within your octave script. For example: 

 octave> addpath([getenv('YARP_ROOT') '/build/lib/octave']);

YARP for Lua

For Lua on linux, be sure to install Lua development files, e.g. on Debian/Ubuntu: 

sudo apt-get install lua5.2 liblua5.2-0-dev

If you use Windows, try Lua for Windows, an easy-to-use distribution of Lua packed with several useful libraries.

A more generic way (also for OSX users) is to build lua from the source. Lua is implemented in pure ANSI C and compiles unmodified in all platforms that have an ANSI C compiler. For example, to compile Lua on OSX, download Lua 5.2.x and try: 

tar -xvf lua-5.2.x.tar.gz
cd lua-5.2.x
make macosx
sudo make install

OSX users can also uses Lua binaries from http://lua-users.org/wiki/LuaBinaries

After Compiling YARP language bindings, make sure that the Lua-Yarp binding shared library (.so/.dll/.dylib/...) is included in your LUA_CPATH environment variable; e.g., on linux: 

export LUA_CPATH=";;;/path/to/bindings/build/lib/lua/5.2/?.so"

YARP for Perl5

For perl on linux, be sure to install perl, e.g. on Debian/Ubuntu: 

sudo apt-get install perl

If you are using YARP installed in the same prefix as perl vendorprefix (usually /usr) you should not need to set any environment variable.

If you are installing YARP in a different directory, you should point the PERL5LIB environment variable to the installation directory; e.g., on linux: 

export PERL5LIB="<CMAKE_INSTALL_PREFIX>/<CMAKE_INSTALL_PERLDIR>"

You can verify both CMAKE_INSTALL_PREFIX and CMAKE_INSTALL_PERLDIR from CMake.

If you are using yarp from the build directory, you should point the PERL5LIB environment variable to your build directory; e.g. on linux: 

export PERL5LIB="<CMAKE_BINARY_DIR>/<CMAKE_INSTALL_PERLDIR>"

Configuring YARP language bindings

You can build the YARP bindings while you are building YARP or using a separated build directory just for the bindings.

Configure bindings while compiling YARP

The process on building bindings with YARP follows the usual YARP compilation steps. In addition to that, while you configure YARP using ccmake or the CMake GUI you should enable the YARP_COMPILE_BINDINGS option.

After a configuration step you should see the options to enable various languages (CREATE_JAVA, CREATE_PYTHON, and so on). Turn on the languages for which you want to compile the bindings, and then continue with the usual YARP compilation steps.

Configure bindings to build separately from YARP

Run the CMake GUI (or ccmake from the command line), and set the source directory to $YARP_ROOT/bindings, where YARP_ROOT is the path to the YARP source code. Set the build directory to be anywhere you like. When you configure, you should see options to enable various languages (CREATE_JAVA, CREATE_PYTHON, and so on). Turn on exactly one of those options (you may get conflicts between certain pairs of languages if you choose to build more than one in a single build directory). Configure, and generate. You should now have a project file or Makefile in the build directory. Go build it and you are done!

Here are the steps, one by one.

  • Create an empty build directory. This can be anywhere you like. If you are interested in multiple languages, we recommend you use a separate build directory for each. From the command-line, you could do this (if YARP_ROOT isn't set, replace it with the path to YARP's source code): 
    # On Linux...
cd $YARP_ROOT/bindings
mkdir build
cd build

# On Windows...
cd %YARP_ROOT%/bindings
mkdir build
cd build
  • Run CMake. If you use a GUI, set the SOURCE directory to the "bindings" subdirectory of the YARP source code, and the BUILD directory to the empty build directory you created. If you followed the command-line instructions above, you can continue with: 
    ccmake ..
  • Now, in CMake, find a CREATE_* flag that matches the language you care about, and turn it ON. For example, for python, turn on CREATE_PYTHON. 
    CREATE_<LANGUAGE>=ON
  • Finish configuring/generating in CMake, then exit it.
  • Now you should have everything you need to compile and build.

Configuration troubleshooting

If you run into any trouble, choose the "SHOW ADVANCED VALUES" option in CMake and make sure that all options related to your language are correct (e.g. PYTHON_* variables, JAVA_* variables, etc). If not correct, fix them to point to valid locations on your computer.

If you installed SWIG manually, for example on Windows, then:

  • Check that SWIG_DIR in CMake points to the directory Lib inside where you unpacked SWIG. If not, edit it and set it manually to the correct location.
  • Check that SWIG_EXECUTABLE in CMake points to the swig.exe program. If not, edit it and set it manually to the correct location.
  • Examples of good values: 
    SWIG_DIR         C:/swig/swigwin-2.0.7/Lib
SWIG_EXECUTABLE  C:/swig/swigwin-2.0.7/swig.exe

Compiling YARP language bindings

If you followed the command-line suggestions in Configuring YARP language bindings, and are on Linux/OSX, all that remains is to do: 

make
sudo make install   # Optional, not sane for all languages.

For Python, you can append the path of the bindings build directory to the PYTHONPATH environment variable, like this: 

export PYTHONPATH=$PYTHONPATH:/path/to/bindings/build

then compile with make and you're done (no need to make install).

In any case, everything you need should be sitting in the build directory. With Visual Studio: open the solution file in build directory, and compile as usual. Be sure to use the Release build.

Running programs that use the YARP language bindings

There are basic examples in the "bindings" subdirectory of the YARP source code for all the supported languages. There are a few important things to be aware of:

  • When you compiled the bindings, a shared library (.so/.dll/.pyd/...) was created. This library needs to be in your operating system's library path. On Linux, if you are in the build directory, you can do something like one of: 
    setenv LD_LIBRARY_PATH $PWD:$LD_LIBRARY_PATH
export LD_LIBRARY_PATH=$PWD:$LD_LIBRARY_PATH
    On Windows, you can update your PATH environment variable.
  • When you compiled the bindings, one or many wrapper files may have been produced in your language of interest. These files will need to be in whatever path is appropriate to guide your language's interpreter/compiler/... to find them.

Available classes and methods

While we try to translate the YARP API in as close to its original form as possible, some classes and methods had to be changed because of issues with templates and pointers. So in different languages the API is slightly different from the original. At the moment, the three ways to find out about these differences are:

  • Via your language's introspection features.
  • By compiling the java or python interfaces, and then run javadoc or pydoc to build a browsable form of the API.
  • By reading the bindings/yarp.i file. This is a bit complicated, but powerful because you'll learn how to fix things if you run into problems. See http://www.swig.org for documentation on the syntax of this file.