__  __ ___     ____   ____  ___
\ \/ //   |   / __ \ / __ \|__ \
 \  // /| |  / /_/ // /_/ /__/ /
 / // ___ | / _, _// ____// __/
/_//_/  |_|/_/ |_|/_/    /____/

      Welcome to YARP.

YARP is a library and toolkit for communication and device interfaces,
developed by humanoid robotics researchers but useful beyond that field.

Material included in YARP is copyright its authors.  YARP is released
under the terms of the LGPL v2.1 or later.  See COPYING for details.

Certain optional parts of YARP have dependencies that have more 
requirements than the LGPL:
 + libYARP_math uses the GNU Scientific Library, under the GPL.
 + devices urbtc, vfw, dimax_u2c have components that are under the GPL.

===============================================================================

INSTALLATION and COMPILATION
----------------------------

See official instructions at:
  http://eris.liralab.it/yarp/specs/dox/user/html/install.html
What follows is a summary.

There are a few different ways to compile YARP.

See if there is a file called "QUICKSTART-*.TXT" whose name matches
your system configuration.  If so, then you have a distribution of
YARP tailored to your specific operating system, and the instructions
in this file will give the fastest way to get going.

We now describe two general methods for compiling YARP: "cmake" and
"autoconf".

We recommend the "cmake" method for users of Microsoft Windows.  See the
CMAKE section below (after reading PREREQUISITES).

We also recommend the "cmake" method for users of UNIX-like systems
(including Linux, OSX, Cygwin).  See the CMAKE section below
(after reading PREREQUISITES).

Those on UNIX systems may also choose to use the "autoconf" method
(see AUTOCONF section below).  Be aware that this method will not
currently compile device interface support, only communication
support.


===============================================================================

PREREQUISITES *** important! read this! ***
-------------

YARP depends on a small, stable subset of the ACE communications
library.  Make sure you install ACE before following any of the steps
below.  See:
  http://www.cs.wustl.edu/~schmidt/ACE.html
or:
  http://eris.liralab.it/yarp/specs/dox/user/html/install.html#install_ace
for download and installation instructions.  Some linux distributions
have binary packages for ACE (e.g. debian has "libace-dev").

  * Read about ACE here: http://www.cs.wustl.edu/~schmidt/ACE.html

  * Download ACE here: http://deuce.doc.wustl.edu/Download.html
      o For Windows, we suggest: http://deuce.doc.wustl.edu/ACE-5.5.zip
      o For all others, we suggest: http://deuce.doc.wustl.edu/ACE-5.5.tar.gz

  * Please try using a release and not a beta version of ACE (at the moment of
	writing the latest version is 5.5)

  * Compile ACE using the instructions here: 
    http://www.cs.wustl.edu/~schmidt/ACE_wrappers/ACE-INSTALL.html

      o Don't panic! The instructions cover a lot of operating systems and 
        compilers. Just look carefully for your combination.

      o Windows/DevStudio instructions are here: 
        http://www.cs.wustl.edu/~schmidt/ACE_wrappers/ACE-INSTALL.html#msvc

      o UNIX/gcc instructions are here:
        http://www.cs.wustl.edu/~schmidt/ACE_wrappers/ACE-INSTALL.html#unix_traditional

      o OSX/gcc users, follow the UNIX instructions. 

On Microsoft Windows, please set the ACE_ROOT environment variable to
the location of your ACE install (a directory called "ACE_wrappers").
The directory in which the ACE library resides will also need to be in
your PATH environment variable in other for YARP executables to be
able to run.


For OSX/gcc, a note from Dimitri Ognibene:
------------------------------------------

