blob: aa25b5eb02c76d60080d34b4ed2f3744bed31f1d [file] [log] [blame]
Getting Started
===============
Portability
------------
.. image:: https://travis-ci.org/named-data-ndnSIM/ndnSIM.svg?branch=master
:target: https://travis-ci.org/named-data-ndnSIM/ndnSIM
ndnSIM 2.x has been successfully compiled and used on following platforms:
- Ubuntu Linux 18.04
- Ubuntu Linux 16.04
- macOS 10.13
- macOS 10.14
.. _requirements:
Prerequisites
-------------
**1. Core dependencies**
- ``python`` >= 2.7
- ``libsqlite3``
- ``pkg-config``
- ``openssl``
- Boost libraries >= 1.54
.. 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 :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.
- macOS
* macOS with HomeBrew:
.. code-block:: bash
brew install boost pkg-config openssl libxml2
export PKG_CONFIG_PATH="/usr/local/opt/libxml2/lib/pkgconfig" # put this line in ~/.bashrc or manually type before ./waf configure
- Linux
* Ubuntu Linux
.. code-block:: bash
sudo apt install build-essential libsqlite3-dev libboost-all-dev libssl-dev git python-setuptools castxml
* Fedora Linux
.. code-block:: bash
sudo yum install gcc-g++ git sqlite-devel boost-devel openssl-devel
.. note::
:red:`ndnSIM requires boost version at least 1.54.` 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:
- macOS
* macOS with HomeBrew
.. code-block:: bash
brew install cairo goocanvas gtk+3 graphviz gobject-introspection castxml
export PKG_CONFIG_PATH="$PKG_CONFIG_PATH:/usr/local/opt/libffi/lib/pkgconfig" # this needed only for running the next line
pip install pygraphviz pycairo PyGObject pygccxml
- Linux
* Ubuntu Linux
.. code-block:: bash
sudo apt install python-dev python-pygraphviz python-kiwi python-gnome2 ipython libcairo2-dev python3-gi libgirepository1.0-dev python-gi python-gi-cairo gir1.2-gtk-3.0 gir1.2-goocanvas-2.0 python-pip
sudo pip install pygraphviz pycairo PyGObject pygccxml
.. _visualizer: https://www.nsnam.org/wiki/PyViz
Downloading ndnSIM source
-------------------------
ndnSIM package consists of three pieces:
- 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
- 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:
.. 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
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
----------------------------
ndnSIM uses a standard NS-3 compilation procedure. Normally the following commands should be
sufficient to configure and build ndnSIM with python bindings enabled:
.. code-block:: bash
cd <ns-3-folder>
./waf configure --enable-examples
./waf
On macOS (with MacPorts), you may need to modify the configure command to use MacPorts
version of python:
.. 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
.. note::
On macOS configuration stage may get :ref:`stuck at detecting gtk module <Problems with
the gtk python module on macOS>`. 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'"):
.. code-block:: bash
cd <ns-3-folder>
./waf configure --disable-python --enable-examples
./waf
For more configuration options, please refer to ``./waf --help``.
Simulating using ndnSIM
-----------------------
- Example simulation scenarios
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
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>`_.
..
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