docs: Documentation update, initial preparation for version 2.1 release
Change-Id: I3694a8791b9540fc1b926a83ff55421b47e0f1e2
diff --git a/docs/source/_templates/indexcontent.html b/docs/source/_templates/indexcontent.html
index 72634b2..55a4b08 100644
--- a/docs/source/_templates/indexcontent.html
+++ b/docs/source/_templates/indexcontent.html
@@ -1,81 +1,105 @@
{% extends "layout.html" %}
-{% set title = _('ndnSIM 2.0 documentation') %}
+{% set title = _('ndnSIM Documentation') %}
{% block body %}
<h1>{{ docstitle|e }}</h1>
-<p>ndnSIM 2.0 is a new release of <a class="reference external" href="http://ndnsim.net/1.0/">NS-3 based Named Data Networking (NDN) simulator</a> that went through extensive refactoring and rewriting. The key new features of the new version:</p>
-
-<ul class="simple">
-<li>ndnSIM no longer re-implements basic NDN primitives and directly uses implementation from <a class="reference external" href="http://named-data.net/doc/ndn-cxx/">ndn-cxx library (NDN C++ library with eXperimental eXtensions)</a>.</li>
-<li>All NDN forwarding and management is implemented directly using source code of <a class="reference external" href="http://named-data.net/doc/NFD/">Named
-Data Networking Forwarding Daemon (NFD)</a></li>
-<li>Packet format changed to the <a class="reference external" href="http://named-data.net/doc/ndn-tlv/">NDN packet format</a></li>
-</ul>
-
<p>
We invite you to <a href="http://www.lists.cs.ucla.edu/mailman/listinfo/ndnsim" target="_blank">join our mailing list</a> to see and participate in discussions about ndnSIM implementation and simulations in general (<a href="http://www.lists.cs.ucla.edu/pipermail/ndnsim/" target="_blank">mailing list archives</a>).
</p>
{% block tables %}
- <p><strong>Parts of the documentation:</strong></p>
- <table class="contentstable" align="center"><tr>
- <td width="50%" valign="top">
- <p class="biglink"><a class="biglink" href="{{ pathto("tutorial") }}">ndnSIM 2.0 tutorial</a><br/>
- <div class="linkdescr" style="margin-left: 20px">
- <p class="biglink"><a class="biglink" href="{{ pathto("intro") }}">Introduction</a><br/>
- <span class="linkdescr">what is ndnSIM, how to get support, and what is in the package</span></p>
- <p class="biglink"><a class="biglink" href="{{ pathto("getting-started") }}">Getting started</a><br/>
- <span class="linkdescr">portability, requirements, downloading, compiling, simulating</span></p>
- <p class="biglink"><a class="biglink" href="{{ pathto("helpers") }}">ndnSIM helpers</a><br/>
- <span class="linkdescr">very important components of ndnSIM for writing simulation scenarios</span></p>
- <p class="biglink"><a class="biglink" href="{{ pathto("cs") }}">Content Store</a><br/>
- <span class="linkdescr">several different build-in content store implementations: LRU, LFU, and others</span></p>
- <p class="biglink"><a class="biglink" href="{{ pathto("fw") }}">Forwarding Strategies</a><br/>
- <span class="linkdescr">experimenting with different build-in and custom Interest/Data forwarding strategies</span></p>
- <p class="biglink"><a class="biglink" href="{{ pathto("applications") }}">ndnSIM applications</a><br/>
- <span class="linkdescr">reference applications for network-leverl evaluations</span></p>
- <p class="biglink"><a class="biglink" href="{{ pathto("metric") }}">Obtaining metrics</a><br/>
- <span class="linkdescr">obtaining and visualizing metrics from simulation runs</span></p>
- </div>
- </p>
- <p class="biglink"><a class="biglink" href="{{ pathto("examples") }}">Simulation examples</a><br/>
- <span class="linkdescr">basic tutorial examples</span></p>
+ <!-- <p><strong>Parts of the documentation:</strong></p> -->
+ <table class="contentstable" align="center">
+ <tr>
+ <td width="50%" valign="top">
+ <h2>Getting Started</h2>
+ <div class="tile">
+ <p class="biglink"><a class="biglink" href="{{ pathto("intro") }}">Introduction</a><br/>
+ <span class="linkdescr">what is ndnSIM, how to get support, and what is in the package</span></p>
+ <p class="biglink"><a class="biglink" href="{{ pathto("getting-started") }}">Downloading and Compiling ndnSIM</a><br/>
+ <span class="linkdescr">requirements, downloading, compiling, simulating</span></p>
+ <p class="biglink"><a class="biglink" href="{{ pathto("faq") }}">FAQs</a><br/>
+ <span class="linkdescr">frequently asked questions (with answers!)</span></p>
+ <p class="biglink"><a class="biglink" href="{{ pathto("examples") }}">Simulation examples</a><br/>
+ <span class="linkdescr">basic tutorial examples</span></p>
+ </div>
+ </td>
+ <td width="50%" valign="top">
+ <h2>Advanced Topics</h2>
+ <div class="tile">
+ <p class="biglink"><a class="biglink" href="doxygen/annotated.html">ndnSIM API documentation</a><br/>
+ <span class="linkdescr">generated documentation of ndnSIM API</span></p>
+ <p class="biglink"><a class="biglink" href="{{ pathto("parallel-simulations") }}">Parallelize simulations using OpenMPI</a><br/>
+ <span class="linkdescr">how to use OpenMPI to parallelize execution of simulation scenarios</span></p>
+ <p class="biglink"><a class="biglink" href="{{ pathto("guide-to-simulate-real-apps") }}">Simulating real applications</a><br/>
+ <span class="linkdescr">guide on how to simulate real application that are written against ndn-cxx library</span></p>
+ </div>
+ </td>
+ </tr>
+ <tr>
+ <td width="50%" valign="top">
+ <h2>ndnSIM tutorial</h2>
+ <div class="tile">
+ <p class="biglink"><a class="biglink" href="{{ pathto("helpers") }}">ndnSIM helpers</a><br/>
+ <span class="linkdescr">very important components of ndnSIM for writing simulation scenarios</span></p>
+ <p class="biglink"><a class="biglink" href="{{ pathto("cs") }}">Content Store</a><br/>
+ <span class="linkdescr">several different build-in content store implementations: LRU, LFU, and others</span></p>
+ <p class="biglink"><a class="biglink" href="{{ pathto("fw") }}">Forwarding Strategies</a><br/>
+ <span class="linkdescr">experimenting with different build-in and custom Interest/Data forwarding strategies</span></p>
+ <p class="biglink"><a class="biglink" href="{{ pathto("applications") }}">ndnSIM applications</a><br/>
+ <span class="linkdescr">reference applications for network-leverl evaluations</span></p>
+ <p class="biglink"><a class="biglink" href="{{ pathto("metric") }}">Obtaining metrics</a><br/>
+ <span class="linkdescr">obtaining and visualizing metrics from simulation runs</span></p>
+ </div>
+ </td>
+ <td width="50%" valign="top">
+ <h2>ndnSIM Versions</h2>
+ <div class="tile">
+ <p class="biglink"><a class="biglink" href="#">ndnSIM 2.1</a><br/>
+ <span class="linkdescr">latest version</span></p>
+ <p class="biglink"><a class="biglink" href="http://ndnsim.net/2.0/">ndnSIM 2.0</a><br/>
+ <p class="biglink"><a class="biglink" href="http://ndnsim.net/1.0/">ndnSIM 1.0</a><br/>
+ </div>
+ </td>
+ </tr>
+ <tr>
+ <td width="50%" valign="top">
+ <h2>Publications</h2>
+ <div class="tile">
+ <p class="biglink"><a class="biglink" href="{{ pathto("ndnsim-research-papers") }}">ndnSIM-related publications</a><br/>
+ <span class="linkdescr">general papers about ndnSIM, research papers that use ndnSIM</span></p>
+ <p>If you are referring to ndnSIM in a published work, please cite the following papers, not just the ndnSIM website. Thank you!
+ <ul>
+ <li>
+ S. Mastorakis, A. Afanasyev, I. Moiseenko, and L. Zhang, “ndnSIM 2.0: A new version of the NDN simulator for NS-3,” NDN, Technical Report NDN-0028, 2015 (<a class="reference external" href="http://named-data.net/techreport/ndn-0028-1-ndnsim-v2.pdf">PDF</a>) (<a class="reference external" href="http://lasr.cs.ucla.edu/afanasyev/bibwiki/bibtex/399">BibTex</a>)
+ </li>
+ <li>
+ A. Afanasyev, I. Moiseenko, and L. Zhang, “ndnSIM: NDN simulator for NS-3,” NDN, Technical Report NDN-0005, 2012 (<a class="reference external" href="http://named-data.net/wp-content/uploads/TRndnsim.pdf">PDF</a>) (<a class="reference external" href="http://lasr.cs.ucla.edu/afanasyev/bibwiki/bibtex/367">BibTex</a>)
+ </li>
+ </ul>
+ </div>
+ </td>
+ <td width="50%" valign="top">
+ <h2>Miscellaneous</h2>
+ <div class="tile">
+ <p class="biglink"><a class="biglink" href="{{ pathto("RELEASE_NOTES") }}">Release Notes</a><br/>
+ <span class="linkdescr">new features, changes, bug fixes, deprecations, and removals</span></p>
- </td>
- <td width="50%" valign="top">
- <p class="biglink"><a class="biglink" href="doxygen/annotated.html">ndnSIM API documentation</a><br/>
- <span class="linkdescr">doxygen-generated API documentation</span></p>
- <p class="biglink"><a class="biglink" href="{{ pathto("faq") }}">FAQs</a><br/>
- <span class="linkdescr">frequently asked questions (with answers!)</span></p>
- <p class="biglink"><a class="biglink" href="{{ pathto("parallel-simulations") }}">How to use OpenMPI</a><br/>
- <span class="linkdescr">speeding up simulations by using OpenMPI for parallel execution of scenarios</span></p>
- <p class="biglink"><a class="biglink" href="{{ pathto("ndnsim-research-papers") }}">ndnSIM research papers</a><br/>
- <span class="linkdescr">list of ndnSIM-related papers</span></p>
- </td></tr>
+ <p class="biglink"><a class="biglink" href="http://redmine.named-data.net/projects/ndnsim">Reporting bugs</a><br/>
+ <span class="linkdescr"><a href="http://redmine.named-data.net/projects/ndnsim" target="_blank">ndnSIM Redmine</a>,
+ <span class="linkdescr"><a href="https://github.com/named-data-ndnSIM/ndnSIM/pulls" target="_blank">GitHub pull requests</a></span></p>
+
+ <p class="biglink"><a class="biglink" href="http://www.lists.cs.ucla.edu/mailman/listinfo/ndnsim" target="_blank">ndnSIM mailing list</a><br/>
+ <span class="linkdescr"><a href="http://www.lists.cs.ucla.edu/pipermail/ndnsim/" target="_blank">mailing list archives</a></span></p>
+
+ <p class="biglink"><a class="biglink" href="{{ pathto("meta/copying") }}">Copyright and License</a></p>
+ </div>
+ </td>
+ </tr>
</table>
- <p><strong>Meta information:</strong></p>
- <table class="contentstable" align="center"><tr>
- <td width="50%" valign="top">
- <p class="biglink"><a class="biglink" href="{{ pathto("RELEASE_NOTES") }}">Release Notes</a></p>
- <p class="biglink"><a class="biglink" href="{{ pathto("meta/bugs") }}">Reporting bugs</a></p>
- <p class="biglink"><a class="biglink" href="{{ pathto("meta/about") }}">About the documentation</a></p>
- </td><td width="50%" valign="top">
- <p class="biglink"><a class="biglink" href="{{ pathto("meta/license") }}">ndnSIM license</a></p>
- <p class="biglink"><a class="biglink" href="{{ pathto("meta/copyright") }}">Copyright</a></p>
- </td></tr>
- </table>
{% endblock %}
- <p>
-<hr class="docutils" />
-<dl class="docutils">
-<dt>If you refer to ndnSIM in a published work, please cite the following papers, not just the ndnSIM website. Thank you!</dt>
-<dd><strong>S. Mastorakis, A. Afanasyev, I. Moiseenko, and L. Zhang, “ndnSIM 2.0: A new version of the NDN simulator for NS-3,” NDN, Technical Report NDN-0028, 2015</strong> (<a class="reference external" href="http://named-data.net/techreport/ndn-0028-1-ndnsim-v2.pdf">PDF</a>) (<a class="reference external" href="http://lasr.cs.ucla.edu/afanasyev/bibwiki/bibtex/399">BibTex</a>)</dd>
-<dd><strong>A. Afanasyev, I. Moiseenko, and L. Zhang, “ndnSIM:
- NDN simulator for NS-3,” NDN, Technical Report NDN-0005, 2012</strong> (<a class="reference external" href="http://named-data.net/wp-content/uploads/TRndnsim.pdf">PDF</a>) (<a class="reference external" href="http://lasr.cs.ucla.edu/afanasyev/bibwiki/bibtex/367">BibTex</a>)</dd>
-</dl>
- </p>
{% endblock %}
diff --git a/docs/source/conf.py b/docs/source/conf.py
index 2d93856..c648be3 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -48,9 +48,9 @@
# built documents.
#
# The short X.Y version.
-version = '2.0'
+version = '2.1'
# The full version, including alpha/beta/rc tags.
-release = 'Overall ndnSIM 2.0'
+release = 'ndnSIM'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
@@ -185,7 +185,7 @@
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title, author, documentclass [howto/manual]).
latex_documents = [
- ('tutorial', 'ndnSIM-tutorial.tex', u'ndnSIM 2.0: NS-3 based Named Data Networking (NDN) simulator documentation',
+ ('tutorial', 'ndnSIM-tutorial.tex', u'ndnSIM: NS-3 based Named Data Networking (NDN) simulator documentation',
u'Alexander Afanasyev, Spyridon Mastorakis, Ilya Moiseenko, and Lixia Zhang', 'manual'),
]
@@ -215,7 +215,7 @@
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
- ('index', 'ndnSIM', u'ndnSIM 2.0: NS-3 based Named Data Networking (NDN) simulator documentation',
+ ('index', 'ndnSIM', u'ndnSIM: NS-3 based Named Data Networking (NDN) simulator documentation',
[u'Alexander Afanasyev, Spyridon Mastorakis, Ilya Moiseenko, and Lixia Zhang'], 1)
]
@@ -229,7 +229,7 @@
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
- ('index', 'ndnSIM', u'ndnSIM 2.0: NS-3 based Named Data Networking (NDN) simulator documentation',
+ ('index', 'ndnSIM', u'ndnSIM: NS-3 based Named Data Networking (NDN) simulator documentation',
u'Alexander Afanasyev, Spyridon Mastorakis, Ilya Moiseenko, and Lixia Zhang', 'ndnSIM', 'One line description of project.',
'Miscellaneous'),
]
diff --git a/docs/source/faq.rst b/docs/source/faq.rst
index 71cb2cb..d97a644 100644
--- a/docs/source/faq.rst
+++ b/docs/source/faq.rst
@@ -18,7 +18,7 @@
**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.53) ot ``/usr/local``, assuming you have a root access to your machine. If
+writing, version 1.59) 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`.
@@ -29,9 +29,9 @@
.. code-block:: bash
:linenos:
- wget http://downloads.sourceforge.net/project/boost/boost/1.57.0/boost_1_57_0.tar.bz2
- tar jxf boost_1_57_0.tar.bz2
- cd boost_1_57_0
+ wget http://downloads.sourceforge.net/project/boost/boost/1.59.0/boost_1_59_0.tar.bz2
+ tar jxf boost_1_59_0.tar.bz2
+ cd boost_1_59_0
./bootstrap.sh
sudo ./b2 --prefix=/usr/local install
@@ -63,15 +63,15 @@
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.57.0):
+issue following commands (e.g., for boost version 1.59.0):
.. code-block:: bash
:linenos:
export BOOSTDIR=/home/non-privileged-user/boost
- wget http://downloads.sourceforge.net/project/boost/boost/1.57.0/boost_1_57_0.tar.bz2
- tar jxf boost_1_57_0.tar.bz2
- cd boost_1_57_0
+ wget http://downloads.sourceforge.net/project/boost/boost/1.59.0/boost_1_59_0.tar.bz2
+ tar jxf boost_1_59_0.tar.bz2
+ cd boost_1_59_0
./bootstrap.sh
./b2 --prefix=$BOOSTDIR install
diff --git a/docs/source/getting-started.rst b/docs/source/getting-started.rst
index 3adbd21..03c6aea 100644
--- a/docs/source/getting-started.rst
+++ b/docs/source/getting-started.rst
@@ -4,10 +4,15 @@
Portability
------------
+.. image:: https://travis-ci.org/named-data-ndnSIM/ndnSIM.svg?branch=test-travis-ci
+ :target: https://travis-ci.org/named-data-ndnSIM/ndnSIM
+
ndnSIM 2.0 has been successfully compiled and used on following platforms:
- Ubuntu Linux 12.04 (see the note)
-- Ubuntu Linux 14.04
+- Ubuntu Linux 14.04 (32- and 64-bit platform)
+- Ubuntu Linux 15.05 (64-bit platform)
+- OS X 10.9
- OS X 10.10
.. note::
@@ -34,64 +39,115 @@
Prerequisites
-------------
-1. `ndn-cxx library prerequisites <http://named-data.net/doc/ndn-cxx/current/INSTALL.html>`__.
+**1. Core dependencies**
+
+- ``python`` >= 2.6
+- ``libsqlite3``
+- ``libcrypto++``
+- ``pkg-config``
+- Boost libraries >= 1.49
.. role:: red
.. note::
- :red:`ndnSIM requires boost version at least 1.49.` 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::
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.
+Following are the detailed steps for each platform to install the compiler, all necessary
+development tools and libraries, and ndn-cxx prerequisites.
-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:
+- OS X
- * For Ubuntu:
+ * OS X with MacPorts:
- .. code-block:: bash
+ .. code-block:: bash
- sudo apt-get install python-dev python-pygraphviz python-kiwi
- sudo apt-get install python-pygoocanvas python-gnome2
- sudo apt-get install python-rsvg ipython
+ sudo port install pkgconfig boost sqlite3 libcryptopp
- * For Fedora:
+ * OS X with HomeBrew:
- .. code-block:: bash
+ .. code-block:: bash
- sudo yum install pygoocanvas python-kiwi graphviz-python
+ brew install pkg-config boost cryptopp
- # easy_install method, since pygraphviz is not (yet?) packaged into Fedora (https://bugzilla.redhat.com/show_bug.cgi?id=740687)
- sudo yum install graphviz-devel
- sudo yum install python-pip
- sudo easy_install pygraphviz
+- Linux
- * For OS X with MacPorts:
+ * Ubuntu Linux
- .. code-block:: bash
+ .. code-block:: bash
- sudo port install py27-pygraphviz py27-goocanvas
+ sudo apt-get install build-essential libsqlite3-dev libcrypto++-dev
- # 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
+ # For Ubuntu 12.04
+ sudo apt-get install python-software-properties
+ sudo add-apt-repository ppa:boost-latest/ppa
+ sudo apt-get update
+ sudo apt-get install libboost1.55-all-dev
- * For OS X with HomeBrew
+ # For all other Ubuntu versions
+ sudo apt-get install libboost-all-dev
- .. code-block:: bash
+ * Fedora Linux
- brew install boost cryptopp pkg-config libxml2
- brew link --force libxml2
+ .. code-block:: bash
+
+ sudo yum install gcc-g++ git sqlite-devel cryptopp-devel boost-devel
+
+ .. note::
+ :red:`ndnSIM requires boost version at least 1.49.` 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>`.
+
+**2. Dependencies for NS-3 Python bindings**
+
+If you are planning to use NS-3 python bindings, a number of additional dependencies
+should be installed. For example, in order to run `visualizer`_ module, the following
+should be installed:
+
+- OS X
+
+ * OS X with MacPorts:
+
+ .. code-block:: bash
+
+ sudo port install py27-pygraphviz py27-goocanvas
+
+ # 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
+
+ * OS X with HomeBrew
+
+ .. code-block:: bash
+
+ brew install boost cryptopp pkg-config libxml2
+ brew link --force libxml2
+
+- Linux
+
+ * Ubuntu Linux
+
+ .. code-block:: bash
+
+ sudo apt-get install python-dev python-pygraphviz python-kiwi
+ sudo apt-get install python-pygoocanvas python-gnome2
+ sudo apt-get install python-rsvg ipython
+
+ * Fedora Linux
+
+ .. code-block:: bash
+
+ sudo yum install pygoocanvas python-kiwi graphviz-python
+
+ # easy_install method, since pygraphviz is not (yet?) packaged into Fedora (https://bugzilla.redhat.com/show_bug.cgi?id=740687)
+ sudo yum install graphviz-devel
+ sudo yum install python-pip
+ sudo easy_install pygraphviz
.. _visualizer: http://www.nsnam.org/wiki/index.php/PyViz
@@ -104,6 +160,8 @@
- 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
+- modified source code of ndn-cxx library and NDN Forwarding Daemon (NFD), attached to
+ ndnSIM git repository as git submodules
The following commands download all pieces from GitHub repositories:
@@ -115,156 +173,166 @@
git clone https://github.com/named-data-ndnSIM/pybindgen.git pybindgen
git clone --recursive https://github.com/named-data-ndnSIM/ndnSIM.git ns-3/src/ndnSIM
-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.
+The last command downloads ndnSIM source code and source code of all submodules (i.e.,
+ndn-cxx and NFD). If you previously cloned without ``--recursive`` flag, the correct
+versions of submodules can be retrieved using:
+
+.. code-block:: bash
+
+ git submodule update --init
+
+The same command should be run to update submodules when there are new changes available.
+
+.. note::
+ A few modification to the base NS-3 and pybindgen are necessary to run successfully
+ compile and run ndnSIM. Some of the changes are specific to ndnSIM and some are
+ bugfixes that we are submitting to NS-3 upstream. We also periodically update
+ repository with the new NS-3 releases, usually in form of rebasing (and if necessary
+ updating or eliminating) our custom patches on top of the released commits.
Compiling and running ndnSIM
----------------------------
-- Compile NS-3 with ndnSIM module
+ndnSIM uses a standard NS-3 compilation procedure. Normally the following commands should be
+sufficient to configure and build ndnSIM with python bindings enabled:
- ndnSIM uses standard NS-3 compilation procedure. Normally the following commands should be
- sufficient to configure and build ndnSIM with python bindings enabled:
+.. code-block:: bash
- .. code-block:: bash
+ cd <ns-3-folder>
+ ./waf configure --enable-examples
+ ./waf
- cd <ns-3-folder>
- ./waf configure --enable-examples
- ./waf
+On OS X (with MacPorts), you may need to modify the configure command to use MacPorts
+version of python:
- On MacOS (with macports), you may need to modify the configure command to use macports
- version of python:
+.. code-block:: bash
- .. code-block:: bash
+ cd <ns-3-folder>
+ ./waf configure --with-python=/opt/local/bin/python2.7 --enable-examples
+ # or run ``sudo port select python python27``
+ ./waf
- cd <ns-3-folder>
- ./waf configure --with-python=/opt/local/bin/python2.7 --enable-examples
- # or run ``sudo port select python python27``
- ./waf
+.. note::
+ On OS X configuration stage may get :ref:`stuck at detecting gtk module <Problems with
+ the gtk python module on OS X>`. Make sure you have `XQuartz
+ <http://xquartz.macosforge.org>`_ installed or disable python as described in the
+ following instructions.
- .. note::
- On OS X configuration stage may get :ref:`stuck at detecting gtk module <Problems with
- the gtk python module on OS X>`. Make sure you have `XQuartz
- <http://xquartz.macosforge.org>`_ installed or disable python as described in the
- following instructions.
+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'"):
- 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
+ cd <ns-3-folder>
+ ./waf configure --disable-python --enable-examples
+ ./waf
- cd <ns-3-folder>
- ./waf configure --disable-python --enable-examples
- ./waf
-
- For more configuration options, please refer to ``./waf --help``.
+For more configuration options, please refer to ``./waf --help``.
Simulating using ndnSIM
-----------------------
-- Examples simulations
+- Example simulation scenarios
- 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
-
- ./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.
+ When NS-3 is configured 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
+
+ ./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.
+ Simulation scenarios can be written directly inside NS-3 in ``scratch/`` or ``src/ndnSIM/examples`` folder.
+
+ Alternative and a recommended way is to write simulation scenarios in a separate
+ repository, not related to either NS-3 or ndnSIM. 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 https://github.com/named-data-ndnSIM/ns-3-dev.git ns-3
+ git clone https://github.com/named-data-ndnSIM/pybindgen.git pybindgen
+ git clone --recursive https://github.com/named-data-ndnSIM/ndnSIM.git ns-3/src/ndnSIM
+
+ # Build and install NS-3 and ndnSIM
+ cd ns-3
+ ./waf configure -d optimized
+ ./waf
+
+ sudo ./waf install
+ cd ..
+
+ git clone https://github.com/named-data-ndnSIM/scenario-template.git scenario
+ cd scenario
+ export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig
+ export LD_LIBRARY_PATH=/usr/local/lib:$LD_LIBRARY_PATH
+
+ ./waf configure
+
+ ./waf --run <scenario>
+
+ For more detailed information, refer to `README file
+ <https://github.com/cawka/ndnSIM-scenario-template/blob/master/README.md>`_.
- 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>`_:
+..
+ Examples of template-based simulations
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- .. code-block:: bash
+ 1. ndnSIM examples from `<http://ndnsim.net>`_ website and more:
- mkdir ndnSIM
- cd ndnSIM
- git clone https://github.com/named-data-ndnSIM/ns-3-dev.git ns-3
- git clone https://github.com/named-data-ndnSIM/pybindgen.git pybindgen
- git clone --recursive https://github.com/named-data-ndnSIM/ndnSIM.git ns-3/src/ndnSIM
+ - `<http://github.com/cawka/ndnSIM-examples>`_, or
- # Build and install NS-3 and ndnSIM
- cd ns-3
- ./waf configure -d optimized
- ./waf
+ 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>`_):
- sudo ./waf install
- cd ..
+ - `<http://github.com/cawka/ndnSIM-comcom-stateful-fw>`_, or
- git clone https://github.com/named-data-ndnSIM/scenario-template.git scenario
- cd scenario
- export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig
- export LD_LIBRARY_PATH=/usr/local/lib:$LD_LIBRARY_PATH
+ 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>`_):
- ./waf configure
+ - `<http://github.com/cawka/ndnSIM-nom-rapid-car2car>`_, or
- ./waf --run <scenario>
+ - Rocketfuel-based topology generator for ndnSIM preferred format (randomly assigned link
+ delays and bandwidth, based on estimated types of connections between nodes):
- For more detailed information, refer to `README file
- <https://github.com/cawka/ndnSIM-scenario-template/blob/master/README.md>`_.
-
-Examples of template-based simulations
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-1. ndnSIM examples from `<http://ndnsim.net>`_ website and more:
-
-- `<http://github.com/cawka/ndnSIM-examples>`_, or
-
-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
-
-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
-
-- 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://github.com/cawka/ndnSIM-sample-topologies>`_, or
diff --git a/docs/source/guide-to-simulate-real-apps.rst b/docs/source/guide-to-simulate-real-apps.rst
new file mode 100644
index 0000000..ab73f8d
--- /dev/null
+++ b/docs/source/guide-to-simulate-real-apps.rst
@@ -0,0 +1,4 @@
+Simulating real applications
+============================
+
+TODO
diff --git a/docs/source/intro.rst b/docs/source/intro.rst
index de72e7d..4c4c981 100644
--- a/docs/source/intro.rst
+++ b/docs/source/intro.rst
@@ -10,16 +10,33 @@
.. image:: _static/ndnSIM-structure.*
:width: 100%
-ndnSIM 2.0 is a new release of `NS-3 based Named Data Networking (NDN) simulator
-<http://ndnsim.net/1.0/>`_ that went through extensive refactoring and rewriting. The key
-new features of the new version:
+- Packet format changed to [NDN Packet Specification](http://named-data.net/doc/ndn-tlv/)
-- ndnSIM no longer re-implements basic NDN primitives and directly uses implementation
- from `ndn-cxx library (NDN C++ library with eXperimental eXtensions)
- <http://named-data.net/doc/ndn-cxx/>`_.
+- ndnSIM uses implementation of basic NDN primitives from
+ [ndn-cxx library (NDN C++ library with eXperimental eXtensions)](http://named-data.net/doc/ndn-cxx/)
+
+- All NDN forwarding and management is implemented directly using source code of
+ [Named Data Networking Forwarding Daemon (NFD)](http://named-data.net/doc/NFD/)
+
+- Allows [simulation of real applications](http://ndnsim.net/2.1/guide-to-simulate-real-apps.html)
+ written against ndn-cxx library
+
+
+A new release of `NS-3 based Named Data Networking (NDN) simulator <http://ndnsim.net/1.0/>`__
+went through a number of extensive refactoring and rewriting. The key new features of the
+new version:
+
+- Packet format changed to the `NDN packet format <http://named-data.net/doc/ndn-tlv/>`_
+
+- ndnSIM uses implementation of basic NDN primitives from
+ `ndn-cxx library (NDN C++ library with eXperimental eXtensions)
+ <http://named-data.net/doc/ndn-cxx/>`_
+
- All NDN forwarding and management is implemented directly using source code of `Named
Data Networking Forwarding Daemon (NFD) <http://named-data.net/doc/NFD/>`_
-- Packet format changed to the `NDN packet format <http://named-data.net/doc/ndn-tlv/>`_
+
+- It is possible to :doc:`simulation some real applications <guide-to-simulate-real-apps>`
+ written against ndn-cxx library
.. note::
Please note that ndnSIM 2.0 has major refactoring and simulation scenario written for
@@ -84,8 +101,11 @@
| | :ndnsim:`AppFace`), |
| | etc. |
+-----------------+---------------------------------------------------------------------+
-| ``NFD/`` | contains the `NFD`_ source code with few modifications to make it |
-| | compatible with the simulator |
+| ``NFD/`` | submodule of `NDN Forwarding Daemon (NFD)`_ source code with few |
+| | modifications to make it compatible with the simulator |
++-----------------+---------------------------------------------------------------------+
+| ``ndn-cxx/`` | submodule of `ndn-cxx library`_ source code with few |
+| | modifications to make it compatible with the simulator |
+-----------------+---------------------------------------------------------------------+
| ``apps/`` | applications (in NS-3 sense) that can be installed on the nodes. |
| | Right now we have one producer (:ndnsim:`Producer`) and a |
@@ -102,7 +122,9 @@
| ``examples/`` | contain :doc:`several example scenarios <examples>` |
+-----------------+---------------------------------------------------------------------+
-.. _NFD: http://named-data.net/doc/NFD/
+.. _NDN Forwarding Daemon (NFD): http://named-data.net/doc/NFD/
+
+.. _ndn-cxx library: http://named-data.net/doc/ndn-cxx/
Logging
-------
diff --git a/docs/source/meta/about.rst b/docs/source/meta/about.rst
deleted file mode 100644
index 93518a1..0000000
--- a/docs/source/meta/about.rst
+++ /dev/null
@@ -1,17 +0,0 @@
-=====================
-About these documents
-=====================
-
-These documents are generated from `reStructuredText`_ sources by `Sphinx`_, a
-document processor specifically written for the Python documentation.
-
-.. _reStructuredText: http://docutils.sf.net/rst.html
-.. _Sphinx: http://sphinx.pocoo.org/
-
-.. In the online version of these documents, you can submit comments and suggest
- changes directly on the documentation pages.
-
-We are always welcome for your comments about the documentation, catched typos, and
-other contributions.
-
-See :ref:`reporting-bugs` for information how to report bugs in this documentation, or ndnSIM itself.
diff --git a/docs/source/meta/bugs.rst b/docs/source/meta/bugs.rst
deleted file mode 100644
index 85912b5..0000000
--- a/docs/source/meta/bugs.rst
+++ /dev/null
@@ -1,9 +0,0 @@
-.. _reporting-bugs:
-
-==============
-Reporting bugs
-==============
-
-To file a bug report, please use `NDN Redmine <http://redmine.named-data.net/projects/ndnsim>`_.
-
-To create new feature, please fork the code and submit Pull Request on GitHub.
diff --git a/docs/source/meta/license.rst b/docs/source/meta/copying.rst
similarity index 95%
rename from docs/source/meta/license.rst
rename to docs/source/meta/copying.rst
index ae1718a..1609bcb 100644
--- a/docs/source/meta/license.rst
+++ b/docs/source/meta/copying.rst
@@ -1,10 +1,40 @@
-.. _license:
+=====================
+Copyright and License
+=====================
-===================
-License information
-===================
+Copyright © 2011-2015 University of California, Los Angeles
-Most parts of ndnSIM code are licensed under GNU GPL License 3.0.
+ndnSIM is licensed under conditions of GNU General Public License version 3.0 or later
+with permission to be linked with NS-3 codebase (GPL 2.0).
+
+ndnSIM uses a number of third-party software and libraries, licensed under the following
+licenses:
+
+- Boost libraries licensed under conditions of `Boost Software License 1.0`_
+
+- CryptoPP library is licensed under conditions of `Boost Software License 1.0`_
+
+- SQLite is in `public domain <http://www.sqlite.org/copyright.html>`__
+
+- waf build system is licensed under conditions of `BSD license
+ <https://github.com/named-data/ndn-cxx/blob/master/waf>`__
+
+- ndn-cxx library licensed under conditions of `GNU LGPL 3.0+
+ <https://github.com/named-data/ndn-cxx/blob/master/COPYING.md>`__
+
+- NDN Forwarding Daemon (NFD) licensed under conditions of `GNU GPL 3.0+
+ <https://github.com/named-data/NFD/blob/master/COPYING.md>`__
+
+ndnSIM also relies on several other third-party libraries with non-GPL compatible
+license. These library fall into category of "System Libraries" under GPL license
+definitions and are used in accordance with GPL license exception for "System Libraries":
+
+The GPL license is provided below in this file. For more information about these licenses,
+see `<http://www.gnu.org/licenses/>`__
+
+.. _Boost Software License 1.0 : http://www.boost.org/users/license.html
+
+----------------------------------------------------------------------------------
GNU GENERAL PUBLIC LICENSE
==========================
diff --git a/docs/source/meta/copyright.rst b/docs/source/meta/copyright.rst
deleted file mode 100644
index 6a19d5c..0000000
--- a/docs/source/meta/copyright.rst
+++ /dev/null
@@ -1,15 +0,0 @@
-=========
-Copyright
-=========
-
-ndnSIM and this documentation is:
-
-Copyright © 2011-2015 University of California, Los Angeles
-
-Copyright © 2011-2015 Alexander Afanasyev
-
-Copyright © 2014-2015 Spyridon Mastorakis
-
--------
-
-See :ref:`license` for complete license and permissions information.
diff --git a/docs/source/tutorial.rst b/docs/source/tutorial.rst
index 37d7fe4..d74bdf0 100644
--- a/docs/source/tutorial.rst
+++ b/docs/source/tutorial.rst
@@ -20,20 +20,18 @@
intro
getting-started
+ faq
+ examples
helpers
cs
fw
applications
-
-.. toctree::
- :maxdepth: 2
-
- examples
metric
- faq
parallel-simulations
+ guide-to-simulate-real-apps
ndnsim-research-papers
+
.. toctree::
:hidden:
:glob: