docs: Adding example of how to build ndnSIM using non-root-installed boost libraries
This commit also includes an example of how to build boost libraries
with one of the known pitfalls.
closes #8
diff --git a/docs/source/boost-custom-install.rst b/docs/source/boost-custom-install.rst
new file mode 100644
index 0000000..34ae785
--- /dev/null
+++ b/docs/source/boost-custom-install.rst
@@ -0,0 +1,50 @@
+Installing boost libraries
+==========================
+
+Normally, to compile and install boost libraries in non-privileged mode, you would need to issue following commands (e.g., for boost version 1.51.0)::
+
+ export BOOSTDIR=/home/non-privileged-user/boost
+
+ wget http://downloads.sourceforge.net/project/boost/boost/1.51.0/boost_1_51_0.tar.bz2
+ tar jxf boost_1_51_0.tar.bz2
+ cd boost_1_51_0
+ ./bootstrap.sh
+ ./b2 --prefix=$BOOSTDIR install
+
+However, after the following steps you may still not able to use ndnSIM.
+
+Common pitfalls
+---------------
+
+The common pitfalls is with boost iostreams library, which is failed to build because of missing bzip2 library.
+This problem can be easily fixed by downloading and installing bzip2 library, e.g., using the following steps::
+
+ wget http://www.bzip.org/1.0.6/bzip2-1.0.6.tar.gz
+ tar zxf bzip2-1.0.6.tar.gz
+ cd bzip2-1.0.6
+ make PREFIX=$BOOSTDIR CFLAGS="-fPIC -O2 -g" install
+
+Afte bzip2 library is installed, you may recompile and reinstall boost libraries using custom compilation flags::
+
+ ./b2 --prefix=$BOOSTDIR cxxflags=-I$BOOSTDIR/include linkflags=-L$BOOSTDIR/lib install
+
+Alternatively, you can solve this particular problem by installing development package for bzip2 library (if you have root access). For example, on Ubuntu 12.04 it would be the following command::
+
+ sudo apt-get install libbz2-dev
+
+And then compiling and installing boost without custom compilation flags::
+
+ ./b2 --prefix=$BOOSTDIR
+
+
+Compiling NS-3 with custom boost libraries
+==========================================
+
+The following commands should allow compilation and run of NS-3 simulations with custom install of boost libraries::
+
+ cd <ns-3>
+ ./waf configure --boost-includes=$BOOSTDIR/include --boost-libs=$BOOSTDIR/lib --enable-examples --enable-ndn-plugins=topology,mobility
+ LD_LIBRARY_PATH=$BOOSTDIR/lib NS_LOG=ndn.Face:ndn.Consumer ./waf --run=ndn-simple
+
+.. note::
+ `LD_LIBRARY_PATH=$BOOSTDIR/lib` is necessary on Linux platform in order for the dynamic linker to find libraries installed in a location different from one of the folders specified in /etc/ld.so.conf.
diff --git a/docs/source/index.rst b/docs/source/index.rst
index db110f4..3a2f47e 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -12,3 +12,4 @@
helpers
applications
examples
+ boost-custom-install
diff --git a/docs/source/intro.rst b/docs/source/intro.rst
index a70ab1a..5ec2355 100644
--- a/docs/source/intro.rst
+++ b/docs/source/intro.rst
@@ -85,6 +85,10 @@
sudo port instal boost
+.. note::
+ !!! If you do not have root permissions to install boost, you can install it in your home folder. However, you need to be make sure that `libboost_iostreams` library is successfully compiled and is installed. Please refer to :doc:`the following example <boost-custom-install>` for the hints how to successfully compile and install boost libraries on Ubuntu Linux.
+
+
3. If you are planning to use other modules, like visualizer, a number of additional dependencies should be installed. For example, in
order to run `visualizer`_ module, the following should be installed: