docs: Documentation update
Change-Id: I6f916eb822a59e980e8fb1134886c3431755119c
diff --git a/docs/source/getting-started.rst b/docs/source/getting-started.rst
index 77c89e2..23ff20d 100644
--- a/docs/source/getting-started.rst
+++ b/docs/source/getting-started.rst
@@ -4,59 +4,46 @@
Portability
------------
-ndnSIM has been successfully compiled and used under Ubuntu Linux 12.04 (boost libraries **1.48**, with default version 1.46 compilation will probably fail), 12.10 (default version of boost 1.49), 13.04 (default version of boost 1.49), Fedora 18, Mac OS 10.7 and 10.8 (gcc-4.2 apple/llvm, macports gcc 4.7, boost 1.49-1.54).
+ndnSIM has been successfully compiled and used under Ubuntu Linux 12.04 (only with boost
+libraries **1.48**), 14.04 (default version of boost), OS X 10.10 (Xcode 6.1.1, macports boost
+1.56-1.57).
.. _requirements:
-Requirements
+Prerequisites
-------------
-1. ndnSIM requires the customized version of NS-3 simulator (a number of patches required to make ndnSIM work with the latest development branch of NS-3).
-
-2. Boost libraries should be installed on the system:
-
- * For Ubuntu
-
- * 12.04
-
- .. code-block:: bash
-
- sudo aptitude install libboost1.48-all-dev
-
- * 12.10, 13.04, and newer versions
-
- .. code-block:: bash
-
- sudo aptitude install libboost-all-dev
-
- * For Fedora (for Fedora 18 and later only):
-
- .. code-block:: bash
-
- sudo yum install boost-devel
-
- * For MacOS (macports):
-
- .. code-block:: bash
-
- sudo port instal boost
+1. `ndnSIM also required ndn-cxx library and all of its prerequisites
+ <http://named-data.net/doc/ndn-cxx/current/INSTALL.html>`_.
.. role:: red
.. note::
- :red:`!!! ndnSIM requires boost version at least 1.48.` Many linux distribution (Fedora 16, 17 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>`.
+ :red:`!!! ndn-cxx and ndnSIM requires boost version at least 1.48.` Many linux distribution
+ (Fedora 16, 17 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::
- :red:`For Ubuntu 12.04` Ubuntu 12.04 ships with two versions of boost libraries and it is known that if both are installed, then compilation of ndnSIM will most likely fail. Please install ``libboost1.48-dev-all`` package and uninstall ``libboost-dev-all``. If you want to install the latest version of boost libraries, then uninstall both ``libboost1.48-dev-all`` and ``libboost-dev-all``, so the libraries do not interfere with each other.
+ :red:`For Ubuntu 12.04` Ubuntu 12.04 ships with two versions of boost libraries and it is
+ known that if both are installed, then compilation of ndnSIM will most likely fail. Please
+ install ``libboost1.48-dev-all`` package and uninstall ``libboost-dev-all``. If you want to
+ install the latest version of boost libraries, then uninstall both ``libboost1.48-dev-all``
+ and ``libboost-dev-all``, so the libraries do not interfere with each other.
.. 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.
+ !!! 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
-order to run `visualizer`_ module, the following should be installed:
+2. 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:
- * For Ubuntu (tested on Ubuntu 12.04, 12.10, 13.04, should work on later versions as well):
+ * For Ubuntu (tested on Ubuntu 14.04, should work on later versions as well):
.. code-block:: bash
@@ -81,106 +68,155 @@
sudo port install py27-pygraphviz py27-goocanvas
-.. py27-kiwi
+ # If you add NDN macports repository, as described in
+ # http://named-data.net/doc/NFD/current/INSTALL.html#install-nfd-using-the-ndn-macports-repository-on-os-x
+ # you will be able to install another useful python module
+ # sudo port install py27-kiwi
.. _visualizer: http://www.nsnam.org/wiki/index.php/PyViz
Downloading ndnSIM source
-------------------------
-Download a custom branch of NS-3 that contains all necessary patches, python binding generation library (optional), and clone actual ndnSIM code and place it in src/ folder:
+ndnSIM package consists of three pieces:
+
+- `ndn-cxx library <http://named-data.net/doc/ndn-cxx/>`_
+- a custom branch of NS-3 that contains a few useful patches
+- a customized python binding generation library (necessary if you want to use NS-3's python
+ bindings and/or visualizer module)
+- the source code of ndnSIM module
+
+The following commands download all pieces from GitHub repositories:
.. code-block:: bash
- mkdir ndnSIM
- cd ndnSIM
- git clone git://github.com/cawka/ns-3-dev-ndnSIM.git ns-3
- git clone git://github.com/cawka/pybindgen.git pybindgen
- git clone git://github.com/NDN-Routing/ndnSIM.git ns-3/src/ndnSIM
+ mkdir ndnSIM
+ cd ndnSIM
+ git clone https://github.com/named-data/ndn-cxx.git ndn-cxx
+ git clone https://github.com/cawka/ns-3-dev-ndnSIM.git ns-3
+ git clone https://github.com/cawka/pybindgen.git pybindgen
+ git clone https://github.com/named-data/ndnSIM.git ns-3/src/ndnSIM
-There are quite a few modification to the base NS-3 code that are necessary to run ndnSIM, and the code is periodically synchronized with the official developer branch. Eventually, all the changes will be merged to the official branch, but for the time being, it is necessary to use the customized branch.
+The few modification to the base NS-3 code are necessary to run ndnSIM, and the code is
+periodically synchronized with the official developer branch. Eventually, all the changes will
+be merged to the official branch, but for the time being, it is necessary to use the customized
+branch.
-If you have problems connecting to github, you can try to clone from google servers:
-
-.. code-block:: bash
-
- mkdir ndnSIM
- cd ndnSIM
- git clone https://code.google.com/p/ndnsim.ns3-base/ ns-3
- git clone https://code.google.com/p/ndnsim.pybindgen/ pybindgen
- git clone https://code.google.com/p/ndnsim/ ns-3/src/ndnSIM
Compiling and running ndnSIM
----------------------------
-ndnSIM uses standard NS-3 compilation procedure. Normally the following commands should be sufficient to configure and build ndnSIM with python bindings enabled:
+- Compile and install ndn-cxx library
-.. code-block:: bash
+ .. code-block:: bash
- cd <ns-3-folder>
- ./waf configure --enable-examples
- ./waf
+ cd ndnSIM/ndn-cxx
+ ./waf configure
+ ./waf
+ sudo ./waf install
-On MacOS (with macports), you may need to modify the configure command to use macports version of python:
+ .. note::
+ On Ubuntu platform you can also install ndn-cxx library from `NDN
+ PPA repository <http://named-data.net/doc/NFD/current/INSTALL.html#installing-nfd-from-binaries>`_
-.. code-block:: bash
+ .. code-block:: bash
- cd <ns-3-folder>
- ./waf configure --with-python=/opt/local/bin/python2.7 --enable-examples
- ./waf
+ sudo apt-get install ndn-cxx
-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'"):
+- Compile NS-3 with ndnSIM module
-.. code-block:: bash
+ 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 --disable-python --enable-examples
- ./waf
+ .. code-block:: bash
-For more configuration options, please refer to ``./waf --help``.
+ cd <ns-3-folder>
+ ./waf configure --enable-examples
+ ./waf
-To run :doc:`sample ndnSIM simulations <examples>`:
+ On MacOS (with macports), you may need to modify the configure command to use macports
+ version of python:
-.. code-block:: bash
+ .. code-block:: bash
- ./waf --run=ndn-simple
+ cd <ns-3-folder>
+ ./waf configure --with-python=/opt/local/bin/python2.7 --enable-examples
+ # or run ``sudo port select python python27``
+ ./waf
-or:
+ 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'"):
-.. code-block:: bash
+ .. code-block:: bash
- ./waf --run=ndn-grid
+ cd <ns-3-folder>
+ ./waf configure --disable-python --enable-examples
+ ./waf
-If you have compiled with python bindings, then you can try to run these simulations with visualizer:
-
-.. code-block:: bash
-
- ./waf --run=ndn-simple --vis
-
-or:
-
-.. code-block:: bash
-
- ./waf --run=ndn-grid --vis
-
-.. note::
- Do not forget to configure and compile NS-3 in optimized mode (``./waf configure -d optimized``) in order to run actual simulations.
-
+ For more configuration options, please refer to ``./waf --help``.
Simulating using ndnSIM
-----------------------
-While it is possible to write simulations directly inside NS-3 (in ``scratch/`` folder) or ndnSIM (in ``examples/``), the recommended way is to write your simulation scenarios, as well as any custom extensions, separately from the NS-3 or ndnSIM core.
+- Examples simulations
-For example, you can use the following template to write your extensions, simulation scenarios, and metric processing scripts: `<http://github.com/cawka/ndnSIM-scenario-template>`_:
+ When NS-3 is compiled with ``--with-examples`` flag, you can directly run all examples
+ described in :doc:`examples section of this tutorial <examples>`. For example, to run
+ ``ndn-simple.cpp`` scenario, you can run the following command:
-.. code-block:: bash
+ .. code-block:: bash
- mkdir ndnSIM
- cd ndnSIM
- git clone git://github.com/cawka/ns-3-dev-ndnSIM.git ns-3
- git clone git://github.com/cawka/pybindgen.git pybindgen
- git clone git://github.com/NDN-Routing/ndnSIM.git ns-3/src/ndnSIM
+ ./waf --run=ndn-simple
+
+ To run ``ndn-grid.cpp` scenario:
+
+ .. code-block:: bash
+
+ ./waf --run=ndn-grid
+
+ To run the sample simulation scenarios with the logging module of NS-3 enabled (note that
+ this will work only when NS-3 is compiled in debug mode):
+
+ .. code-block:: bash
+
+ NS_LOG=ndn.Producer:ndn.Consumer ./waf --run=<scenario name>
+
+ If you have compiled with python bindings, then you can try to run these simulations with
+ visualizer:
+
+ .. code-block:: bash
+
+ ./waf --run=ndn-simple --vis
+
+ or:
+
+ .. code-block:: bash
+
+ ./waf --run=ndn-grid --vis
+
+ .. note::
+ Do not forget to configure and compile NS-3 in optimized mode (``./waf configure -d
+ optimized``) in order to run actual simulations.
+
+- Real experimentation
+
+ While it is possible to write simulations directly inside NS-3 (in ``scratch/`` folder) or
+ ndnSIM (in ``examples/``), the recommended way is to write your simulation scenarios, as
+ well as any custom extensions, separately from the NS-3 or ndnSIM core.
+
+ For example, you can use the following template to write your extensions, simulation
+ scenarios, and metric processing scripts:
+ `<http://github.com/cawka/ndnSIM-scenario-template>`_:
+
+ .. code-block:: bash
+
+ mkdir ndnSIM
+ cd ndnSIM
+ git clone git://github.com/cawka/ns-3-dev-ndnSIM.git ns-3
+ git clone git://github.com/cawka/pybindgen.git pybindgen
+ git clone git://github.com/NDN-Routing/ndnSIM.git ns-3/src/ndnSIM
# Build and install NS-3 and ndnSIM
cd ns-3
@@ -199,7 +235,8 @@
./waf --run <scenario>
-For more detailed information, refer to `README file <https://github.com/cawka/ndnSIM-scenario-template/blob/master/README.md>`_.
+ For more detailed information, refer to `README file
+ <https://github.com/cawka/ndnSIM-scenario-template/blob/master/README.md>`_.
Examples of template-based simulations
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -207,19 +244,19 @@
1. ndnSIM examples from `<http://ndnsim.net>`_ website and more:
- `<http://github.com/cawka/ndnSIM-examples>`_, or
-- `<http://code.google.com/p/ndnsim.ndnsim-examples/>`_
-2. Script scenarios and graph processing scripts for simulations used in "A Case for Stateful Forwarding Plane" paper by Yi et al. (`<http://dx.doi.org/10.1016/j.comcom.2013.01.005>`_):
+2. Script scenarios and graph processing scripts for simulations used in "A Case for Stateful
+ Forwarding Plane" paper by Yi et al. (`<http://dx.doi.org/10.1016/j.comcom.2013.01.005>`_):
- `<http://github.com/cawka/ndnSIM-comcom-stateful-fw>`_, or
-- `<http://code.google.com/p/ndnsim.ndnsim-comcom/>`_
-3. Script scenarios and graph processing scripts for simulations used in "Rapid Traffic Information Dissemination Using Named Data" paper by Wang et al. (`<http://dx.doi.org/10.1145/2248361.2248365>`_):
+3. Script scenarios and graph processing scripts for simulations used in "Rapid Traffic
+ Information Dissemination Using Named Data" paper by Wang et
+ al. (`<http://dx.doi.org/10.1145/2248361.2248365>`_):
- `<http://github.com/cawka/ndnSIM-nom-rapid-car2car>`_, or
-- `<http://code.google.com/p/ndnsim.ndnsim-nom-rapid/>`_
-- Rocketfuel-based topology generator for ndnSIM preferred format (randomly assigned link delays and bandwidth, based on estimated types of connections between nodes):
+- Rocketfuel-based topology generator for ndnSIM preferred format (randomly assigned link
+ delays and bandwidth, based on estimated types of connections between nodes):
- `<http://github.com/cawka/ndnSIM-sample-topologies>`_, or
-- `<http://code.google.com/p/ndnsim.ndnsim-sample-topo/>`_