Changeset 10700 for INSTALL


Ignore:
Timestamp:
Aug 22, 2012, 2:09:00 PM (12 years ago)
Author:
Michael Tänzer
Message:

Merge CMake branch into trunk

File:
1 edited

Legend:

Unmodified
Added
Removed
  • INSTALL

    r10642 r10700  
    55about Ariba and its application.
    66
     7
    78Prerequisites
    89=============
    910ariba depends on libraries that may not be installed on your system:
    1011
    11     * Boost (version >=1.39)
    12     * Log4cxx (version >= 0.10.0)
    13     * GMP (no specific version)
     12    * Boost (version >=1.42)
     13    * GMP
     14    * CMake (version >=2.8)
    1415
    15 Furthermore, you need default development tools - that are most likely already installed on your system - such as
    16 gcc/g++, autoconf, automake, aclocal, libtool, liblt-dev ...
     16and optionally on
     17
     18    * Log4Cxx (version >= 0.10.0) for more sophisticated logging
     19    * Avahi for more efficient bootstrapping in local networks
     20    * LibBluetooth/Bluez for bluetooth support
     21    * Doxygen to build the documentation
     22
     23Furthermore, you need default development tools - that are most likely already
     24installed on your system - such as gcc/g++, libtool, liblt-dev ...
     25
    1726
    1827Quick Install (If all dependencies are satisfied)
    1928=============
    2029
    21 ariba currently build on Linux systems. Our reference platform is
    22 Ubuntu 8.04 with the g++ compiler version 4.1. However, latest
    23 Ubuntu releases should work, too. Download the latest
    24 ariba package from the the download site
    25 http://ariba-underlay.org/downloads
    26 or get the latest trunk code:
    27 svn co https://svn.tm.kit.edu/SpoVNet-KA/entwicklung/ariba/trunk ariba-trunk
     30ariba currently builds on Linux systems. Our reference platform is Ubuntu 8.04
     31with the g++ compiler version 4.1. However, latest Ubuntu releases should work
     32too.
    2833
    29 Extract the archive and change into the project directory:
     34Download the latest ariba package from the the download site
     35http://ariba-underlay.org/downloads or get the latest trunk code:
     36> svn co https://svn.tm.kit.edu/SpoVNet-KA/entwicklung/ariba/trunk ariba-trunk
    3037
     38If you downloaded ariba from the website extract the archive and change into the
     39project directory:
    3140> tar xfz ./ariba-x.x.x.tar.gz
    3241> cd ariba-x.x.x
    3342
    34 For SVN checkout you have to
     43For SVN checkout you have to:
    3544> cd ariba-trunk
    3645
    37 Now, configure, compile, and install ariba (if not all libraries
    38 needed by Ariba are available on your system, read the section
    39 'Prequisites').
     46Now create a directory to build ariba in:
     47> mkdir build
     48> cd build
    4049
    41 If no configure script is available (e.g. when you checked out an svn
    42 version), run the ./bootstrap script first and then type:
    43 
    44 > ./configure
     50Next the makefiles have to be generated and the source compiled:
     51> cmake ..
    4552> make
    46 > make install
    4753
    4854HINT: you may use
     
    5258the compilation stops, try make without the -j option again.
    5359
    54 
    55 In case you don't want to install Ariba into your system but to a
    56 local place, do:
    57 
    58 > mkdir build
    59 > ./configure --prefix=$PWD/build
    60 > make
     60And finally ariba will be installed into the system:
    6161> make install
    6262
    6363
    64 Local install (Download library dependencies and install ariba in a
    65 =============  local subdirectory)
     64Custom Build Options
     65====================
     66The build may be customized in various ways by setting CMake options. This can
     67be done by giving them as arguments on the command line:
     68> cmake .. -DOPTION=value
    6669
     70by using the CMake GUI which lets you set the variables graphically:
     71> cmake-gui ..
    6772
    68 If the required libraries are not available on your system or don't
    69 want to install them to the system you can use the bootstrap_libs
    70 script that comes with the ariba package. It will download all
    71 dependencies, compile and install them locally, and compile and
    72 install ariba:
     73or running cmake in interactive mode:
     74> cmake -i ..
    7375
    74 > tar xfz ./ariba-x.x.x.tar.gz
    75 > cd ariba-x.x.x
    76 > ./bootstrap_libs
     76The last two ways also give an overview which options exist.
    7777
    78 This script will automatically download all necessary libraries and
    79 compile them inside a new ./libs subdirectory and install them into
    80 ./build. In the end the ariba library itself is compiled to
    81 ./build. You can safely delete the ./libs subdirectory after the
    82 process.
     78Important options:
    8379
    84 Here is the manual way to go: If you install Ariba locally and have
    85 the required libraries also installed locally, you can use a
    86 config.site script to make it easier. The config.site file must reside
    87 in a folder called share. If your install path is /home/foo/local and
    88 you do a ./configure --prefix=/home/foo/local, ariba headers will be
    89 installed in /home/foo/local/include, and the ariba library in
    90 /home/foo/local/lib. To use a config.site script, create a folder
    91 /home/foo/local/share and create a file config.site. Such a file has
    92 paths towards required header files and libraries.
     80CMAKE_INSTALL_PREFIX - Where to install the compiled files. The default on Unix
     81                       platforms is /usr/local/. If you for example don't want
     82                       or can't install system wide, you can specify a directory
     83                       you have control over. The files will be installed to
     84                       "${prefix}/include/", "${prefix}/lib/" and so on.
    9385
    94 with_boost=/home/foo/Libraries/include
    95 test -z "$CPPFLAGS" && CPPFLAGS='-I/home/foo/Libraries/include'
    96 test -z "$LDFLAGS" && LDFLAGS='-L/home/foo/Libraries/lib'
     86CMAKE_BUILD_TYPE     - One of "", "Release", "Debug", "RelWithDebInfo" or
     87                       "MinSizeRel". This influences the build in various ways
     88                       (e.g. which compiler optimizations are turned on, whether
     89                       debug symbols are included, what warnings to show).
    9790
    98 If you now do a ./configure --prefix=/home/foo/local, the config.site
    99 will be found and the paths therein used for finding libraries. If you
    100 e.g. have multiple libraries distributed in their own include folders,
    101 you can also have multiple includes:
     91ENABLE_{AVAHI,BLUETOOTH,LOG4CXX}
     92                     - If set to OFF or 0 (ON is the default) it disables the
     93                       support of the feature even if the corresponding library
     94                       (see above) was detected to be present.
    10295
    103 test -z "$CPPFLAGS" && CPPFLAGS='-I/home/foo/Libraries/include -I/home/foo/otherlibrary/include'
     96<library>_INCLUDE_DIR - Where the directory containing the header files for
     97                       <library> is located. If the library is installed in the
     98                       usual system paths CMake should be able to automatically
     99                       find the right location. If the library is located
     100                       elsewhere (e.g. because you compiled it yourself in your
     101                       home directory) then you may need to set this variable
     102                       manually.
     103
     104<library>_LIBRARY    - Where the library file (aka the .so, .a or .dll file) for
     105                       <library> is located. If the library is installed in the
     106                       usual system paths CMake should be able to automatically
     107                       find the right location. If the library is located
     108                       elsewhere (e.g. because you compiled it yourself in your
     109                       home directory) then you may need to set this variable
     110                       manually.
     111
     112DOCUMENTATION_GENERATE_GRAPHICS
     113                     - Whether the documentation should include graphics such as
     114                       inheritance and include graphs (OFF by default). This
     115                       might take a long time and consume a lot of space.
     116
     117CMAKE_{C,CXX}_COMPILER - Which C/C++ compiler to use
     118CMAKE_{C,CXX}_FLAGS  - Which additional flags to give to the compiler (e.g. -pg
     119                       for profiling support)
     120
    104121
    105122Running the PingPong Sample
    106123===========================
    107 The PingPong binary pingpong is installed in build/bin. It has one
    108 parameter, a configuration file. You can find sample configuration
    109 files in the etc/pingpongconfig folder. If no configuration file is
    110 given, the node will randomly select its NodeID but will not find
    111 other nodes. This is because bootstrap modules are selected in the
    112 configuration file.
     124The PingPong binary pingpong is installed in "${prefix}/lib/ariba/" or found
     125directly in the build tree at "sample/pingpong/pingpong". It has one parameter,
     126a configuration file. You can find sample configuration files in the
     127"etc/pingpong" folder. If no configuration file is given, the node will randomly
     128select its NodeID but will not find other nodes. This is because bootstrap
     129modules are selected in the configuration file.
     130> ./sample/pingpong/pingpong ../etc/pingpong/settings_node1.cnf
    113131
    114 > ./pingpong ../../etc/pingpong/settings_node1.cnf
     132If this fails to find the libariba you may have to set the LD_LIBRARY_PATH
     133correctly in your current terminal, or better add it to your .bashrc
     134> export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/home/user/ariba/build/source/ariba
    115135
    116 If this fails to find the libariba you may have to set
    117 the LD_LIBRARY_PATH correctly in your current terminal,
    118 or better add it to your .bashrc
     136When running the pingpong application it will output a large number of log
     137messages and the initiator will wait for other nodes to join. You can start them
     138using the configuration files settings_node1.cnf and settings_node2.cnf. You may
     139need to adjust the configurations files: currently both node1 and node2 try to
     140join the initiator on the local machine. This will only work if you start all
     141instances on a local machine.
    119142
    120 > export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/home/user/ariba/build/lib
     143Once the PingPong sample is running and the nodes have connected, each node will
     144send out ping messages to every node he knows in the overlay structure every
     1455 seconds. You can now e.g. test mobility of Ariba and change the IP address of
     146a node, or swith from LAN connection to WLAN. The links established by the
     147PingPong sample through Ariba are mobility invariant and automatically repaired.
    121148
    122 When running the pingpong application it will output a large number of
    123 log messages and the initiator will wait for other nodes to join. You
    124 can start them using the configuration files settings_node1.cnf and
    125 settings_node2.cnf. You may need to adjust the configurations files:
    126 currently both node1 and node2 try to join the initiator on the local
    127 machine. This will only work if you start all instances on a local
    128 machine.
    129149
    130 Once the PingPong sample is running and the nodes have connected, each
    131 node will send out ping messages to every node he knows in the overlay
    132 structure every 5 seconds. You can now e.g. test mobility of Ariba and
    133 change the IP address of a node, or swith from LAN connection to
    134 WLAN. The links established by the PingPong sample through Ariba are
    135 mobility invariant and automatically repaired.  Selecting a compiler
     150Cross-Compiling for Maemo
     151=========================
     152Ariba runs on Nokia Maemo 4 (tested) and probably Maemo 5. We have tested Ariba
     153on an N810 device. Cross-Compiling is done using Scratchbox. Use the
     154preassembled Scratchbox version provided by Nokia which will install and
     155configure the complete Scratchbox system automatically.
    136156
    137 As the g++-4.3 compiler is very restrictive when compiling C++ and you
    138 will have some trouble with Boost and Log4cxx, we suggest to use
    139 e.g. g++-4.1. You then have to compile the libraries and Ariba with
    140 this compiler. You can tell Log4cxx and Ariba to use a different
    141 compiler using:
     157If you compile for Maemo you have to set the HAVE_MAEMO option in CMake.
    142158
    143 ./configure --prefix=... CXX=g++-4.1
    144 
    145 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:
    146 
    147 using gcc : 4.1 ;
    148 
    149 and then build using bjam as described in http://www.boost.org/doc/libs/1_38_0/more/getting_started/unix-variants.html.
    150 
    151 Cross-Comiling for Maemo
    152 ========================
    153 Ariba runs on Nokia Maemo 4 (tested) and probably Maemo 5. We have
    154 tested Ariba on an N810 device. Cross-Compiling is done using
    155 Scratchbox. Use the preassembled Scratchbox version provided by Nokia
    156 which will install and configure the complete Scratchbox system
    157 automatically.
    158 
    159 The Ariba configure will test for Maemo systems. Internally there are
    160 a number of special cases where handling on Maemo is different from
    161 normal Linux. If you require special handling, do the following in
    162 your code:
     159Internally there are a number of special cases where handling on Maemo is
     160different from normal Linux. If you require special handling, do the following
     161in your code:
    163162
    164163#include "ariba/config.h"
     
    167166 // special Maemo handling
    168167#endif
    169 
    170 Overview of special configure options
    171 =====================================
    172 There are several options to configure that are specific to Ariba:
    173 
    174     * --enable-debug=yes - for building a debug build
    175     * --enable-profiling=yes - for profiling with gprof
    176     * --enable-logcolors=yes - for colorful logging output
    177     * --enable-doxygen=yes - for generating doxygen documentation (do a make html-local in ariba/docu/doxygen)
    178 
Note: See TracChangeset for help on using the changeset viewer.