yarp_swig.dox

*
 * Copyright (C) 2012 IITRBCS
 * CopyPolicy: Released under the terms of the LGPLv2.1 or later, see LGPL.TXT
 *
 */

/**
 * @page yarp_swig Using YARP from python, java, ruby, C#, and other languages

\author Paul Fitzpatrick, Lorenzo Natale, Vadim Tikhanoff, Ali Paikan

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
<a href="http://www.swig.org">SWIG</a>.  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,
Chicken Scheme, C#, Allegro Common Lisp, TCL, and Ruby.
If you are interested in a different language, check if it is in the list of
<a href="http://www.swig.org/compat.html#SupportedLanguages">languages supported by SWIG</a>.  If it is, getting YARP going should be easy, so don't despair.
Just send a quick email to the <a href="http://wiki.icub.org/wiki/Robotcub-hackers">mailing&nbsp;list</a>, or pattern match in
the $YARP_ROOT/bindings/CMakeLists.txt file to add your language.

@section yarp_swig_install Overview of steps needed

First, install SWIG.
\li \ref yarp_swig_linux
\li \ref yarp_swig_osx
\li \ref yarp_swig_windows

Then, install any language-specific packages needed.

 - \ref yarp_swig_java
 - \ref yarp_swig_python
 - \ref yarp_swig_matlab
 - \ref yarp_swig_lua
 - \ref yarp_swig_octave
 - \ref yarp_swig_perl
 - \ref Other tested languages are: Chicken Scheme, C#, Allegro Common Lisp, TCL, and Ruby.  Procedure is same as for Java/Python.  You may need to install a development package for your desired language.  To find out:
   - On Linux: Check http://www.dabeaz.com/cgi-bin/wiki.pl?DeveloperInfo/GettingStarted
   - On OSX: A surprising amount of stuff comes pre-installed.
   - On Windows: Check http://www.swig.org/Doc2.0/Windows.html

Now, we need to get YARP ready:

\li You'll need to have YARP installed or compiled on your computer.
See \ref install for how to do that.
\li 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 "CREATE_SHARED_LIBRARY"
flag was turned on.  If not, configure it with CMake and recompile.
Precompiled YARP builds provide dynamic/shared libraries.
\li You'll also need an up-to-date copy of the YARP source code.  This
does <b>not</b> 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:
\verbatim
git clone git://github.com/robotology/yarp.git
\endverbatim

Now that we have all the prerequisites, it is time to configure and
compile the YARP language bindings.
\li \ref yarp_swig_configure
\li \ref yarp_swig_compile
\li \ref yarp_swig_run
\li \ref yarp_swig_api

@section yarp_swig_linux Installing SWIG on Linux

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

\verbatim
sudo apt-get install swig
\endverbatim

Done? Now follow the language-specific steps in \ref yarp_swig_install.

@section yarp_swig_osx Installing SWIG on OSX

Some OSX versions have a version of SWIG pre-installed.
We recommend you use <a href="http://mxcl.github.com/homebrew/">homebrew</a> to manage packages on OSX.  Once you have homebrew, you may install swig as follows:
\verbatim
brew install swig
\endverbatim

Done? Now follow the language-specific steps in \ref yarp_swig_install.

@section yarp_swig_windows Installing SWIG on Windows

 - Download SWIG from the <a href="http://www.swig.org/download.html">SWIG home page</a>.  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 \ref yarp_swig_install.



@section yarp_swig_java 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:
\verbatim
sudo apt-get install openjdk-6-jdk
\endverbatim
(replace "6" with "7" to taste).  Or there is Sun's version (you may need to add a non-free repository to get this):
\verbatim
sudo apt-get install sun-java6-jdk
\endverbatim

On OSX, you may already have a JDK installed (<a href="http://stackoverflow.com/questions/1577014/how-install-a-specific-jdk-on-mac-os-x">details</a>).

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


@section yarp_swig_python YARP for Python

For python on linux, be sure to install python development files,
e.g. on Debian/Ubuntu:
\verbatim
sudo apt-get install python-dev
\endverbatim
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/


@section yarp_swig_matlab YARP for Matlab

The easiest way to use YARP from Matlab is via its Java bindings.
Follow the instructions for Java: \ref yarp_swig_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:
\verbatim
which classpath.txt
\endverbatim

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:
\verbatim
which librarypath.txt
\endverbatim

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 .

@section yarp_swig_octave YARP for Octave
For using Yarp from octave on Linux, be sure to install octave development packages, e.g. on Debian/Ubuntu:
\verbatim
sudo apt-get install liboctave-dev
\endverbatim

After \ref yarp_swig_compile, 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:
\verbatim
 octave> addpath([getenv('YARP_ROOT') '/build/lib/octave']);
\endverbatim


@section yarp_swig_lua YARP for Lua
For Lua on linux, be sure to install Lua development files, e.g. on Debian/Ubuntu:
\verbatim
sudo apt-get install liblua5.1-0-dev
\endverbatim

If you use Windows, try <a href="https://code.google.com/p/luaforwindows/">Lua for Windows</a>,
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 <a href="http://www.lua.org/ftp/lua-5.1.5.tar.gz">Lua 5.1</a> and try:
\verbatim
tar -xvf lua-5.1.x.tar.gz
cd lua-5.1.x
make macosx
sudo make install
\endverbatim

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

After \ref yarp_swig_compile, make sure that the Lua-Yarp binding shared library
(.so/.dll/.dylib/...) is included in your LUA_CPATH environment variable; e.g., on linux:
\verbatim
export LUA_CPATH=";;;/path/to/bindings/build/?.so"
\endverbatim


@section yarp_swig_perl YARP for Perl5

For perl on linux, be sure to install perl, e.g. on Debian/Ubuntu:
\verbatim
sudo apt-get install perl
\endverbatim

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:
\verbatim
export PERL5LIB="<CMAKE_INSTALL_PREFIX>/<CMAKE_INSTALL_PERLDIR>"
\endverbatim
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:
\verbatim
export PERL5LIB="<CMAKE_BINARY_DIR>/<CMAKE_INSTALL_PERLDIR>"
\endverbatim


@section yarp_swig_configure 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.

@subsection yarp_swig_configure_main_build 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 <tt>ccmake</tt> 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.


@subsection yarp_swig_configure_separate_build Configure bindings to build separately from YARP

Run the CMake GUI (or <tt>ccmake</tt> 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.

\li 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):
\verbatim
# On Linux...
cd $YARP_ROOT/bindings
mkdir build
cd build

# On Windows...
cd %YARP_ROOT%/bindings
mkdir build
cd build
\endverbatim
\li 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:
\verbatim
ccmake ..
\endverbatim
\li 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.
\verbatim
CREATE_<LANGUAGE>=ON
\endverbatim
\li Finish configuring/generating in CMake, then exit it.
\li Now you should have everything you need to compile and build.

@subsection yarp_swig_configure_troubleshooting 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:
\li 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.
\li Check that SWIG_EXECUTABLE in CMake points to the swig.exe program. If not, edit it and set it manually to the correct location.
\li Examples of good values:
\verbatim
SWIG_DIR         C:/swig/swigwin-2.0.7/Lib
SWIG_EXECUTABLE  C:/swig/swigwin-2.0.7/swig.exe
\endverbatim

@section yarp_swig_compile Compiling YARP language bindings

If you followed the command-line suggestions in \ref yarp_swig_configure,
and are on Linux/OSX, all that remains is to do:
\verbatim
make
sudo make install   # Optional, not sane for all languages.
\endverbatim

For Python, you can append the path of the bindings build directory to the PYTHONPATH environment variable, like this:
\verbatim
export PYTHONPATH=$PYTHONPATH:/path/to/bindings/build
\endverbatim
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.

@section yarp_swig_run 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:

\li 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:
\verbatim
setenv LD_LIBRARY_PATH $PWD:$LD_LIBRARY_PATH
export LD_LIBRARY_PATH=$PWD:$LD_LIBRARY_PATH
\endverbatim
On Windows, you can update your PATH environment variable.
\li 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.

@section yarp_swig_api 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 <tt>bindings/yarp.i</tt> 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.


 */