docs: small documentation update (restructured FAQ about boost libraries)
diff --git a/docs/ns3_html_theme/static/ns3_stylesheet.css b/docs/ns3_html_theme/static/ns3_stylesheet.css
index 341b70a..c900197 100644
--- a/docs/ns3_html_theme/static/ns3_stylesheet.css
+++ b/docs/ns3_html_theme/static/ns3_stylesheet.css
@@ -124,3 +124,8 @@
.highlight .hll {
background-color: #FFFF88;
}
+
+.red {
+ color: red;
+ font-weight: bold;
+}
\ No newline at end of file
diff --git a/docs/source/boost-custom-install.rst b/docs/source/boost-custom-install.rst
deleted file mode 100644
index 17a9564..0000000
--- a/docs/source/boost-custom-install.rst
+++ /dev/null
@@ -1,52 +0,0 @@
-.. _boost-custom-install:
-
-.. 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/faq.rst b/docs/source/faq.rst
index 9ec64b3..c03e341 100644
--- a/docs/source/faq.rst
+++ b/docs/source/faq.rst
@@ -4,13 +4,110 @@
Boost libraries
---------------
-.. topic:: Custom boost libraries compilation problem
+.. note::
+ **My ubuntu/redhat/freebsd have an old version of boost libraries. How can I get the latest one?**
- I'm trying to use custom boost libraries, but something is going wrong. What should I do?
+.. _Installing boost libraries:
-.. Please refer to :ref:`boost-custom-install` section for an example how custom boost libraries could be built.
+Installing boost libraries to ``/usr/local``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-.. include:: boost-custom-install.rst
+.. role:: red
+
+.. note::
+ **The following instructions are for those who want to install latest version of boost libraries** :red:`and has root access`.
+
+The following commands would install the latest version of boost libraries (at the time of writing, version 1.52) ot ``/usr/local``, assuming you have a root access to your machine.
+If you don't have root access, please refer to section :ref:`Installing boost libraries to a non-privileged location`.
+
+.. note::
+ If you are using Ubuntyu, make sure that you have installed ``libbz2-dev``, otherwise not all libraries required by ndnSIM will be installed (see :ref:`Common pitfalls`)
+
+.. code-block:: bash
+ :linenos:
+
+ wget http://downloads.sourceforge.net/project/boost/boost/1.52.0/boost_1_52_0.tar.bz2
+ tar jxf boost_1_52_0.tar.bz2
+ cd boost_1_52_0
+ ./bootstrap.sh
+ sudo ./b2 --prefix=/usr/local install
+
+
+The following commands should allow compilation and run of NS-3 simulations with custom install of boost libraries:
+
+.. code-block:: bash
+ :linenos:
+
+ cd <ns-3>
+ ./waf configure --boost-includes=/usr/local/include --boost-libs=/usr/local/lib --enable-examples
+ ./waf
+ LD_LIBRARY_PATH=/usr/local/lib NS_LOG=ndn.Face:ndn.Consumer ./waf --run=ndn-simple
+
+.. note::
+ `LD_LIBRARY_PATH=/usr/local/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.
+
+.. _Installing boost libraries to a non-privileged location:
+
+Installing boost libraries to a non-privileged location
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. note::
+ **Follow these general instructions if you are trying to installboost libraries to a non-privileged location** :red:`(i.e., you do not have root access),` **but something is going wrong.**
+
+Normally, to compile and install boost libraries in non-privileged mode, you would need to issue following commands (e.g., for boost version 1.52.0):
+
+.. code-block:: bash
+ :linenos:
+
+ export BOOSTDIR=/home/non-privileged-user/boost
+ wget http://downloads.sourceforge.net/project/boost/boost/1.52.0/boost_1_52_0.tar.bz2
+ tar jxf boost_1_52_0.tar.bz2
+ cd boost_1_52_0
+ ./bootstrap.sh
+ ./b2 --prefix=$BOOSTDIR install
+
+However, after the following steps you may still not able to use ndnSIM.
+
+.. _Common pitfalls:
+
+Common pitfalls
+^^^^^^^^^^^^^^^
+
+The common pitfalls is with the **boost iostreams** library, which is required by ndnSIM, but failed to build because of the missing bzip2 library.
+This problem can be easily fixed by downloading and installing bzip2 library, e.g., using the following steps:
+
+.. code-block:: bash
+ :linenos:
+
+ 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 (:red:`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
+
+
+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
+ ./waf
+ 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.
+
+
Visualizer problems
-------------------
@@ -85,5 +182,4 @@
I found an error in the documentation / bug in the code. What should I do?
-Please create an issue for the documentation error or code bug.
-We will try to resolve the problem as fast as we can.
+Please create an issue for the documentation error or code bug on `github <http://github.com/NDN-Routing/ndnSIM>`_, or tell us about the error on `our mailing list <http://www.lists.cs.ucla.edu/mailman/listinfo/ndnsim>`_ .
diff --git a/docs/source/getting-started.rst b/docs/source/getting-started.rst
index 02ae504..698e6d3 100644
--- a/docs/source/getting-started.rst
+++ b/docs/source/getting-started.rst
@@ -23,8 +23,13 @@
sudo port instal boost
+.. role:: red
+
.. 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.
+ :red:`!!! ndnSIM requires boost version at least 1.48.` Many linux distribution (including Ubuntu 12.04.1 at the time of this writing) ship an old version of boost, making it impossible to compile ndnSIM out-of-the-box. Please install the latest version, following :ref:`these simple instructions <Installing boost libraries>`.
+
+.. 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 :ref:`the following example <Installing boost libraries>` 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
@@ -68,19 +73,19 @@
ndnSIM uses standard NS-3 compilation procedure. Normally the following commands should be sufficient to configure and build ndnSIM with python bindings enabled::
cd <ns-3-folder>
- ./waf configure --enable-examples --enable-ndn-plugins=topology,mobility
+ ./waf configure --enable-examples
./waf
On MacOS (with macports), you may need to modify the configure command to use macports version of python::
cd <ns-3-folder>
- ./waf configure --with-python=/opt/local/bin/python2.7 --enable-examples --enable-ndn-plugins=topology,mobility
+ ./waf configure --with-python=/opt/local/bin/python2.7 --enable-examples
./waf
Python bindings is an optional and not very stable feature of NS-3 simulator. It is possible to disable python bindings compilation either to speed up compilation or to avoid certain compilation errors (e.g., "Could not find a task generator for the name 'ns3-visualizer'")::
cd <ns-3-folder>
- ./waf configure --disable-python --enable-examples --enable-ndn-plugins=topology,mobility
+ ./waf configure --disable-python --enable-examples
./waf
For more configuration options, please refer to ``./waf --help``.
@@ -104,10 +109,4 @@
.. note::
Do not forget to configure and compile NS-3 in optimized mode (``./waf configure -d optimized``) in order to run actual simulations.
-Additional compiling options
-++++++++++++++++++++++++++++
-
-ndnSIM contains a number of NS-3 extensions that are not technically part of the ndnSIM. Right now there are two optional plugins---topology and mobility---which can be enabled using the following configuration option::
-
- ./waf configure --enable-ndn-plugins=topology,mobility
diff --git a/docs/source/intro.rst b/docs/source/intro.rst
index 845dd1c..62a12b2 100644
--- a/docs/source/intro.rst
+++ b/docs/source/intro.rst
@@ -83,6 +83,7 @@
To create new feature, please fork the code and submit Pull Request on GitHub.
+And of course, `our mailing list <http://www.lists.cs.ucla.edu/mailman/listinfo/ndnsim>`_ is the best way to communicate with and get support from ndnSIM team and other users of ndnSIM.
A very short guide to the code
------------------------------