README

# Copyright: (C) 2010 RobotCub Consortium
# Author: Paul Fitzpatrick
# CopyPolicy: Released under the terms of the LGPLv2.1 or later, see LGPL.TXT


This directory is for producing SWIG interfaces to YARP.

This lets you run YARP from Java, Python, Perl, Tcl, Chicken, C#, Ruby,
Matlab.

Note that while we try to preserve YARP as close to its original form
as possible, some classes and methods had to be changed because
of issues with templates and pointers.  So the API is slightly 
different from the original.  The two ways to find out about the API
are:

 + Compile the java or python interfaces, and then run javadoc
   or pydoc to build a browsable form of the API.

 + Read yarp.i.  This is a bit complicated, but powerful because you'll
   learn how to fix things if you run into problems.  See www.swig.org
   for documentation on the syntax of this file.


============================================================================
== JAVA INTERFACE

See also:
  http://wiki.icub.org/wiki/YARP_and_Java
for latest tips.

To create the Java interface to YARP from linux
(the process on windows is analogous using cmake):
  ccmake .   # make sure the Java JNI directories get found
  make
  
Note from Lorenzo Natale 30/06/2011: If you select CMAKE_BULID_TYPE="Release" on Linux
you may get runtime errors from java later on. I guess this is related to Sebastien note 
below.

You should end up with a "libjyarp.so" library and a lot of generated "*.java"
files in a directory called "generated_src".
There will be a LOT of warnings during this process.  That is normal.

Now either do something like one of:
  setenv LD_LIBRARY_PATH $PWD:$LD_LIBRARY_PATH
  export LD_LIBRARY_PATH=$PWD:$LD_LIBRARY_PATH
Or move libjyarp.so into a directory in your library path.
If you are planning to just use Java via Matlab, you could instead
add to your matlab classpath.txt file:
  .../example/swig/build
(replace "..." with the path to YARP).  You can find out where this
file is by typing in Matlab:
  which classpath.txt

Now try building the examples using ant by typing:
  ant

You should now have files like "example1.jar" in the bin directory.
The source for these examples is in the "src" directory.

Try running:
  java -jar bin/example1.jar
and see if stuff happens.


Note from Sebastien Wrede:

  "... we had some problems due to a segmentation fault in
  libjyarp.so (in some generated JNI function) using SWIG 1.3.35 and gcc
  (Ubuntu 4.3.2-1ubuntu12). I'm not sure whether I missed something, but
  adding -fno-strict-aliasing to the compile flags in our build system
  solved the problem."

============================================================================
== PYTHON, PERL, TCL, RUBY INTERFACES

Run:
  ccmake .
And set "CREATE_PERL" and/or "CREATE_PYTHON" and/or "CREATE_TCL" to true.
Run:
  make

You should now have libraries called 
+ libyarp.so 
+ and/or _yarp.so 
+ and/or cyarp.so
+ and/or yarp.so
Or on windows, the equivalent DLLs.

Now try to run example.pl and/or example.py and/or example.tcl and/or Ruby.

For TCL, on windows, look at example.tcl and uncomment the line referring
to a .dll, and comment the line referring to a .so

Make sure all DLLs or SOs needed for YARP are available (for example, by
copying them to the current directory).

============================================================================
== CHICKEN INTERFACE

*** at the time of writing, you need to comment out the line mentioning
include "std_vector.i" in yarp.i -- a mapping for the std::vector class
doesn't seem to be implemented yet for Chicken.

Run:
  ccmake .
And set "CREATE_CHICKEN" to true.
Run:
  make

You should now have cyarp.so and cyarp.scm

Now try:
  chicken cyarp.scm
  chicken example.scm && gcc example.c cyarp.c libcyarp.so -lchicken -o example
  ./example

============================================================================
== CSHARP INTERFACE

Run:
  ccmake .
And set "CREATE_CSHARP" to true.
Run:
  make

You should now have libyarp.so or yarp.so (on Linux, presumably a .dll
on windows) and a whole lot of .cs files

On Linux, now either do something like one of:
  setenv LD_LIBRARY_PATH $PWD:$LD_LIBRARY_PATH
  export LD_LIBRARY_PATH=$PWD:$LD_LIBRARY_PATH
On Windows, put all this stuff in your path.

There used be some issues that are now fixed; solution preserved
just in case they recur

OLD>  The .cs files are not quite correct, you need to run:
OLD>  ./csharp-fix.pl
OLD> to fix them up (problems with multiple inheritance mismatch)
OLD> You need the "mcs" compiler for this script to work.  If you're
OLD> on windows, it might be easier to borrow a linux laptop for this
OLD> step.  Alternatively, manually fix the problems (there are cases
OLD> where "override" is specified rather than "virtual").
OLD>
OLD> At the time of writing, there are also a few errors related to the
OLD> PidVector class.  One solution is to just remove that and all 
OLD> references to it.

Now try:
  mcs -out:example.exe *.cs
or whatever your compiler is (the mcs compiler is in the debian/ubuntu
"mono-mcs" package).  If it works, then:
  ./example.exe
should do something yarpy.

NOTE:
Different compilers need the library to be called different things.
If you have yarp.so, try copying it to libyarp.so, or vice versa,
if you run into trouble.


============================================================================
== MATLAB INTERFACE

Matlab can run java code, so we access YARP via java.  See the 
"Java interface" section above.

See also:
  http://wiki.icub.org/wiki/Calling_yarp_from_Matlab
for latest tips.


============================================================================
== ALLEGRO INTERFACE

Should taste just like Chicken (see above).  Thanks to Lorenz Moselechner
for adding this.  There is a patch needed at the time of writing for SWIG
(July 2008), see *.patch in this directory.