blob: ef30fb67f4881838a02b5a00911cf3c4169b0c90 [file] [log] [blame]
Alexander Afanasyeve095f0f2012-11-21 17:43:32 -08001Getting Started
2===============
3
4Portability
5------------
6
7ndnSIM has been successfully compiled and used under Ubuntu Linux 12.04 (stock gcc, boost 1.48), Mac OS 10.8 (gcc-4.2 apple/llvm, macports gcc 4.7, boost 1.49-1.52).
8
9.. _requirements:
10
11Requirements
12-------------
13
141. 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).
15
162. Boost libraries should be installed on the system:
17
Alexander Afanasyev326410e2013-03-09 20:39:11 -080018 * For Ubuntu (for Ubuntu 12.10 and later only):
Alexander Afanasyeve095f0f2012-11-21 17:43:32 -080019
Alexander Afanasyev326410e2013-03-09 20:39:11 -080020 .. code-block:: bash
Alexander Afanasyeve095f0f2012-11-21 17:43:32 -080021
Alexander Afanasyev326410e2013-03-09 20:39:11 -080022 sudo aptitude install libboost-all-dev
Alexander Afanasyeve095f0f2012-11-21 17:43:32 -080023
Alexander Afanasyev326410e2013-03-09 20:39:11 -080024 * For Fedora (for Fedora 18 and later only):
25
26 .. code-block:: bash
27
28 sudo yum install boost-devel
29
30 * For MacOS (macports):
31
32 .. code-block:: bash
33
34 sudo port instal boost
Alexander Afanasyeve095f0f2012-11-21 17:43:32 -080035
Alexander Afanasyev26b558b2012-12-13 11:39:46 -080036.. role:: red
37
Alexander Afanasyeve095f0f2012-11-21 17:43:32 -080038.. note::
Alexander Afanasyev326410e2013-03-09 20:39:11 -080039 :red:`!!! ndnSIM requires boost version at least 1.48.` Many linux distribution (including Ubuntu 12.04.1 and Fedore 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>`.
Alexander Afanasyev26b558b2012-12-13 11:39:46 -080040
41.. note::
Alexander Afanasyev326410e2013-03-09 20:39:11 -080042 !!! 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.
Alexander Afanasyeve095f0f2012-11-21 17:43:32 -080043
44
453. If you are planning to use other modules, like visualizer, a number of additional dependencies should be installed. For example, in
46order to run `visualizer`_ module, the following should be installed:
47
Alexander Afanasyev326410e2013-03-09 20:39:11 -080048 * For Ubuntu (tested on Ubuntu 12.04.1):
Alexander Afanasyeve095f0f2012-11-21 17:43:32 -080049
Alexander Afanasyev326410e2013-03-09 20:39:11 -080050 .. code-block:: bash
Alexander Afanasyeve095f0f2012-11-21 17:43:32 -080051
Alexander Afanasyev326410e2013-03-09 20:39:11 -080052 sudo apt-get install python-dev python-pygraphviz python-kiwi
53 sudo apt-get install python-pygoocanvas python-gnome2
54 sudo apt-get install python-gnomedesktop python-rsvg ipython
Alexander Afanasyeve095f0f2012-11-21 17:43:32 -080055
Alexander Afanasyev326410e2013-03-09 20:39:11 -080056 * For Fedora (tested on Fedora 16):
Alexander Afanasyeve095f0f2012-11-21 17:43:32 -080057
Alexander Afanasyev326410e2013-03-09 20:39:11 -080058 .. code-block:: bash
59
60 sudo yum install pygoocanvas python-kiwi graphviz-python
61
62 # easy_install method, since pygraphviz is not yet packaged into Fedora (https://bugzilla.redhat.com/show_bug.cgi?id=740687)
63 sudo yum install graphviz-devel
64 sudo yum install python-pip
65 sudo easy_install pygraphviz
66
67 * For MacOS (macports):
68
69 .. code-block:: bash
70
71 sudo port install py27-pygraphviz py27-goocanvas
72
73.. py27-kiwi
Alexander Afanasyeve095f0f2012-11-21 17:43:32 -080074
75.. _visualizer: http://www.nsnam.org/wiki/index.php/PyViz
76
77Downloading ndnSIM source
78-------------------------
79
Alexander Afanasyev701e5082013-03-13 09:47:50 -070080Download 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:
Alexander Afanasyev326410e2013-03-09 20:39:11 -080081
82.. code-block:: bash
Alexander Afanasyeve095f0f2012-11-21 17:43:32 -080083
84 mkdir ndnSIM
85 cd ndnSIM
86 git clone git://github.com/cawka/ns-3-dev-ndnSIM.git ns-3
87 git clone git://github.com/cawka/pybindgen.git pybindgen
Alexander Afanasyeve095f0f2012-11-21 17:43:32 -080088 git clone git://github.com/NDN-Routing/ndnSIM.git ns-3/src/ndnSIM
89
90There 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.
91
Alexander Afanasyev701e5082013-03-13 09:47:50 -070092If you have problems connecting to github, you can try to clone from google servers:
93
94.. code-block:: bash
95
96 mkdir ndnSIM
97 cd ndnSIM
98 git clone https://code.google.com/p/ndnsim.ns3-base/ ns-3
99 git clone https://code.google.com/p/ndnsim.pybindgen/ pybindgen
100 git clone https://code.google.com/p/ndnsim/ ns-3/src/ndnSIM
101
Alexander Afanasyeve095f0f2012-11-21 17:43:32 -0800102Compiling and running ndnSIM
103----------------------------
104
Alexander Afanasyev326410e2013-03-09 20:39:11 -0800105ndnSIM uses standard NS-3 compilation procedure. Normally the following commands should be sufficient to configure and build ndnSIM with python bindings enabled:
106
107.. code-block:: bash
Alexander Afanasyeve095f0f2012-11-21 17:43:32 -0800108
109 cd <ns-3-folder>
Alexander Afanasyev26b558b2012-12-13 11:39:46 -0800110 ./waf configure --enable-examples
Alexander Afanasyeve095f0f2012-11-21 17:43:32 -0800111 ./waf
112
Alexander Afanasyev326410e2013-03-09 20:39:11 -0800113On MacOS (with macports), you may need to modify the configure command to use macports version of python:
114
115.. code-block:: bash
Alexander Afanasyeve095f0f2012-11-21 17:43:32 -0800116
117 cd <ns-3-folder>
Alexander Afanasyev26b558b2012-12-13 11:39:46 -0800118 ./waf configure --with-python=/opt/local/bin/python2.7 --enable-examples
Alexander Afanasyeve095f0f2012-11-21 17:43:32 -0800119 ./waf
120
Alexander Afanasyev326410e2013-03-09 20:39:11 -0800121Python 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'"):
122
123.. code-block:: bash
Alexander Afanasyeve095f0f2012-11-21 17:43:32 -0800124
125 cd <ns-3-folder>
Alexander Afanasyev26b558b2012-12-13 11:39:46 -0800126 ./waf configure --disable-python --enable-examples
Alexander Afanasyeve095f0f2012-11-21 17:43:32 -0800127 ./waf
128
129For more configuration options, please refer to ``./waf --help``.
130
Alexander Afanasyev326410e2013-03-09 20:39:11 -0800131To run :doc:`sample ndnSIM simulations <examples>`:
132
133.. code-block:: bash
Alexander Afanasyeve095f0f2012-11-21 17:43:32 -0800134
135 ./waf --run=ndn-simple
136
Alexander Afanasyev326410e2013-03-09 20:39:11 -0800137or:
138
139.. code-block:: bash
Alexander Afanasyeve095f0f2012-11-21 17:43:32 -0800140
141 ./waf --run=ndn-grid
142
Alexander Afanasyev326410e2013-03-09 20:39:11 -0800143If you have compiled with python bindings, then you can try to run these simulations with visualizer:
144
145.. code-block:: bash
Alexander Afanasyeve095f0f2012-11-21 17:43:32 -0800146
147 ./waf --run=ndn-simple --vis
148
Alexander Afanasyev326410e2013-03-09 20:39:11 -0800149or:
150
151.. code-block:: bash
Alexander Afanasyeve095f0f2012-11-21 17:43:32 -0800152
153 ./waf --run=ndn-grid --vis
154
155.. note::
156 Do not forget to configure and compile NS-3 in optimized mode (``./waf configure -d optimized``) in order to run actual simulations.
157
Alexander Afanasyeve095f0f2012-11-21 17:43:32 -0800158
Alexander Afanasyev701e5082013-03-13 09:47:50 -0700159Simulating using ndnSIM
160-----------------------
161
162While 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.
163
164For example, you can you can use the following template to write your extensions, simulation scenarios, and metric processing scripts: `<http://github.com/cawka/ndnSIM-scenario-template>`_:
165
166.. code-block:: bash
167
168 mkdir ndnSIM
169 cd ndnSIM
170 git clone git://github.com/cawka/ns-3-dev-ndnSIM.git ns-3
171 git clone git://github.com/cawka/pybindgen.git pybindgen
172 git clone git://github.com/NDN-Routing/ndnSIM.git ns-3/src/ndnSIM
173
174 # Build and install NS-3 and ndnSIM
175 cd ns-3
176 ./waf configure -d optimized
177 ./waf
178
179 sudo ./waf install
180 cd ..
181
182 git clone git://github.com/cawka/ndnSIM-scenario-template.git scenario
183 cd scenario
184 export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig
185 export LD_LIBRARY_PATH=/usr/local/lib:$LD_LIBRARY_PATH
186
187 ./waf configure
188
189 ./waf --run <scenario>
190
191For more detailed information, refer to `README file <https://github.com/cawka/ndnSIM-scenario-template/blob/master/README.md>`_.
192
193Examples of template-based simulations
194~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
195
1961. ndnSIM examples from `<http://ndnsim.net>`_ website and more:
197
198- `<http://github.com/cawka/ndnSIM-examples>`_, or
199- `<http://code.google.com/p/ndnsim.ndnsim-examples/>`_
200
2012. 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>`_):
202
203- `<http://github.com/cawka/ndnSIM-comcom-stateful-fw>`_, or
204- `<http://code.google.com/p/ndnsim.ndnsim-comcom/>`_
205
2063. 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>`_):
207
208- `<http://github.com/cawka/ndnSIM-nom-rapid-car2car>`_, or
209- `<http://code.google.com/p/ndnsim.ndnsim-nom-rapid/>`_
210
211- Rocketfuel-based topology generator for ndnSIM preferred format (randomly assigned link delays and bandwidth, based on estimated types of connections between nodes):
212
213- `<http://github.com/cawka/ndnSIM-sample-topologies>`_, or
214- `<http://code.google.com/p/ndnsim.ndnsim-sample-topo/>`_