= Installation = 

== Prerequisites ==

ariba depends on libraries that may not be installed on your system: 

 * [http://www.boost.org Boost (version >=1.39)] 
 * [http://gmplib.org GMP (no specific version)]
 * optional: [http://logging.apache.org/log4cxx Log4cxx (version >= 0.10.0)]

Furthermore, you need default development tools - that are most likely already installed on your system - such as gcc/g++, autoconf, automake, aclocal, libtool, libltdl-dev ...

Ariba provides the {{{bootstrap_libs}}} script that will help you in installing several libraries. What you should anyway do locally:
{{{
   sudo apt-get install g++ libssl-dev autoconf automake libtool libltdl-dev
}}}


== Quick Install (If all dependencies are satisfied) ==

ariba currently build on Linux systems. Our reference platform is Ubuntu 8.04 with the g++ compiler version 4.1 (confirmed to work on Ubuntu releases 10.04, 10.10) 
Download the latest ariba package from the [http://ariba-underlay.org/downloads download site]:

Extract the archive and change into the project directory:
{{{
> tar xfz ./ariba-x.x.x.tar.gz
> cd ariba-x.x.x
}}}

Now, configure, compile, and install ariba (if not all libraries needed by Ariba are available on your system, read the section 'Prequisites'). If no {{{configure}}} script is available (e.g. when you checked out an svn version), run the {{{./bootstrap}}} script first.:
{{{
> ./configure
> make
> make install
}}}

If you want to install as root, do
{{{
> sudo make install
> sudo ldconfig
}}}

In case you don't want to install Ariba into your system but to a local place, do:
{{{
> mkdir build
> ./configure --prefix=$PWD/build
> make
> make install
}}}

== Local install (Download library dependencies and install ariba in a local subdirectory) ==

If the required libraries are not available on your system or don't want to install them to the system you can use the {{{bootstrap_libs}}} script that comes with the ariba package. It will download all dependencies, compile and install them locally, and compile and install ariba:
{{{
> tar xfz ./ariba-x.x.x.tar.gz
> cd ariba-x.x.x
> ./bootstrap_libs
}}} 
This script will automatically download all necessary libraries and compile them inside a new {{{./libs}}} subdirectory and install them into {{{./build}}}. In the end the ariba library itself is compiled to {{{./build}}}. You can safely delete the  {{{./libs}}} subdirectory after the process. 

Here is the manual way to go: If you install Ariba locally and have the required libraries also installed locally, you can use a {{{config.site}}} script to make it easier. The {{{config.site}}} file must reside in a folder called {{{share}}}. If your install path is {{{/home/foo/local}}} and you do a {{{./configure --prefix=/home/foo/local}}}, ariba headers will be installed in {{{/home/foo/local/include}}}, and the ariba library in {{{/home/foo/local/lib}}}. To use a {{{config.site}}} script, create a folder {{{/home/foo/local/share}}} and create a file {{{config.site}}}. Such a file has paths towards required header files and libraries.

{{{
with_boost=/home/foo/Libraries/include
test -z "$CPPFLAGS" && CPPFLAGS='-I/home/foo/Libraries/include'
test -z "$LDFLAGS" && LDFLAGS='-L/home/foo/Libraries/lib'
}}}

If you now do a {{{./configure --prefix=/home/foo/local}}}, the {{{config.site}}} will be found and the paths therein used for finding libraries. If you e.g. have multiple libraries distributed in their own include folders, you can also have multiple includes:

{{{
test -z "$CPPFLAGS" && CPPFLAGS='-I/home/foo/Libraries/include -I/home/foo/otherlibrary/include'
}}}

== Running the !PingPong Sample == 

The !PingPong binary {{{pingpong}}} is installed in {{{build/bin}}}. It has one parameter, a configuration file. You can find sample configuration files in the {{{etc/pingpongconfig}}} folder. If no configuration file is given, the node will randomly select its NodeID but will not find other nodes. This is because bootstrap modules are selected in the configuration file. 

{{{
> ./pingpong ../../etc/pingpong/settings_node1.cnf
}}}

If this will fail to find the {{{libariba}}} you may have to set the {{{LD_LIBRARY_PATH}}} correctly in your current terminal, or better add it to your {{{.bashrc}}}
{{{
> export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/home/user/ariba/build/lib
}}}

When running the {{{pingpong}}} application it will output a large number of log messages and the initiator will wait for other nodes to join. You can start them using the configuration files {{{settings_node1.cnf}}} and {{{settings_node2.cnf}}}. You may need to adjust the configurations files: currently both node1 and node2 try to join the initiator on the local machine. This will only work if you start all instances on a local machine.

Once the !PingPong sample is running and the nodes have connected, each node will send out ping messages to every node he knows in the overlay structure every 5 seconds. You can now e.g. test mobility of Ariba and change the IP address of a node, or swith from LAN connection to WLAN. The links established by the !PingPong sample through Ariba are mobility invariant and automatically repaired.

=== Selecting a compiler ===

As the g++-4.3 compiler is very restrictive when compiling C++ and you will have some trouble with Boost and Log4cxx, we suggest to use e.g. g++-4.1. You then have to compile the libraries and Ariba with this compiler. You can tell Log4cxx and Ariba to use a different compiler using:
{{{
./configure --prefix=... CXX=g++-4.1
}}}
This will not work in Boost as the {{{configure}}} script is just a wrapper around the Boost Build.System {{{bjam}}}. You can edit the jamfile in the Boost root directory:
{{{
using gcc : 4.1 ;
}}}
and then build using bjam as described in {{{http://www.boost.org/doc/libs/1_38_0/more/getting_started/unix-variants.html}}}.

=== Cross-Comiling for Maemo ===

Ariba runs on Nokia Maemo 4 (tested) and probably Maemo 5. We have tested Ariba on an N810 device. Cross-Compiling is done using [http://www.scratchbox.org Scratchbox]. Use the [http://maemo.org/development/sdks/maemo_4-1-2_diablo preassembled Scratchbox version] provided by Nokia which will install and configure the complete Scratchbox system automatically. 

The Ariba {{{configure}}} will test for Maemo systems. Internally there are a number of special cases where handling on Maemo is different from normal Linux. If you require special handling, do the following in your code:
{{{
#!cpp
#include "ariba/config.h"
...
#ifdef HAVE_MAEMO
 // special Maemo handling
#endif
}}}

{{{
#!comment
=== Installing libraries locally ===

We will shortly explain how to install the Boost and Log4cxx libraries locally on your system. Download Boost ({{{boost_1_38_0.tar.gz}}}) and Log4cxx (apache-log4cxx-0.10.0.tar.gz). Be aware, that Log4cxx requires the Apache Portable Runtime (libapr and libapr-util).

{{{
> cd ~/
> mkdir local
> cd boost_1_38_0
> ./configure --prefix=/home/user/local
> make install
> cd ..
> cd log4cxx-0.10.0
> ./configure --prefix=/home/user/local
> make install
}}}

If Boost makes itself a subdirectory (e.g. {{{/home/user/local/include/boost_1-38/boost}}}), move the {{{boost}}} directory one hierarchy up, resulting in {{{/home/user/local/include/boost}}}.

There is a compiler optimization bug in g++-4.3 that results in problems with Boost 1.38.0 (see https://svn.boost.org/trac/boost/ticket/2655). There is a workaround available, see https://svn.boost.org/trac/boost/changeset/51863/trunk/boost/xpressive/detail/core/adaptor.hpp. 

If you installed some of the libraries locally and not system wide (e.g. using {{{./configure --prefix=MYPATH}}} as described above), you have to tell Ariba where the libraries are installed. In this example we assume that (1) all libraries are installed locally, and not system wide, and (2) that you want to install Ariba locally. The installation process would then look as follow:

{{{
> cd ~/ariba-x.x.x
> mkdir build
> ./configure 
  --prefix=/home/user/ariba-x.x.x/build 
  --with-boost=/home/user/local/include/boost   
  CPPFLAGS='-I/home/user/local/include'
  LDFLAGS='-L/home/user/local/lib'
> make
> make install
}}}

This will build and install Ariba into the created {{{build}}} folder.
COMMENT_END
}}} 


{{{
#!comment

== Building for Simulations ==

Ariba support transparent simulation integration for [http://www.omnetpp.org OMNeT++] and the INET framework. Currently v3 of OMNeT++ is supported. Porting to OMNeT++ 4 will be finished soon. Furthermore, interation with [http://www.oversim.org OverSim] is in the queue.  

To build Ariba for simulated environment, use the {{{--enable-simulation=yes}}} option to {{{configure}}}. Furthermore, you have to tell Ariba where OMNeT++ and INET include files reside. This time we assume that you have installed the required libraries (like Boost) system wide. If this is not the case, you would have include the paths as shown above

{{{
> ./configure --prefix=$PWD/build 
  CPPFLAGS='-I/home/user/omnet/include 
  -I/home/user/inet/Network/IPv4 
  -I/home/user/inet/Base 
  -I/home/user/inet/Network/Contract 
  -I/home/user/inet/NetworkInterfaces/Contract 
  -I/home/user/inet/Transport/TCP 
  -I/home/user/inet/Transport/UDP 
  -I/home/user/inet/Transport/Contract'
  --enable-simulation=yes
> make
> make install
}}}

This will compile the Ariba library with simulation support and the !PingPong sample with simulation support. Note, that the !PingPong example will now be compiled as a shared library and reside in {{{build/lib}}}. Details on how to run the simulated !PingPong sample are detailed in the next section.

== Running the Simulated !PingPong Sample ==

Compiling Ariba for simulations will result in {{{libariba}}} and {{{libpingpong}}} being placed into the {{{build/lib}}} folder. You can find exemplary simulation files in the {{{etc/simulation/omnet3}}} folder of the Ariba distribution. 

You have to adjust some path in the {{{omnetpp.ini}}} file. Fix the path in {{{preload-ned-files}}}. The load-libs path should be correct, in case you did not change the Ariba package.

Next, start the {{{INET}}} binary in the {{{etc/simulation/omnet3}}}. This will start up the simulation that contains 3 router and 15 nodes that have Ariba nodes with the !PingPong application on it.

 * {{{--enable-simulation=yes}}} - for building for simulation integration

COMMENT_END
}}} 

=== Overview of special {{{configure}}} options ===

There are several options to {{{configure}}} that are specific to Ariba:

 * {{{--enable-debug=yes}}} - for building a debug build
 * {{{--enable-profiling=yes}}} - for profiling with gprof
 * {{{--enable-logcolors=yes}}} - for colorful logging output
 * {{{--enable-doxygen=yes}}} - for generating doxygen documentation (do a {{{make html-local}}} in {{{ariba/docu/doxygen}}})