Index: INSTALL =================================================================== --- INSTALL (revision 10642) +++ INSTALL (revision 10700) @@ -5,44 +5,50 @@ about Ariba and its application. + Prerequisites ============= ariba depends on libraries that may not be installed on your system: - * Boost (version >=1.39) - * Log4cxx (version >= 0.10.0) - * GMP (no specific version) + * Boost (version >=1.42) + * GMP + * CMake (version >=2.8) -Furthermore, you need default development tools - that are most likely already installed on your system - such as -gcc/g++, autoconf, automake, aclocal, libtool, liblt-dev ... +and optionally on + + * Log4Cxx (version >= 0.10.0) for more sophisticated logging + * Avahi for more efficient bootstrapping in local networks + * LibBluetooth/Bluez for bluetooth support + * Doxygen to build the documentation + +Furthermore, you need default development tools - that are most likely already +installed on your system - such as gcc/g++, libtool, liblt-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. However, latest -Ubuntu releases should work, too. Download the latest -ariba package from the the download site -http://ariba-underlay.org/downloads -or get the latest trunk code: -svn co https://svn.tm.kit.edu/SpoVNet-KA/entwicklung/ariba/trunk ariba-trunk +ariba currently builds on Linux systems. Our reference platform is Ubuntu 8.04 +with the g++ compiler version 4.1. However, latest Ubuntu releases should work +too. -Extract the archive and change into the project directory: +Download the latest ariba package from the the download site +http://ariba-underlay.org/downloads or get the latest trunk code: +> svn co https://svn.tm.kit.edu/SpoVNet-KA/entwicklung/ariba/trunk ariba-trunk +If you downloaded ariba from the website extract the archive and change into the +project directory: > tar xfz ./ariba-x.x.x.tar.gz > cd ariba-x.x.x -For SVN checkout you have to +For SVN checkout you have to: > cd ariba-trunk -Now, configure, compile, and install ariba (if not all libraries -needed by Ariba are available on your system, read the section -'Prequisites'). +Now create a directory to build ariba in: +> mkdir build +> cd build -If no configure script is available (e.g. when you checked out an svn -version), run the ./bootstrap script first and then type: - -> ./configure +Next the makefiles have to be generated and the source compiled: +> cmake .. > make -> make install HINT: you may use @@ -52,113 +58,106 @@ the compilation stops, try make without the -j option again. - -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 +And finally ariba will be installed into the system: > make install -Local install (Download library dependencies and install ariba in a -============= local subdirectory) +Custom Build Options +==================== +The build may be customized in various ways by setting CMake options. This can +be done by giving them as arguments on the command line: +> cmake .. -DOPTION=value +by using the CMake GUI which lets you set the variables graphically: +> cmake-gui .. -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: +or running cmake in interactive mode: +> cmake -i .. -> tar xfz ./ariba-x.x.x.tar.gz -> cd ariba-x.x.x -> ./bootstrap_libs +The last two ways also give an overview which options exist. -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. +Important options: -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. +CMAKE_INSTALL_PREFIX - 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. -with_boost=/home/foo/Libraries/include -test -z "$CPPFLAGS" && CPPFLAGS='-I/home/foo/Libraries/include' -test -z "$LDFLAGS" && LDFLAGS='-L/home/foo/Libraries/lib' +CMAKE_BUILD_TYPE - One of "", "Release", "Debug", "RelWithDebInfo" or + "MinSizeRel". This influences the build in various ways + (e.g. which compiler optimizations are turned on, whether + debug symbols are included, what warnings to show). -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: +ENABLE_{AVAHI,BLUETOOTH,LOG4CXX} + - If set to OFF or 0 (ON is the default) it disables the + support of the feature even if the corresponding library + (see above) was detected to be present. -test -z "$CPPFLAGS" && CPPFLAGS='-I/home/foo/Libraries/include -I/home/foo/otherlibrary/include' +_INCLUDE_DIR - Where the directory containing the header files for + 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. + +_LIBRARY - Where the library file (aka the .so, .a or .dll file) for + 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. + +DOCUMENTATION_GENERATE_GRAPHICS + - 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. + +CMAKE_{C,CXX}_COMPILER - Which C/C++ compiler to use +CMAKE_{C,CXX}_FLAGS - Which additional flags to give to the compiler (e.g. -pg + for profiling support) + 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. +The 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. +> ./sample/pingpong/pingpong ../etc/pingpong/settings_node1.cnf -> ./pingpong ../../etc/pingpong/settings_node1.cnf +If this fails 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/source/ariba -If this fails 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 +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. -> export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/home/user/ariba/build/lib +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. -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 +Cross-Compiling 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 Scratchbox. Use the +preassembled Scratchbox version provided by Nokia which will install and +configure the complete Scratchbox system automatically. -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: +If you compile for Maemo you have to set the HAVE_MAEMO option in CMake. -./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 -Scratchbox. Use the 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: +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: #include "ariba/config.h" @@ -167,12 +166,2 @@ // special Maemo handling #endif - -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) -