blob: 369be3f27ffe8debf865f308bfb00a60606a0c82 [file] [log] [blame]
Alexander Afanasyeve095f0f2012-11-21 17:43:32 -08001Getting Started
2===============
3
4Portability
5------------
6
Alexander Afanasyev8e60bcd2015-01-15 20:55:40 +00007ndnSIM 2.0 has been successfully compiled and used on following platforms:
8
9- Ubuntu Linux 12.04 (see the note)
10- Ubuntu Linux 14.04
11- OS X 10.10
12
13.. note::
14 ndnSIM is currently cannot be compiled on Ubuntu Linux 12.04 with the packaged boost
15 libraries (there is an `issue with boost 1.48 and gcc 4.6
16 <https://svn.boost.org/trac/boost/ticket/6153>`_). It is still possible to compile ndnSIM
17 on this platform, but either compiler or boost libraries (or both) need to get upgraded.
18
19 More recent version of boost can be installed from "Boost C++ Libraries" team PPA::
20
21 sudo apt-get install python-software-properties
22 sudo add-apt-repository ppa:boost-latest/ppa
23 sudo apt-get update
24 sudo apt-get install libboost1.55-all-dev
25
26 # add --boost-libs=/usr/lib/x86_64-linux-gnu to ./waf configure for ndn-cxx and ns3
27 # ./waf configure --boost-libs=/usr/lib/x86_64-linux-gnu
28
29 Make sure that all other version of boost libraries (``-dev`` packages) are removed,
30 otherwise compilation will fail.
Alexander Afanasyeve095f0f2012-11-21 17:43:32 -080031
32.. _requirements:
33
Spyridon Mastorakis460f57c2014-12-17 00:44:14 -080034Prerequisites
Alexander Afanasyeve095f0f2012-11-21 17:43:32 -080035-------------
36
Spyridon Mastorakis460f57c2014-12-17 00:44:14 -0800371. `ndnSIM also required ndn-cxx library and all of its prerequisites
38 <http://named-data.net/doc/ndn-cxx/current/INSTALL.html>`_.
Alexander Afanasyeve095f0f2012-11-21 17:43:32 -080039
Alexander Afanasyev26b558b2012-12-13 11:39:46 -080040.. role:: red
41
Alexander Afanasyeve095f0f2012-11-21 17:43:32 -080042.. note::
Spyridon Mastorakisc33e2882015-01-20 21:45:44 -080043 :red:`ndnSIM requires boost version at least 1.49.` Many linux distribution
Spyridon Mastorakis460f57c2014-12-17 00:44:14 -080044 (Fedora 16, 17 at the time of this writing) ship an old version of boost, making it
45 impossible to compile ndnSIM out-of-the-box. Please install the latest version, following
46 :ref:`these simple instructions <Installing boost libraries>`.
Alexander Afanasyev9ab7d672013-08-11 11:02:52 -070047
48.. note::
Spyridon Mastorakisc33e2882015-01-20 21:45:44 -080049 If you do not have root permissions to install boost, you can install it in your home
Spyridon Mastorakis460f57c2014-12-17 00:44:14 -080050 folder. However, you need to be make sure that `libboost_iostreams` library is successfully
51 compiled and is installed. Please refer to :ref:`the following example <Installing boost
52 libraries>` for the hints how to successfully compile and install boost libraries on Ubuntu
53 Linux.
Alexander Afanasyeve095f0f2012-11-21 17:43:32 -080054
55
Spyridon Mastorakis460f57c2014-12-17 00:44:14 -0800562. If you are planning to use other modules, like visualizer, a number of additional
57dependencies should be installed. For example, in order to run `visualizer`_ module, the
58following should be installed:
Alexander Afanasyeve095f0f2012-11-21 17:43:32 -080059
Alexander Afanasyev8e60bcd2015-01-15 20:55:40 +000060 * For Ubuntu:
Alexander Afanasyeve095f0f2012-11-21 17:43:32 -080061
Alexander Afanasyev326410e2013-03-09 20:39:11 -080062 .. code-block:: bash
Alexander Afanasyeve095f0f2012-11-21 17:43:32 -080063
Alexander Afanasyev326410e2013-03-09 20:39:11 -080064 sudo apt-get install python-dev python-pygraphviz python-kiwi
65 sudo apt-get install python-pygoocanvas python-gnome2
Alexander Afanasyevdf26b5a2015-01-15 23:30:56 -080066 sudo apt-get install python-rsvg ipython
Alexander Afanasyeve095f0f2012-11-21 17:43:32 -080067
Alexander Afanasyev8e60bcd2015-01-15 20:55:40 +000068 * For Fedora:
Alexander Afanasyeve095f0f2012-11-21 17:43:32 -080069
Alexander Afanasyev326410e2013-03-09 20:39:11 -080070 .. code-block:: bash
71
72 sudo yum install pygoocanvas python-kiwi graphviz-python
73
Alexander Afanasyev9ab7d672013-08-11 11:02:52 -070074 # easy_install method, since pygraphviz is not (yet?) packaged into Fedora (https://bugzilla.redhat.com/show_bug.cgi?id=740687)
Alexander Afanasyev326410e2013-03-09 20:39:11 -080075 sudo yum install graphviz-devel
76 sudo yum install python-pip
77 sudo easy_install pygraphviz
78
Alexander Afanasyev8e60bcd2015-01-15 20:55:40 +000079 * For OS X with MacPorts:
Alexander Afanasyev326410e2013-03-09 20:39:11 -080080
81 .. code-block:: bash
82
83 sudo port install py27-pygraphviz py27-goocanvas
84
Spyridon Mastorakis460f57c2014-12-17 00:44:14 -080085 # If you add NDN macports repository, as described in
86 # http://named-data.net/doc/NFD/current/INSTALL.html#install-nfd-using-the-ndn-macports-repository-on-os-x
87 # you will be able to install another useful python module
88 # sudo port install py27-kiwi
Alexander Afanasyeve095f0f2012-11-21 17:43:32 -080089
Alexander Afanasyevdf26b5a2015-01-15 23:30:56 -080090 * For OS X with HomeBrew
91
92 .. code-block:: bash
93
94 brew install boost cryptopp pkg-config libxml2
95 brew link --force libxml2
96
Alexander Afanasyeve095f0f2012-11-21 17:43:32 -080097.. _visualizer: http://www.nsnam.org/wiki/index.php/PyViz
98
99Downloading ndnSIM source
100-------------------------
101
Spyridon Mastorakis460f57c2014-12-17 00:44:14 -0800102ndnSIM package consists of three pieces:
103
104- `ndn-cxx library <http://named-data.net/doc/ndn-cxx/>`_
105- a custom branch of NS-3 that contains a few useful patches
106- a customized python binding generation library (necessary if you want to use NS-3's python
107 bindings and/or visualizer module)
108- the source code of ndnSIM module
109
110The following commands download all pieces from GitHub repositories:
Alexander Afanasyev326410e2013-03-09 20:39:11 -0800111
112.. code-block:: bash
Alexander Afanasyeve095f0f2012-11-21 17:43:32 -0800113
Spyridon Mastorakis460f57c2014-12-17 00:44:14 -0800114 mkdir ndnSIM
115 cd ndnSIM
116 git clone https://github.com/named-data/ndn-cxx.git ndn-cxx
117 git clone https://github.com/cawka/ns-3-dev-ndnSIM.git ns-3
118 git clone https://github.com/cawka/pybindgen.git pybindgen
119 git clone https://github.com/named-data/ndnSIM.git ns-3/src/ndnSIM
Alexander Afanasyeve095f0f2012-11-21 17:43:32 -0800120
Spyridon Mastorakis460f57c2014-12-17 00:44:14 -0800121The few modification to the base NS-3 code are necessary to run ndnSIM, and the code is
122periodically synchronized with the official developer branch. Eventually, all the changes will
123be merged to the official branch, but for the time being, it is necessary to use the customized
124branch.
Alexander Afanasyeve095f0f2012-11-21 17:43:32 -0800125
Alexander Afanasyev701e5082013-03-13 09:47:50 -0700126
Alexander Afanasyeve095f0f2012-11-21 17:43:32 -0800127Compiling and running ndnSIM
128----------------------------
129
Spyridon Mastorakis460f57c2014-12-17 00:44:14 -0800130- Compile and install ndn-cxx library
Alexander Afanasyev326410e2013-03-09 20:39:11 -0800131
Spyridon Mastorakis460f57c2014-12-17 00:44:14 -0800132 .. code-block:: bash
Alexander Afanasyeve095f0f2012-11-21 17:43:32 -0800133
Spyridon Mastorakis460f57c2014-12-17 00:44:14 -0800134 cd ndnSIM/ndn-cxx
135 ./waf configure
136 ./waf
137 sudo ./waf install
Alexander Afanasyeve095f0f2012-11-21 17:43:32 -0800138
Spyridon Mastorakis460f57c2014-12-17 00:44:14 -0800139 .. note::
140 On Ubuntu platform you can also install ndn-cxx library from `NDN
141 PPA repository <http://named-data.net/doc/NFD/current/INSTALL.html#installing-nfd-from-binaries>`_
Alexander Afanasyev326410e2013-03-09 20:39:11 -0800142
Spyridon Mastorakis460f57c2014-12-17 00:44:14 -0800143 .. code-block:: bash
Alexander Afanasyeve095f0f2012-11-21 17:43:32 -0800144
Alexander Afanasyev11381c22015-01-19 16:07:46 -0800145 sudo apt-get install ndn-cxx-dev
146
147 If you are using ndn-cxx from PPA, please make sure that you do not have the existing installation
148 of ndn-cxx library compiled from source (e.g., in /usr/local). Otherwise, the version mistmach
149 may result in compilation errors.
Alexander Afanasyeve095f0f2012-11-21 17:43:32 -0800150
Spyridon Mastorakis460f57c2014-12-17 00:44:14 -0800151- Compile NS-3 with ndnSIM module
Alexander Afanasyev326410e2013-03-09 20:39:11 -0800152
Spyridon Mastorakis460f57c2014-12-17 00:44:14 -0800153 ndnSIM uses standard NS-3 compilation procedure. Normally the following commands should be
154 sufficient to configure and build ndnSIM with python bindings enabled:
Alexander Afanasyeve095f0f2012-11-21 17:43:32 -0800155
Spyridon Mastorakis460f57c2014-12-17 00:44:14 -0800156 .. code-block:: bash
Alexander Afanasyeve095f0f2012-11-21 17:43:32 -0800157
Spyridon Mastorakis460f57c2014-12-17 00:44:14 -0800158 cd <ns-3-folder>
159 ./waf configure --enable-examples
160 ./waf
Alexander Afanasyeve095f0f2012-11-21 17:43:32 -0800161
Spyridon Mastorakis460f57c2014-12-17 00:44:14 -0800162 On MacOS (with macports), you may need to modify the configure command to use macports
163 version of python:
Alexander Afanasyev326410e2013-03-09 20:39:11 -0800164
Spyridon Mastorakis460f57c2014-12-17 00:44:14 -0800165 .. code-block:: bash
Alexander Afanasyeve095f0f2012-11-21 17:43:32 -0800166
Spyridon Mastorakis460f57c2014-12-17 00:44:14 -0800167 cd <ns-3-folder>
168 ./waf configure --with-python=/opt/local/bin/python2.7 --enable-examples
169 # or run ``sudo port select python python27``
170 ./waf
Alexander Afanasyeve095f0f2012-11-21 17:43:32 -0800171
Spyridon Mastorakisc33e2882015-01-20 21:45:44 -0800172 .. note::
173 On OS X configuration stage may get :ref:`stuck at detecting gtk module <Problems with
174 the gtk python module on OS X>`. Make sure you have `XQuartz
175 <http://xquartz.macosforge.org>`_ installed or disable python as described in the
176 following instructions.
177
Spyridon Mastorakis460f57c2014-12-17 00:44:14 -0800178 Python bindings is an optional and not very stable feature of NS-3 simulator. It is
179 possible to disable python bindings compilation either to speed up compilation or to avoid
180 certain compilation errors (e.g., "Could not find a task generator for the name
181 'ns3-visualizer'"):
Alexander Afanasyev326410e2013-03-09 20:39:11 -0800182
Spyridon Mastorakis460f57c2014-12-17 00:44:14 -0800183 .. code-block:: bash
Alexander Afanasyeve095f0f2012-11-21 17:43:32 -0800184
Spyridon Mastorakis460f57c2014-12-17 00:44:14 -0800185 cd <ns-3-folder>
186 ./waf configure --disable-python --enable-examples
187 ./waf
Alexander Afanasyeve095f0f2012-11-21 17:43:32 -0800188
Spyridon Mastorakis460f57c2014-12-17 00:44:14 -0800189 For more configuration options, please refer to ``./waf --help``.
Alexander Afanasyeve095f0f2012-11-21 17:43:32 -0800190
Spyridon Mastorakisf34b3192015-02-16 17:42:01 -0800191
Alexander Afanasyev701e5082013-03-13 09:47:50 -0700192Simulating using ndnSIM
193-----------------------
194
Spyridon Mastorakis460f57c2014-12-17 00:44:14 -0800195- Examples simulations
Alexander Afanasyev701e5082013-03-13 09:47:50 -0700196
Spyridon Mastorakis460f57c2014-12-17 00:44:14 -0800197 When NS-3 is compiled with ``--with-examples`` flag, you can directly run all examples
198 described in :doc:`examples section of this tutorial <examples>`. For example, to run
199 ``ndn-simple.cpp`` scenario, you can run the following command:
Alexander Afanasyev701e5082013-03-13 09:47:50 -0700200
Spyridon Mastorakis460f57c2014-12-17 00:44:14 -0800201 .. code-block:: bash
Alexander Afanasyev701e5082013-03-13 09:47:50 -0700202
Spyridon Mastorakis460f57c2014-12-17 00:44:14 -0800203 ./waf --run=ndn-simple
204
Spyridon Mastorakisc33e2882015-01-20 21:45:44 -0800205 To run ``ndn-grid.cpp`` scenario:
Spyridon Mastorakis460f57c2014-12-17 00:44:14 -0800206
207 .. code-block:: bash
208
209 ./waf --run=ndn-grid
210
211 To run the sample simulation scenarios with the logging module of NS-3 enabled (note that
212 this will work only when NS-3 is compiled in debug mode):
213
214 .. code-block:: bash
215
216 NS_LOG=ndn.Producer:ndn.Consumer ./waf --run=<scenario name>
217
218 If you have compiled with python bindings, then you can try to run these simulations with
219 visualizer:
220
221 .. code-block:: bash
222
223 ./waf --run=ndn-simple --vis
224
225 or:
226
227 .. code-block:: bash
228
229 ./waf --run=ndn-grid --vis
230
231 .. note::
232 Do not forget to configure and compile NS-3 in optimized mode (``./waf configure -d
233 optimized``) in order to run actual simulations.
234
235- Real experimentation
236
237 While it is possible to write simulations directly inside NS-3 (in ``scratch/`` folder) or
238 ndnSIM (in ``examples/``), the recommended way is to write your simulation scenarios, as
239 well as any custom extensions, separately from the NS-3 or ndnSIM core.
240
241 For example, you can use the following template to write your extensions, simulation
242 scenarios, and metric processing scripts:
243 `<http://github.com/cawka/ndnSIM-scenario-template>`_:
244
245 .. code-block:: bash
246
247 mkdir ndnSIM
248 cd ndnSIM
249 git clone git://github.com/cawka/ns-3-dev-ndnSIM.git ns-3
250 git clone git://github.com/cawka/pybindgen.git pybindgen
251 git clone git://github.com/NDN-Routing/ndnSIM.git ns-3/src/ndnSIM
Alexander Afanasyev701e5082013-03-13 09:47:50 -0700252
253 # Build and install NS-3 and ndnSIM
254 cd ns-3
255 ./waf configure -d optimized
256 ./waf
257
258 sudo ./waf install
259 cd ..
260
261 git clone git://github.com/cawka/ndnSIM-scenario-template.git scenario
262 cd scenario
Alexander Afanasyev9ab7d672013-08-11 11:02:52 -0700263 export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig
Alexander Afanasyev701e5082013-03-13 09:47:50 -0700264 export LD_LIBRARY_PATH=/usr/local/lib:$LD_LIBRARY_PATH
265
266 ./waf configure
267
268 ./waf --run <scenario>
269
Spyridon Mastorakis460f57c2014-12-17 00:44:14 -0800270 For more detailed information, refer to `README file
271 <https://github.com/cawka/ndnSIM-scenario-template/blob/master/README.md>`_.
Alexander Afanasyev701e5082013-03-13 09:47:50 -0700272
273Examples of template-based simulations
274~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
275
Alexander Afanasyev9ab7d672013-08-11 11:02:52 -07002761. ndnSIM examples from `<http://ndnsim.net>`_ website and more:
Alexander Afanasyev701e5082013-03-13 09:47:50 -0700277
278- `<http://github.com/cawka/ndnSIM-examples>`_, or
Alexander Afanasyev701e5082013-03-13 09:47:50 -0700279
Spyridon Mastorakis460f57c2014-12-17 00:44:14 -08002802. Script scenarios and graph processing scripts for simulations used in "A Case for Stateful
281 Forwarding Plane" paper by Yi et al. (`<http://dx.doi.org/10.1016/j.comcom.2013.01.005>`_):
Alexander Afanasyev701e5082013-03-13 09:47:50 -0700282
283- `<http://github.com/cawka/ndnSIM-comcom-stateful-fw>`_, or
Alexander Afanasyev701e5082013-03-13 09:47:50 -0700284
Spyridon Mastorakis460f57c2014-12-17 00:44:14 -08002853. Script scenarios and graph processing scripts for simulations used in "Rapid Traffic
286 Information Dissemination Using Named Data" paper by Wang et
287 al. (`<http://dx.doi.org/10.1145/2248361.2248365>`_):
Alexander Afanasyev701e5082013-03-13 09:47:50 -0700288
289- `<http://github.com/cawka/ndnSIM-nom-rapid-car2car>`_, or
Alexander Afanasyev701e5082013-03-13 09:47:50 -0700290
Spyridon Mastorakis460f57c2014-12-17 00:44:14 -0800291- Rocketfuel-based topology generator for ndnSIM preferred format (randomly assigned link
292 delays and bandwidth, based on estimated types of connections between nodes):
Alexander Afanasyev701e5082013-03-13 09:47:50 -0700293
294- `<http://github.com/cawka/ndnSIM-sample-topologies>`_, or