3 

     3 

     4 Getting Started

     4 Getting Started

     5 ---------------

     5 ---------------

     6 

     6 

     7 This section is aimed at getting a user to a working state starting

     7 This section is aimed at getting a user to a working state starting

    87 get a copy of a release by typing the following into your Linux shell 

    87 get a copy of a release by typing the following into your Linux shell 

    88 (substitute the appropriate version numbers, of course):

    88 (substitute the appropriate version numbers, of course):

    89 

    89 

    90 ::

    90 ::

    91 

    91 

    97 

    97 

    98 If you change into the directory ``ns-allinone-3.17`` you should see a

    98 If you change into the directory ``ns-allinone-3.17`` you should see a

    99 number of files:

    99 number of files:

   100 

   100 

   101 ::

   101 ::

   121 an example directory name).  You can get a copy of ``bake`` by typing the 

   121 an example directory name).  You can get a copy of ``bake`` by typing the 

   122 following into your Linux shell (assuming you have installed Mercurial):

   122 following into your Linux shell (assuming you have installed Mercurial):

   123 

   123 

   124 ::

   124 ::

   125 

   125 

   130 

   130 

   131 As the hg (Mercurial) command executes, you should see something like the 

   131 As the hg (Mercurial) command executes, you should see something like the 

   132 following displayed,

   132 following displayed,

   133 

   133 

   134 ::

   134 ::

   189 outside of the directory it was downloaded into, it is advisable

   189 outside of the directory it was downloaded into, it is advisable

   190 to put bake into your path, such as follows (Linux bash shell example):

   190 to put bake into your path, such as follows (Linux bash shell example):

   191 

   191 

   192 ::

   192 ::

   193 

   193 

   197 

   197 

   198 However, setting environment variables is not strictly necessary to

   198 However, setting environment variables is not strictly necessary to

   199 complete this tutorial, so we'll call bake directly by specifying the path 

   199 complete this tutorial, so we'll call bake directly by specifying the path 

   200 to it in our shell commands.

   200 to it in our shell commands.

   201 

   201 

   202 Step into the workspace directory and type the following into your shell:

   202 Step into the workspace directory and type the following into your shell:

   203 

   203 

   204 ::

   204 ::

   205 

   205 

   207 

   207 

   208 Next, we'l ask bake to check whether we have enough tools to download

   208 Next, we'l ask bake to check whether we have enough tools to download

   209 various components.  Type:

   209 various components.  Type:

   210 

   210 

   211 ::

   211 ::

   212 

   212 

   214 

   214 

   215 You should see something like the following,

   215 You should see something like the following,

   216 

   216 

   217 ::

   217 ::

   218 

   218 

   230    > Make - OK

   230    > Make - OK

   231    > cMake - OK

   231    > cMake - OK

   232    > patch tool - OK

   232    > patch tool - OK

   233    > autoreconf tool - OK

   233    > autoreconf tool - OK

   234 

   234 

   236 

   238 

   237 In particular, download tools such as Mercurial, CVS, GIT, and Bazaar

   239 In particular, download tools such as Mercurial, CVS, GIT, and Bazaar

   238 are our principal concerns at this point, since they allow us to fetch

   240 are our principal concerns at this point, since they allow us to fetch

   239 the code.  Please install missing tools at this stage if you are able to.

   241 the code.  Please install missing tools at this stage if you are able to.

   240 

   242 

   284 ``ns-allinone-3.17`` under your ``~/workspace`` directory.  

   286 ``ns-allinone-3.17`` under your ``~/workspace`` directory.  

   285 Type the following:

   287 Type the following:

   286 

   288 

   287 ::

   289 ::

   288 

   290 

   290 

   292 

   291 Because we are working with examples and tests in this tutorial, and

   293 Because we are working with examples and tests in this tutorial, and

   292 because they are not built by default in |ns3|, the arguments for

   294 because they are not built by default in |ns3|, the arguments for

   293 build.py tells it to build them for us.  The program also defaults to

   295 build.py tells it to build them for us.  The program also defaults to

   294 building all available modules.  Later, you can build

   296 building all available modules.  Later, you can build

   321   

   323   

   322    Modules not built (see ns-3 tutorial for explanation):

   324    Modules not built (see ns-3 tutorial for explanation):

   323    brite                     click                     openflow                 

   325    brite                     click                     openflow                 

   324    visualizer               

   326    visualizer               

   325 

   327 

   327 

   329 

   328 Regarding the portion about modules not built:

   330 Regarding the portion about modules not built:

   329 

   331 

   330 ::

   332 ::

   331 

   333 

   345 If you used bake above to fetch source code from project repositories, you

   347 If you used bake above to fetch source code from project repositories, you

   346 may continue to use it to build |ns3|.  Type 

   348 may continue to use it to build |ns3|.  Type 

   347 

   349 

   348 ::

   350 ::

   349 

   351 

   351 

   353 

   352 and you should see something like:

   354 and you should see something like:

   353 

   355 

   354 :: 

   356 :: 

   355 

   357 

   362 If there happens to be a failure, please have a look at what the following

   364 If there happens to be a failure, please have a look at what the following

   363 command tells you; it may give a hint as to a missing dependency:

   365 command tells you; it may give a hint as to a missing dependency:

   364 

   366 

   365 ::

   367 ::

   366 

   368 

   368 

   370 

   369 This will list out the various dependencies of the packages you are

   371 This will list out the various dependencies of the packages you are

   370 trying to build.

   372 trying to build.

   371 

   373 

   372 Building with Waf

   374 Building with Waf

   390 builds that include the examples and tests, you will need to execute the 

   392 builds that include the examples and tests, you will need to execute the 

   391 following commands,

   393 following commands,

   392 

   394 

   393 ::

   395 ::

   394 

   396 

   397 

   399 

   398 This runs Waf out of the local directory (which is provided as a convenience

   400 This runs Waf out of the local directory (which is provided as a convenience

   399 for you).  The first command to clean out the previous build is not 

   401 for you).  The first command to clean out the previous build is not 

   400 typically strictly necessary but is good practice; it will remove the

   402 typically strictly necessary but is good practice; it will remove the

   401 previously built libraries and object files found in directory ``build/``. 

   403 previously built libraries and object files found in directory ``build/``. 

   474 

   476 

   475 Now go ahead and switch back to the debug build that includes the examples and tests.

   477 Now go ahead and switch back to the debug build that includes the examples and tests.

   476 

   478 

   477 ::

   479 ::

   478 

   480 

   481 

   483 

   482 The build system is now configured and you can build the debug versions of 

   484 The build system is now configured and you can build the debug versions of 

   483 the |ns3| programs by simply typing

   485 the |ns3| programs by simply typing

   484 

   486 

   485 ::

   487 ::

   486 

   488 

   488 

   490 

   489 Okay, sorry, I made you build the |ns3| part of the system twice,

   491 Okay, sorry, I made you build the |ns3| part of the system twice,

   490 but now you know how to change the configuration and build optimized code.

   492 but now you know how to change the configuration and build optimized code.

   491 

   493 

   492 Here are a few more introductory tips about Waf.

   494 Here are a few more introductory tips about Waf.

   496 sudo as described above.  This turns out to be a configuration-time command, and so 

   498 sudo as described above.  This turns out to be a configuration-time command, and so 

   497 you could reconfigure using the following command that also includes the examples and tests

   499 you could reconfigure using the following command that also includes the examples and tests

   498 

   500 

   499 ::

   501 ::

   500 

   502 

   502 

   504 

   503 If you do this, waf will have run sudo to change the socket creator programs of the

   505 If you do this, waf will have run sudo to change the socket creator programs of the

   504 emulation code to run as root.  There are many other configure- and build-time options

   506 emulation code to run as root.  There are many other configure- and build-time options

   505 available in waf.  To explore these options, type:

   507 available in waf.  To explore these options, type:

   506 

   508 

   507 ::

   509 ::

   508 

   510 

   510 

   512 

   511 We'll use some of the testing-related commands in the next section.

   513 We'll use some of the testing-related commands in the next section.

   512 

   514 

   513 Finally, as an aside, it is possible to specify that waf builds the 

   515 Finally, as an aside, it is possible to specify that waf builds the 

   514 project in 

   516 project in 

   515 a directory different than the default ``build/`` directory by passing

   517 a directory different than the default ``build/`` directory by passing

   516 the ``-o`` option to configure; e.g.

   518 the ``-o`` option to configure; e.g.

   517 

   519 

   518 ::

   520 ::

   519 

   521 

   521 

   523 

   522 This allows users to work with multiple builds rather than always

   524 This allows users to work with multiple builds rather than always

   523 overwriting the last build.

   525 overwriting the last build.

   524 

   526 

   525 In the examples above, waf uses GCC C++ compiler, command ``g++``, for

   527 In the examples above, waf uses GCC C++ compiler, command ``g++``, for

   526 building ns-3. However, it's possible to change C++ compiler used by waf.

   528 building ns-3. However, it's possible to change C++ compiler used by waf.

   527 Say one wants to use Clang C++ compiler, command ``clang++``; it's done by

   529 Say one wants to use Clang C++ compiler, command ``clang++``; it's done by

   528 

   530 

   529 ::

   531 ::

   530 

   532 

   533 

   535 

   534 One can also set up waf to do distributed compilation with ``distcc`` in

   536 One can also set up waf to do distributed compilation with ``distcc`` in

   535 a similar way:

   537 a similar way:

   536 

   538 

   537 ::

   539 ::

   538 

   540 

   541 

   543 

   542 More info on distcc and distributed compilation can be found on it's

   544 More info on distcc and distributed compilation can be found on it's

   543 `project page

   545 `project page

   544 <http://code.google.com/p/distcc/>`_

   546 <http://code.google.com/p/distcc/>`_

   545 under Documentation section.

   547 under Documentation section.

   550 You can run the unit tests of the |ns3| distribution by running the 

   552 You can run the unit tests of the |ns3| distribution by running the 

   551 "./test.py -c core" script,

   553 "./test.py -c core" script,

   552 

   554 

   553 ::

   555 ::

   554 

   556 

   556 

   558 

   557 These tests are run in parallel by waf. You should eventually

   559 These tests are run in parallel by waf. You should eventually

   558 see a report saying that,

   560 see a report saying that,

   559 

   561 

   560 ::

   562 ::

   615 ``--run`` option in Waf.  Let's run the |ns3| equivalent of the

   617 ``--run`` option in Waf.  Let's run the |ns3| equivalent of the

   616 ubiquitous hello world program by typing the following:

   618 ubiquitous hello world program by typing the following:

   617 

   619 

   618 ::

   620 ::

   619 

   621 

   621 

   623 

   622 Waf first checks to make sure that the program is built correctly and 

   624 Waf first checks to make sure that the program is built correctly and 

   623 executes a build if required.  Waf then executes the program, which 

   625 executes a build if required.  Waf then executes the program, which 

   624 produces the following output.

   626 produces the following output.

   625 

   627 

   642 "optimized out."  If you don't see the "Hello Simulator" output,

   644 "optimized out."  If you don't see the "Hello Simulator" output,

   643 type the following,

   645 type the following,

   644 

   646 

   645 ::

   647 ::

   646 

   648 

   648 

   650 

   649 to tell ``waf`` to build the debug versions of the |ns3| 

   651 to tell ``waf`` to build the debug versions of the |ns3| 

   650 programs that includes the examples and tests.  You must still build 

   652 programs that includes the examples and tests.  You must still build 

   651 the actual debug version of the code by typing,

   653 the actual debug version of the code by typing,

   652 

   654 

   653 ::

   655 ::

   654 

   656 

   656 

   658 

   657 Now, if you run the ``hello-simulator`` program, you should see the 

   659 Now, if you run the ``hello-simulator`` program, you should see the 

   658 expected output.

   660 expected output.

   659 

   661 

   660 If you want to run programs under another tool such as gdb or valgrind,

   662 If you want to run programs under another tool such as gdb or valgrind,