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.
First, install SWIG, at least version 3.0 .
Then, install any language-specific packages needed.
Now, we need to get YARP ready:
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.
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.
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.
Done? Now follow the language-specific steps in Overview of steps needed.
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.
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/
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.
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']);
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"
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>"
You can build the YARP bindings while you are building YARP or using a separated build directory just for the bindings.
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.
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.
# On Linux... cd $YARP_ROOT/bindings mkdir build cd build # On Windows... cd %YARP_ROOT%/bindings mkdir build cd build
ccmake ..
CREATE_<LANGUAGE>=ON
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:
SWIG_DIR C:/swig/swigwin-2.0.7/Lib SWIG_EXECUTABLE C:/swig/swigwin-2.0.7/swig.exe
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.
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:
setenv LD_LIBRARY_PATH $PWD:$LD_LIBRARY_PATH export LD_LIBRARY_PATH=$PWD:$LD_LIBRARY_PATHOn Windows, you can update your PATH environment variable.
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:
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.