(from http://groups.google.com/group/comp.soft-sys.ace/browse_thread/thread/c8fdbd72b3938149) 
create an $ACE_ROOT/ace/config.h file with this content:

#define ACE_LACKS_UNSETENV 
#define ACE_LACKS_ISCTYPE 
#define ACE_NEEDS_DL_UNDERSCORE 
#include "ace/config-macosx-tiger.h" 

===============================================================================

CMAKE
-----

Cmake (www.cmake.org) can create developer studio projects, makefiles,
or other build files for a number of operating systems and tool sets.

Download cmake from www.cmake.org or install it as a package if available
for your system.  For extra tips, see:
  http://eris.liralab.it/yarp/specs/dox/user/html/install.html#cmake

In Linux, in the YARP directory, type:

  cmake . (or "ccmake ." for a graphical interface with clear options)
  cmake . (needed for a few version combinations of cmake/pkg-config/gtk)
  make
  make test

* Note: CMake tries to remember things you've already told it.  
  If you run into trouble while setting things up, and decide to 
  start again, consider deleting the automatically generated
  "CMakeCache.txt" file to make sure CMake is really starting agin.

* See GUIS section below for steps needed to compile YARP graphical 
  interfaces.


In Microsoft Windows, run cmake, answer "Where is the source code" by
browsing to the YARP directory.

* Note: in Microsoft Windows your can run cmake as a GUI (by clicking
  on the appropriate icon) or from the command line.  We recommend
  that you run the GUI - it is easier to see what is going on.

* Note: CMake tries to remember things you've already told it.  
  If you run into trouble while setting things up, and decide to 
  start again, consider clicking the "Delete Cache" button to make 
  sure CMake is really starting agin.

* See GUIS section below for steps needed to compile YARP graphical 
  interfaces.

Answer "Where to build the binaries" with whatever you like.

Then hit the "Configure" button.  You'll be prompted for the Generator
you want (e.g. "NMake Makefiles", "Visual Studio 6", ...).  Pick
the build tool you are comfortable with.

A bunch of options will show up.  DON'T PANIC.  They may
all be correct.  If you don't understand them, you can try just 
hitting the "Configure" button to accept them.

If applicable for your chosen generator, make sure that
"CMAKE_BUILD_TYPE" is set to "Release" or "Debug", depending on
how you compiled ACE.

Make sure that the "ACE_INCLUDE_DIR" and "ACE_LIBRARY" values are set
to something related to where your installed ACE, fixing them manually
if necessary.

Hit the "Configure" button again if needed, then "OK".

In the directory you gave as "Where to build the binaries" should be
everything you need to compile, by opening a workspace, or running nmake,
etc.

After compilation, executables are in the "bin" directory and libraries are
in the "lib" directory.


===============================================================================

AUTOCONF (support is partial)
--------

This method requires the autoconf, automake, and libtool tools (e.g.
debian packages libtool autoconf automake1.8).

If you checked out from CVS and have a configure.ac file but would
like to produce a configure file, try:

  ./bootstrap.sh

You may need to modify this to match your autotool versions.
You should now have a configure file.
Try:

  ./configure

All going well, you have some new Makefiles.  Try:

  make
  make check

A man page will be generated for the "yarp" executable if the 
"docbook-to-man" program is installed on your system at compile-time.

If you do a:

  make install

Executables and libraries are installed on your system (use the --prefix=
option to configure to control where).

"yarp" is the main executable



===============================================================================

GUIS
----

Graphic User Interface(s) are implemented in YARP with gtk+. By default GUIs 
are not compiled, but you can ask cmake to include them.

Simply change the value of the cache variable CREATE_GUIS to ON. 
The easiest way to do this is through the graphic interface of cmake 
(ccmake in linux), but if you prefer you can manually edit the cache 
file instead (either ways are fine with us :)

Before you ask cmake to generate your project/make files, you need to install
gtk+. Needless to say, this procedure is different on Linux and Windows.

-Installing gtk+ on Linux
Follow the installation guide in the gtk web site (www.gtk.org/download).
on Debian: sudo apt-get install libgtk2.0-dev pkgconfig

-Installing gtk+ on Mac OSX
We don't have a lot of experience on Macs, but here's some suggestions.
Please let us know what works for you.
+ Install fink from http://fink.sourceforge.net
+ Then from Terminal run "sudo apt-get install gtk+2-dev pkgconfig"
+ It also seemed necessary to install a few more things: "sudo apt-get install glib2-dev pango1-xft2-dev atk1"
+ Now you should be ready to run cmake and compile.
+ The "stable" gtk+2 version at the time of writing is a little older than
  what we're using on Linux/Windows, so some functions are disabled in the
  yarpview GUI until we rewrite them.

-Installing gtk+ on Windows
We recommand you install glade for win32, which sets up everything you need
to compile applications with gtk (including yarp guis). Don't be scared, this
installation will not copy files in your windows directory (unless you say so)
and will only add a couple of environment variables. However, we understand 
you might want to install gtk manually (indeed this is what the author decided
to do the first time he installed gtk), so we provide a short explanation 
of how to do it.

1) Glade for win32. Go to gladewin32.sourceforge.net and get the 
gtk+/win32 Development Environment from the download section (at the time
of writing the release 2.8.18 is available). Run the installer and follow
the instructions.When prompted to choose which components you want to install
select "Register Environment Variables" and "Devel headers/libraries". Feel
free to decide if you want "Glade" and the "Documentation" (they are not 
required by yarp). Pick the destination folder you prefer and finish the 
installation.

The Glade installation defines GTK_BASEPATH environment variable to point 
to the directory where gtk was installed. GTK_BASEPATH will be used by cmake 
to locate the header files and the libraries required to compile and link gtk.
We also recommend that you append %GTK_BASEPATH%/bin to your PATH so that 
the dlls will be correctly found and loaded at runtime. 

2) The manual installation of gtk+ is a bit complicated because you need to
download and unpack a few packages. Go to http://www.gtk.org/download/ and
click on "win32 packages", download:

atk and atk-dev
cairo and cairo-dev
glib and glib-dev
gtk+ and gtk+-dev
pango and pango-dev

and
gettext
libiconv
libpng
zlib123-dll

from the "dependencies" subdirectory. As you will see, all the above libraries
come in different versions, pick the most recent ones.

Unpack all zip files in the same directory. Create the environment variable
GTK_BASEPATH to point to it (e.g. if you unpack all zip files in 
c:\gtk\ set GTK_BASEPATH=c:\gtk). GTK_BASEPATH will be used by cmake to locate 
the required header files and libraries. Also append %GTK_BASEPATH%/bin 
to your PATH, so that all dlls are located and loaded at runtime. 

Once you you installed gtk+, (please check that the environment variable 
GTK_BASEPATH exists and points to the correct location, that is the 
root of your gtk+ installation), activates the cache variable CREATE_GUIS 
(unless you have already done this) and ask cmake to generate your project
files (click on configure a couple of times). If you installed gtk+ correctly
everything should work fine, otherwise cmake will ask you to locate a few
header files and libraries.