Changes between Version 42 and Version 43 of BaseInstall


Ignore:
Timestamp:
Aug 27, 2012, 6:13:57 PM (12 years ago)
Author:
Michael Tänzer
Comment:

Adjust the documentation to the fact that we now use CMake

Legend:

Unmodified
Added
Removed
Modified

  • BaseInstall

    v42 v43  
    11= Installation =
     2[[TOC]]
    23
    34== Binary Packages ==
    … …  
    1011ariba depends on libraries that may not be installed on your system:
    1112
    12  * [http://www.boost.org Boost (version >=1.39)]
    13  * [http://gmplib.org GMP (no specific version)]
    14  * optional: [http://logging.apache.org/log4cxx Log4cxx (version >= 0.10.0)]
     13 * [http://www.boost.org Boost] (version >=1.42)
     14 * [http://gmplib.org GMP]
     15 * [http://www.cmake.org/ CMake] (version >= 2.8)
    1516
    16 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 ...
     17and optionally on:
     18 * [http://logging.apache.org/log4cxx Log4Cxx] (version >= 0.10.0) for more sophisticated logging
     19 * [http://avahi.org/ Avahi] for more efficient bootstrapping in local networks
     20 * [http://www.bluez.org/ LibBluetooth/Bluez] for bluetooth support
     21 * [http://www.stack.nl/~dimitri/doxygen/ Doxygen] to build the documentation
     22
     23Furthermore, you need default development tools - that are most likely already installed on your system - such as gcc/g++, libtool, libltdl-dev …
    1724
    1825
    19 == Quick Install (If all dependencies are satisfied) ==
     26== Quick Install ==
    2027
    21 ariba currently build on Linux systems. Our reference platform is Ubuntu 12.04 with the g++ compiler version 4.6.3 (confirmed to work on Ubuntu releases 11.04, 11.10)
    22 Download the latest ariba package from the [http://ariba-underlay.org/downloads download site]:
     28ariba currently builds on Linux systems. Our reference platform is Ubuntu 12.04 with the g++ compiler version 4.6.3 (confirmed to work on Ubuntu releases 11.04, 11.10). However other Linux distributions should work too.
     29
     30Download the latest ariba package from the [http://ariba-underlay.org/downloads download site]
    2331
    2432Extract the archive and change into the project directory:
    … …  
    2836}}}
    2937
    30 Alternatively, you could try to use the latest development code from our SVN trunk:
     38Alternatively, you could try to use the latest development code from our SVN trunk (attention: the code on trunk might break from time to time):
    3139{{{
    3240> svn co https://svn.tm.kit.edu/SpoVNet-KA/entwicklung/ariba/trunk ariba-trunk
    … …  
    3442}}}
    3543
    36 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.:
     44
     45Now create a directory to build ariba in:
    3746{{{
    38 > ./configure
     47> mkdir build
     48> cd build
     49}}}
     50
     51Next the makefiles have to be generated and the source compiled:
     52{{{
     53> cmake ..
    3954> make
     55}}}
     56
     57HINT: you may use
     58{{{
     59> make -j 2
     60}}}
     61for a dual processor/core system to speed up the compilation,
     62make -j 4 if you have quad-core respectively, and so on. If
     63the compilation stops, try make without the -j option again.
     64
     65And finally ariba will be installed into the system:
     66{{{
    4067> make install
    4168}}}
    4269
    43 If you want to install as root, do
     70
     71== Custom Build Options ==
     72
     73The build may be customized in various ways by setting CMake options. This can be done by giving them as arguments on the command line
    4474{{{
    45 > sudo make install
    46 > sudo ldconfig
     75> cmake .. -DOPTION=value
     76}}}
     77by using the CMake GUI which lets you set the variables graphically
     78{{{
     79> cmake-gui ..
     80}}}
     81or running cmake in interactive mode
     82{{{
     83> cmake -i ..
    4784}}}
    4885
    49 In case you don't want to install Ariba into your system but to a local place, do:
     86''TIP: The last two ways also give an overview which options exist.''
     87
     88=== Important Options ===
     89
     90 `CMAKE_INSTALL_PREFIX`::
     91   Where to install the compiled files. The default on Unix platforms is `/usr/local/`. If you for example don't want or can't install system wide, you can specify a directory you have control over. The files will be installed to "`${prefix}/include/`", "`${prefix}/lib/`" and so on.
     92
     93 `CMAKE_BUILD_TYPE`::
     94   One of "", "`Release`", "`Debug`", "`RelWithDebInfo`" or "`MinSizeRel`". This influences the build in various ways (which compiler optimizations are turned on, whether debug symbols are included, what warnings to show etc.).
     95
     96 `ENABLE_{AVAHI,BLUETOOTH,LOG4CXX}`::
     97   If set to `OFF` (or `0` (zero) – `ON` is the default) it disables the support of the feature even if the corresponding library ([#Prerequisites see above]) was detected to be present.
     98
     99 `<library>_INCLUDE_DIR`::
     100   Where the directory containing the header files for `<library>` is located. If the library is installed in the usual system paths CMake should be able to automatically find the right location. If the library is located elsewhere (e.g. because you compiled it yourself in your home directory) then you may need to set this variable manually.
     101
     102 `<library>_LIBRARY`::
     103   Where the library file (aka the .so, .a or .dll file) for `<library>` is located. If the library is installed in the usual system paths CMake should be able to automatically find the right location. If the library is located elsewhere (e.g. because you compiled it yourself in your home directory) then you may need to set this variable manually.
     104
     105 `DOCUMENTATION_GENERATE_GRAPHICS`::
     106   Whether the documentation should include graphics such as inheritance and include graphs (`OFF` by default). This might take a long time and consume a lot of space.
     107
     108 `CMAKE_{C,CXX}_COMPILER`::
     109   Which C/C++ compiler to use
     110
     111 `CMAKE_{C,CXX}_FLAGS`::
     112   Which additional flags to give to the compiler (e.g. `-pg` for profiling support)
     113
     114
     115=== Building the Documentation ===
     116
     117To build the documentation once you can build the "docu" target:
    50118{{{
    51 > mkdir build
    52 > ./configure --prefix=$PWD/build
    53 > make
    54 > make install
     119> make docu
    55120}}}
    56121
    57 == Local install (Download library dependencies and install ariba in a local subdirectory) ==
     122If you want to build the documentation on every build you can enable the `ALWAYS_BUILD_DOCUMENTATION` option in CMake.
    58123
    59 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.
    60124
    61 {{{
    62 with_boost=/home/foo/Libraries/include
    63 test -z "$CPPFLAGS" && CPPFLAGS='-I/home/foo/Libraries/include'
    64 test -z "$LDFLAGS" && LDFLAGS='-L/home/foo/Libraries/lib'
    65 }}}
    66 
    67 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:
    68 
    69 {{{
    70 test -z "$CPPFLAGS" && CPPFLAGS='-I/home/foo/Libraries/include -I/home/foo/otherlibrary/include'
    71 }}}
    72125
    73126== Running the !PingPong Sample ==
    74127
    75 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.
    76 
     128The !PingPong binary `pingpong` is installed in "`${prefix}/lib/ariba/`" or found directly in the build tree at "`sample/pingpong/pingpong`". It has one parameter, a configuration file. You can find sample configuration files in the "`etc/pingpong`" 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.
    77129{{{
    78 > ./pingpong ../../etc/pingpong/settings_node1.cnf
    79 }}}
    80 
    81 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}}}
    82 {{{
    83 > export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/home/user/ariba/build/lib
     130> ./sample/pingpong/pingpong ../etc/pingpong/settings_node1.cnf
    84131}}}
    85132
    86133When 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.
    87134
    88 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.
     135Once 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 switch from LAN connection to WLAN. The links established by the !PingPong sample through ariba are mobility invariant and automatically repaired.
    89136
    90 === Selecting a compiler ===
    91137
    92 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:
    93 {{{
    94 ./configure --prefix=... CXX=g++-4.1
    95 }}}
    96 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:
    97 {{{
    98 using gcc : 4.1 ;
    99 }}}
    100 and then build using bjam as described in {{{http://www.boost.org/doc/libs/1_38_0/more/getting_started/unix-variants.html}}}.
    101138
    102 === Cross-Comiling for Maemo ===
     139== Cross-Comiling for Maemo ==
    103140
    104 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.
     141Ariba 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.
    105142
    106 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:
     143If you compile for Maemo you have to set the `HAVE_MAEMO` option in CMake.
     144
     145Internally 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:
    107146{{{
    108147#!cpp
    … …  
    114153}}}
    115154
    116 {{{
    117 #!comment
    118 === Installing libraries locally ===
    119 
    120 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).
    121 
    122 {{{
    123 > cd ~/
    124 > mkdir local
    125 > cd boost_1_38_0
    126 > ./configure --prefix=/home/user/local
    127 > make install
    128 > cd ..
    129 > cd log4cxx-0.10.0
    130 > ./configure --prefix=/home/user/local
    131 > make install
    132 }}}
    133 
    134 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}}}.
    135 
    136 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.
    137 
    138 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:
    139 
    140 {{{
    141 > cd ~/ariba-x.x.x
    142 > mkdir build
    143 > ./configure
    144   --prefix=/home/user/ariba-x.x.x/build
    145   --with-boost=/home/user/local/include/boost   
    146   CPPFLAGS='-I/home/user/local/include'
    147   LDFLAGS='-L/home/user/local/lib'
    148 > make
    149 > make install
    150 }}}
    151 
    152 This will build and install Ariba into the created {{{build}}} folder.
    153 COMMENT_END
    154 }}}
    155 
    156 
    157 {{{
    158 #!comment
    159 
    160 == Building for Simulations ==
    161 
    162 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. 
    163 
    164 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
    165 
    166 {{{
    167 > ./configure --prefix=$PWD/build
    168   CPPFLAGS='-I/home/user/omnet/include
    169   -I/home/user/inet/Network/IPv4
    170   -I/home/user/inet/Base
    171   -I/home/user/inet/Network/Contract
    172   -I/home/user/inet/NetworkInterfaces/Contract
    173   -I/home/user/inet/Transport/TCP
    174   -I/home/user/inet/Transport/UDP
    175   -I/home/user/inet/Transport/Contract'
    176   --enable-simulation=yes
    177 > make
    178 > make install
    179 }}}
    180 
    181 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.
    182 
    183 == Running the Simulated !PingPong Sample ==
    184 
    185 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.
    186 
    187 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.
    188 
    189 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.
    190 
    191  * {{{--enable-simulation=yes}}} - for building for simulation integration
    192 
    193 COMMENT_END
    194 }}}
    195 
    196 === Overview of special {{{configure}}} options ===
    197 
    198 There are several options to {{{configure}}} that are specific to Ariba:
    199 
    200  * {{{--enable-debug=yes}}} - for building a debug build
    201  * {{{--enable-profiling=yes}}} - for profiling with gprof
    202  * {{{--enable-logcolors=yes}}} - for colorful logging output
    203  * {{{--enable-doxygen=yes}}} - for generating doxygen documentation (do a {{{make html-local}}} in {{{ariba/docu/doxygen}}})