|
1 .. include:: replace.txt |
|
2 |
|
3 |
|
4 Getting Started |
|
5 --------------- |
|
6 |
|
7 Downloading ns-3 |
|
8 **************** |
|
9 |
|
10 The |ns3| system as a whole is a fairly complex system and has a |
|
11 number of dependencies on other components. Along with the systems you will |
|
12 most likely deal with every day (the GNU toolchain, Mercurial, you programmer |
|
13 editor) you will need to ensure that a number of additional libraries are |
|
14 present on your system before proceeding. |ns3| provides a wiki |
|
15 for your reading pleasure that includes pages with many useful hints and tips. |
|
16 One such page is the "Installation" page, |
|
17 http://www.nsnam.org/wiki/index.php/Installation. |
|
18 |
|
19 The "Prerequisites" section of this wiki page explains which packages are |
|
20 required to support common |ns3| options, and also provides the |
|
21 commands used to install them for common Linux variants. Cygwin users will |
|
22 have to use the Cygwin installer (if you are a Cygwin user, you used it to |
|
23 install Cygwin). |
|
24 |
|
25 You may want to take this opportunity to explore the |ns3| wiki |
|
26 a bit since there really is a wealth of information there. |
|
27 |
|
28 From this point forward, we are going to assume that the reader is working in |
|
29 Linux or a Linux emulation environment (Linux, Cygwin, etc.) and has the GNU |
|
30 toolchain installed and verified along with the prerequisites mentioned |
|
31 above. We are also going to assume that you have Mercurial and Waf installed |
|
32 and running on the target system as described in the "Getting Started" section |
|
33 of the |ns3| web site: |
|
34 http://www.nsnam.org/getting_started.html. |
|
35 |
|
36 The |ns3| code is available in Mercurial repositories on the server |
|
37 http://code.nsnam.org. You can also download a tarball release at |
|
38 http://www.nsnam.org/releases/, or you can work with repositories |
|
39 using Mercurial. We recommend using Mercurial unless there's a good reason |
|
40 not to. See the end of this section for instructions on how to get a tarball |
|
41 release. |
|
42 |
|
43 The simplest way to get started using Mercurial repositories is to use the |
|
44 ``ns-3-allinone`` environment. This is a set of scripts that manages the |
|
45 downloading and building of various subsystems of |ns3| for you. We |
|
46 recommend that you begin your |ns3| adventures in this environment |
|
47 as it can really simplify your life at this point. |
|
48 |
|
49 Downloading ns-3 Using Mercurial |
|
50 ++++++++++++++++++++++++++++++++ |
|
51 One practice is to create a directory called ``repos`` in one's home |
|
52 directory under which one can keep local Mercurial repositories. |
|
53 *Hint: we will assume you do this later in the tutorial.* If you adopt |
|
54 that approach, you can get a copy of ``ns-3-allinone`` by typing the |
|
55 following into your Linux shell (assuming you have installed Mercurial): |
|
56 |
|
57 :: |
|
58 |
|
59 cd |
|
60 mkdir repos |
|
61 cd repos |
|
62 hg clone http://code.nsnam.org/ns-3-allinone |
|
63 |
|
64 As the hg (Mercurial) command executes, you should see something like the |
|
65 following displayed, |
|
66 |
|
67 :: |
|
68 |
|
69 destination directory: ns-3-allinone |
|
70 requesting all changes |
|
71 adding changesets |
|
72 adding manifests |
|
73 adding file changes |
|
74 added 31 changesets with 45 changes to 7 files |
|
75 7 files updated, 0 files merged, 0 files removed, 0 files unresolved |
|
76 |
|
77 After the clone command completes, you should have a directory called |
|
78 ``ns-3-allinone`` under your ``~/repos`` directory, the contents of which should |
|
79 look something like the following: |
|
80 |
|
81 :: |
|
82 |
|
83 build.py* constants.py dist.py* download.py* README util.py |
|
84 |
|
85 Notice that you really just downloaded some Python scripts. The next step |
|
86 will be to use those scripts to download and build the |ns3| |
|
87 distribution of your choice. |
|
88 |
|
89 If you go to the following link: http://code.nsnam.org/, |
|
90 you will see a number of repositories. Many are the private repositories of |
|
91 the |ns3| development team. The repositories of interest to you will |
|
92 be prefixed with "ns-3". Official releases of |ns3| will be |
|
93 numbered as ``ns-3.<release>.<hotfix>``. For example, a second hotfix to a |
|
94 still hypothetical release nine of |ns3| would be numbered as |
|
95 ``ns-3.9.2``. |
|
96 |
|
97 The current development snapshot (unreleased) of |ns3| may be found |
|
98 at http://code.nsnam.org/ns-3-dev/. The |
|
99 developers attempt to keep these repository in consistent, working states but |
|
100 they are in a development area with unreleased code present, so you may want |
|
101 to consider staying with an official release if you do not need newly- |
|
102 introduced features. |
|
103 |
|
104 Since the release numbers are going to be changing, I will stick with |
|
105 the more constant ns-3-dev here in the tutorial, but you can replace the |
|
106 string "ns-3-dev" with your choice of release (e.g., ns-3.10) in the |
|
107 text below. You can find the latest version of the |
|
108 code either by inspection of the repository list or by going to the |
|
109 `"Getting Started" |
|
110 <http://www.nsnam.org/getting_started.html>`_ |
|
111 web page and looking for the latest release identifier. |
|
112 |
|
113 Go ahead and change into the ``ns-3-allinone`` directory you created when |
|
114 you cloned that repository. We are now going to use the ``download.py`` |
|
115 script to pull down the various pieces of |ns3| you will be using. |
|
116 |
|
117 Go ahead and type the following into your shell (remember you can substitute |
|
118 the name of your chosen release number instead of ``ns-3-dev`` -- like |
|
119 ``"ns-3.10"`` if you want to work with a |
|
120 stable release). |
|
121 |
|
122 :: |
|
123 |
|
124 ./download.py -n ns-3-dev |
|
125 |
|
126 Note that the default for the ``-n`` option is ``ns-3-dev`` and so the |
|
127 above is actually redundant. We provide this example to illustrate how to |
|
128 specify alternate repositories. In order to download ``ns-3-dev`` you |
|
129 can actually use the defaults and simply type, |
|
130 |
|
131 :: |
|
132 |
|
133 ./download.py |
|
134 |
|
135 As the hg (Mercurial) command executes, you should see something like the |
|
136 following, |
|
137 |
|
138 :: |
|
139 |
|
140 # |
|
141 # Get NS-3 |
|
142 # |
|
143 |
|
144 Cloning ns-3 branch |
|
145 => hg clone http://code.nsnam.org/ns-3-dev ns-3-dev |
|
146 requesting all changes |
|
147 adding changesets |
|
148 adding manifests |
|
149 adding file changes |
|
150 added 4634 changesets with 16500 changes to 1762 files |
|
151 870 files updated, 0 files merged, 0 files removed, 0 files unresolved |
|
152 |
|
153 This is output by the download script as it fetches the actual ``ns-3`` |
|
154 code from the repository. |
|
155 |
|
156 The download script is smart enough to know that on some platforms various |
|
157 pieces of ns-3 are not supported. On your platform you may not see some |
|
158 of these pieces come down. However, on most platforms, the process should |
|
159 continue with something like, |
|
160 |
|
161 :: |
|
162 |
|
163 # |
|
164 # Get PyBindGen |
|
165 # |
|
166 |
|
167 Required pybindgen version: 0.10.0.640 |
|
168 Trying to fetch pybindgen; this will fail if no network connection is available. Hit Ctrl-C to skip. |
|
169 => bzr checkout -rrevno:640 https://launchpad.net/pybindgen pybindgen |
|
170 Fetch was successful. |
|
171 |
|
172 This was the download script getting the Python bindings generator for you. |
|
173 Note that you will need bazaar (bzr), a version control system, to download |
|
174 PyBindGen. Next you should see (modulo platform variations) something along |
|
175 the lines of, |
|
176 |
|
177 :: |
|
178 |
|
179 # |
|
180 # Get NSC |
|
181 # |
|
182 |
|
183 Required NSC version: nsc-0.5.0 |
|
184 Retrieving nsc from https://secure.wand.net.nz/mercurial/nsc |
|
185 => hg clone https://secure.wand.net.nz/mercurial/nsc nsc |
|
186 requesting all changes |
|
187 adding changesets |
|
188 adding manifests |
|
189 adding file changes |
|
190 added 273 changesets with 17565 changes to 15175 files |
|
191 10622 files updated, 0 files merged, 0 files removed, 0 files unresolved |
|
192 |
|
193 This part of the process is the script downloading the Network Simulation |
|
194 Cradle for you. Note that NSC is not supported on OSX or Cygwin and works |
|
195 best with gcc-3.4 or gcc-4.2 or greater series. |
|
196 |
|
197 After the download.py script completes, you should have several new directories |
|
198 under ``~/repos/ns-3-allinone``: |
|
199 |
|
200 :: |
|
201 |
|
202 build.py* constants.pyc download.py* nsc/ README util.pyc |
|
203 constants.py dist.py* ns-3-dev/ pybindgen/ util.py |
|
204 |
|
205 Go ahead and change into ``ns-3-dev`` under your ``~/repos/ns-3-allinone`` |
|
206 directory. You should see something like the following there: |
|
207 |
|
208 :: |
|
209 |
|
210 AUTHORS examples/ RELEASE_NOTES utils/ wscript |
|
211 bindings/ LICENSE samples/ VERSION wutils.py |
|
212 CHANGES.html ns3/ scratch/ waf* |
|
213 doc/ README src/ waf.bat* |
|
214 |
|
215 You are now ready to build the |ns3| distribution. |
|
216 |
|
217 Downloading ns-3 Using a Tarball |
|
218 ++++++++++++++++++++++++++++++++ |
|
219 The process for downloading |ns3| via tarball is simpler than the |
|
220 Mercurial process since all of the pieces are pre-packaged for you. You just |
|
221 have to pick a release, download it and decompress it. |
|
222 |
|
223 As mentioned above, one practice is to create a directory called ``repos`` |
|
224 in one's home directory under which one can keep local Mercurial repositories. |
|
225 One could also keep a ``tarballs`` directory. *Hint: the tutorial |
|
226 will assume you downloaded into a ``repos`` directory, so remember the |
|
227 placekeeper.``* If you adopt the ``tarballs`` directory approach, you can |
|
228 get a copy of a release by typing the following into your Linux shell |
|
229 (substitute the appropriate version numbers, of course): |
|
230 |
|
231 :: |
|
232 |
|
233 cd |
|
234 mkdir tarballs |
|
235 cd tarballs |
|
236 wget http://www.nsnam.org/releases/ns-allinone-3.10.tar.bz2 |
|
237 tar xjf ns-allinone-3.10.tar.bz2 |
|
238 |
|
239 If you change into the directory ``ns-allinone-3.10`` you should see a |
|
240 number of files: |
|
241 |
|
242 :: |
|
243 |
|
244 build.py ns-3.10/ pybindgen-0.15.0/ util.py |
|
245 constants.py nsc-0.5.2/ README |
|
246 |
|
247 You are now ready to build the |ns3| distribution. |
|
248 |
|
249 Building ns-3 |
|
250 ************* |
|
251 |
|
252 Building with build.py |
|
253 ++++++++++++++++++++++ |
|
254 The first time you build the |ns3| project you should build using the |
|
255 ``allinone`` environment. This will get the project configured for you |
|
256 in the most commonly useful way. |
|
257 |
|
258 Change into the directory you created in the download section above. If you |
|
259 downloaded using Mercurial you should have a directory called |
|
260 ``ns-3-allinone`` under your ``~/repos`` directory. If you downloaded |
|
261 using a tarball you should have a directory called something like |
|
262 ``ns-allinone-3.10`` under your ``~/tarballs`` directory. Take a deep |
|
263 breath and type the following: |
|
264 |
|
265 :: |
|
266 |
|
267 ./build.py |
|
268 |
|
269 You will see lots of typical compiler output messages displayed as the build |
|
270 script builds the various pieces you downloaded. Eventually you should see the |
|
271 following magic words: |
|
272 |
|
273 :: |
|
274 |
|
275 Waf: Leaving directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build' |
|
276 'build' finished successfully (2m30.586s) |
|
277 |
|
278 Once the project has built you can say goodbye to your old friends, the |
|
279 ``ns-3-allinone`` scripts. You got what you needed from them and will now |
|
280 interact directly with Waf and we do it in the ``ns-3-dev`` directory, |
|
281 not in the ``ns-3-allinone`` directory. Go ahead and change into the |
|
282 ``ns-3-dev`` directory (or the directory for the appropriate release you |
|
283 downloaded. |
|
284 |
|
285 :: |
|
286 |
|
287 cd ns-3-dev |
|
288 |
|
289 Building with Waf |
|
290 +++++++++++++++++ |
|
291 We use Waf to configure and build the |ns3| project. It's not |
|
292 strictly required at this point, but it will be valuable to take a slight |
|
293 detour and look at how to make changes to the configuration of the project. |
|
294 Probably the most useful configuration change you can make will be to |
|
295 build the optimized version of the code. By default you have configured |
|
296 your project to build the debug version. Let's tell the project to do |
|
297 make an optimized build. To explain to Waf that it should do optimized |
|
298 builds you will need to execute the following command, |
|
299 |
|
300 :: |
|
301 |
|
302 ./waf -d optimized configure |
|
303 |
|
304 This runs Waf out of the local directory (which is provided as a convenience |
|
305 for you). As the build system checks for various dependencies you should see |
|
306 output that looks similar to the following, |
|
307 |
|
308 :: |
|
309 |
|
310 Checking for program g++ : ok /usr/bin/g++ |
|
311 Checking for program cpp : ok /usr/bin/cpp |
|
312 Checking for program ar : ok /usr/bin/ar |
|
313 Checking for program ranlib : ok /usr/bin/ranlib |
|
314 Checking for g++ : ok |
|
315 Checking for program pkg-config : ok /usr/bin/pkg-config |
|
316 Checking for -Wno-error=deprecated-declarations support : yes |
|
317 Checking for -Wl,--soname=foo support : yes |
|
318 Checking for header stdlib.h : ok |
|
319 Checking for header signal.h : ok |
|
320 Checking for header pthread.h : ok |
|
321 Checking for high precision time implementation : 128-bit integer |
|
322 Checking for header stdint.h : ok |
|
323 Checking for header inttypes.h : ok |
|
324 Checking for header sys/inttypes.h : not found |
|
325 Checking for library rt : ok |
|
326 Checking for header netpacket/packet.h : ok |
|
327 Checking for pkg-config flags for GSL : ok |
|
328 Checking for header linux/if_tun.h : ok |
|
329 Checking for pkg-config flags for GTK_CONFIG_STORE : ok |
|
330 Checking for pkg-config flags for LIBXML2 : ok |
|
331 Checking for library sqlite3 : ok |
|
332 Checking for NSC location : ok ../nsc (guessed) |
|
333 Checking for library dl : ok |
|
334 Checking for NSC supported architecture x86_64 : ok |
|
335 Checking for program python : ok /usr/bin/python |
|
336 Checking for Python version >= 2.3 : ok 2.5.2 |
|
337 Checking for library python2.5 : ok |
|
338 Checking for program python2.5-config : ok /usr/bin/python2.5-config |
|
339 Checking for header Python.h : ok |
|
340 Checking for -fvisibility=hidden support : yes |
|
341 Checking for pybindgen location : ok ../pybindgen (guessed) |
|
342 Checking for Python module pybindgen : ok |
|
343 Checking for pybindgen version : ok 0.10.0.640 |
|
344 Checking for Python module pygccxml : ok |
|
345 Checking for pygccxml version : ok 0.9.5 |
|
346 Checking for program gccxml : ok /usr/local/bin/gccxml |
|
347 Checking for gccxml version : ok 0.9.0 |
|
348 Checking for program sudo : ok /usr/bin/sudo |
|
349 Checking for program hg : ok /usr/bin/hg |
|
350 Checking for program valgrind : ok /usr/bin/valgrind |
|
351 ---- Summary of optional NS-3 features: |
|
352 Threading Primitives : enabled |
|
353 Real Time Simulator : enabled |
|
354 Emulated Net Device : enabled |
|
355 GNU Scientific Library (GSL) : enabled |
|
356 Tap Bridge : enabled |
|
357 GtkConfigStore : enabled |
|
358 XmlIo : enabled |
|
359 SQlite stats data output : enabled |
|
360 Network Simulation Cradle : enabled |
|
361 Python Bindings : enabled |
|
362 Python API Scanning Support : enabled |
|
363 Use sudo to set suid bit : not enabled (option --enable-sudo not selected) |
|
364 Build examples and samples : enabled |
|
365 Static build : not enabled (option --enable-static not selected) |
|
366 'configure' finished successfully (2.870s) |
|
367 |
|
368 Note the last part of the above output. Some ns-3 options are not enabled by |
|
369 default or require support from the underlying system to work properly. |
|
370 For instance, to enable XmlTo, the library libxml-2.0 must be found on the |
|
371 system. If this library were not found, the corresponding |ns3| feature |
|
372 would not be enabled and a message would be displayed. Note further that there is |
|
373 a feature to use the program ``sudo`` to set the suid bit of certain programs. |
|
374 This is not enabled by default and so this feature is reported as "not enabled." |
|
375 |
|
376 Now go ahead and switch back to the debug build. |
|
377 |
|
378 :: |
|
379 |
|
380 ./waf -d debug configure |
|
381 |
|
382 The build system is now configured and you can build the debug versions of |
|
383 the |ns3| programs by simply typing, |
|
384 |
|
385 :: |
|
386 |
|
387 ./waf |
|
388 |
|
389 Some waf commands are meaningful during the build phase and some commands are valid |
|
390 in the configuration phase. For example, if you wanted to use the emulation |
|
391 features of |ns3| you might want to enable setting the suid bit using |
|
392 sudo as described above. This turns out to be a configuration-time command, and so |
|
393 you could reconfigure using the following command |
|
394 |
|
395 :: |
|
396 |
|
397 ./waf -d debug --enable-sudo configure |
|
398 |
|
399 If you do this, waf will have run sudo to change the socket creator programs of the |
|
400 emulation code to run as root. There are many other configure- and build-time options |
|
401 available in waf. To explore these options, type: |
|
402 |
|
403 :: |
|
404 |
|
405 ./waf --help |
|
406 |
|
407 We'll use some of the testing-related commands in the next section. |
|
408 |
|
409 Okay, sorry, I made you build the |ns3| part of the system twice, |
|
410 but now you know how to change the configuration and build optimized code. |
|
411 |
|
412 Testing ns-3 |
|
413 ************ |
|
414 |
|
415 You can run the unit tests of the |ns3| distribution by running the |
|
416 "./test.py -c core" script, |
|
417 |
|
418 :: |
|
419 |
|
420 ./test.py -c core |
|
421 |
|
422 These tests are run in parallel by waf. You should eventually |
|
423 see a report saying that, |
|
424 |
|
425 :: |
|
426 |
|
427 47 of 47 tests passed (47 passed, 0 failed, 0 crashed, 0 valgrind errors) |
|
428 |
|
429 This is the important message. |
|
430 |
|
431 You will also see output from the test runner and the output will actually look something like, |
|
432 |
|
433 :: |
|
434 |
|
435 Waf: Entering directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build' |
|
436 Waf: Leaving directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build' |
|
437 'build' finished successfully (1.799s) |
|
438 PASS: TestSuite ns3-wifi-interference |
|
439 PASS: TestSuite histogram |
|
440 PASS: TestSuite sample |
|
441 PASS: TestSuite ipv4-address-helper |
|
442 PASS: TestSuite devices-wifi |
|
443 PASS: TestSuite propagation-loss-model |
|
444 |
|
445 ... |
|
446 |
|
447 PASS: TestSuite attributes |
|
448 PASS: TestSuite config |
|
449 PASS: TestSuite global-value |
|
450 PASS: TestSuite command-line |
|
451 PASS: TestSuite basic-random-number |
|
452 PASS: TestSuite object |
|
453 PASS: TestSuite random-number-generators |
|
454 47 of 47 tests passed (47 passed, 0 failed, 0 crashed, 0 valgrind errors) |
|
455 |
|
456 This command is typically run by ``users`` to quickly verify that an |
|
457 |ns3| distribution has built correctly. |
|
458 |
|
459 Running a Script |
|
460 **************** |
|
461 We typically run scripts under the control of Waf. This allows the build |
|
462 system to ensure that the shared library paths are set correctly and that |
|
463 the libraries are available at run time. To run a program, simply use the |
|
464 ``--run`` option in Waf. Let's run the |ns3| equivalent of the |
|
465 ubiquitous hello world program by typing the following: |
|
466 |
|
467 :: |
|
468 |
|
469 ./waf --run hello-simulator |
|
470 |
|
471 Waf first checks to make sure that the program is built correctly and |
|
472 executes a build if required. Waf then executes the program, which |
|
473 produces the following output. |
|
474 |
|
475 :: |
|
476 |
|
477 Hello Simulator |
|
478 |
|
479 *Congratulations. You are now an ns-3 user.* |
|
480 |
|
481 *What do I do if I don't see the output?* |
|
482 |
|
483 If you don't see ``waf`` messages indicating that the build was |
|
484 completed successfully, but do not see the "Hello Simulator" output, |
|
485 chances are that you have switched your build mode to "optimized" in |
|
486 the "Building with Waf" section, but have missed the change back to |
|
487 "debug" mode. All of the console output used in this tutorial uses a |
|
488 special |ns3| logging component that is useful for printing |
|
489 user messages to the console. Output from this component is |
|
490 automatically disabled when you compile optimized code -- it is |
|
491 "optimized out." If you don't see the "Hello Simulator" output, |
|
492 type the following, |
|
493 |
|
494 :: |
|
495 |
|
496 ./waf -d debug configure |
|
497 |
|
498 to tell ``waf`` to build the debug versions of the |ns3| |
|
499 programs. You must still build the actual debug version of the code by |
|
500 typing, |
|
501 |
|
502 :: |
|
503 |
|
504 ./waf |
|
505 |
|
506 Now, if you run the ``hello-simulator`` program, you should see the |
|
507 expected output. |
|
508 |
|
509 If you want to run programs under another tool such as gdb or valgrind, |
|
510 see this `wiki entry |
|
511 <http://www.nsnam.org/wiki/index.php/User_FAQ#How_to_run_NS-3_programs_under_another_tool>`_. |
|
512 |