51 release. |
51 release. |
52 |
52 |
53 @cindex repository |
53 @cindex repository |
54 The simplest way to get started using Mercurial repositories is to use the |
54 The simplest way to get started using Mercurial repositories is to use the |
55 @code{ns-3-allinone} environment. This is a set of scripts that manages the |
55 @code{ns-3-allinone} environment. This is a set of scripts that manages the |
56 downloading and building of various subystems of ns-3 for you. We recommend |
56 downloading and building of various subystems of @command{ns-3} for you. We |
57 that you begin your @command{ns-3} adventures in this environment as it can |
57 recommend that you begin your @command{ns-3} adventures in this environment |
58 really simplify your life at this point. |
58 as it can really simplify your life at this point. |
59 |
59 |
60 @subsection Downloading ns-3 Using Mercurial |
60 @subsection Downloading ns-3 Using Mercurial |
61 One practice is to create a directory called @code{repos} in one's home |
61 One practice is to create a directory called @code{repos} in one's home |
62 directory under which one can keep local Mercurial repositories. |
62 directory under which one can keep local Mercurial repositories. |
63 @emph{Hint: we will assume you do this later in the tutorial.} If you adopt |
63 @emph{Hint: we will assume you do this later in the tutorial.} If you adopt |
131 code either by inspection of the repository list or by going to the ``Getting |
131 code either by inspection of the repository list or by going to the ``Getting |
132 Started'' web page and looking for the latest release identifier. |
132 Started'' web page and looking for the latest release identifier. |
133 |
133 |
134 Go ahead and change into the @code{ns-3-allinone} directory you created when |
134 Go ahead and change into the @code{ns-3-allinone} directory you created when |
135 you cloned that repository. We are now going to use the @code{download.py} |
135 you cloned that repository. We are now going to use the @code{download.py} |
136 script to pull down the various pieces of @code{ns-3} you will be using/ |
136 script to pull down the various pieces of @command{ns-3} you will be using/ |
137 |
137 |
138 Go ahead and type the following into your shell (remember you can substitute |
138 Go ahead and type the following into your shell (remember you can substitute |
139 the name of your chosen release number instead of @code{ns-3-dev} -- like |
139 the name of your chosen release number instead of @code{ns-3-dev} -- like |
140 @code{"ns-3.4"} and @code{"ns-3.4-ref-traces"} if you want to work with a |
140 @code{"ns-3.4"} and @code{"ns-3.4-ref-traces"} if you want to work with a |
141 stable release). |
141 stable release). |
238 @end verbatim |
238 @end verbatim |
239 |
239 |
240 You are now ready to build the @command{ns-3} distribution. |
240 You are now ready to build the @command{ns-3} distribution. |
241 |
241 |
242 @subsection Downloading ns-3 Using a Tarball |
242 @subsection Downloading ns-3 Using a Tarball |
243 The process for downloading @code{ns-3} via tarball is simpler than the |
243 The process for downloading @command{ns-3} via tarball is simpler than the |
244 Mercurial process since all of the pieces are pre-packaged for you. You just |
244 Mercurial process since all of the pieces are pre-packaged for you. You just |
245 have to pick a release, download it and decompress it. |
245 have to pick a release, download it and decompress it. |
246 |
246 |
247 As mentioned above, one practice is to create a directory called @code{repos} |
247 As mentioned above, one practice is to create a directory called @code{repos} |
248 in one's home directory under which one can keep local Mercurial repositories. |
248 in one's home directory under which one can keep local Mercurial repositories. |
468 @command{ns-3} distribution has built correctly. |
468 @command{ns-3} distribution has built correctly. |
469 |
469 |
470 @cindex regression tests |
470 @cindex regression tests |
471 You can also run our regression test suite to ensure that your distribution and |
471 You can also run our regression test suite to ensure that your distribution and |
472 tool chain have produced binaries that generate output that is identical to |
472 tool chain have produced binaries that generate output that is identical to |
473 reference output files stored in a central location. To run the regression |
473 known-good reference output files. You downloaded these reference traces to |
474 tests, you provide Waf with the regression flag. |
474 your machine during the download process above. (Warning: The @code{ns-3.2} |
|
475 and @code{ns-3.3} releases do not use the @code{ns-3-allinone} environment |
|
476 and require you to be online when you run regression tests because they |
|
477 dynamically synchronize the reference traces directory with an online |
|
478 repository immediately prior to the run). |
|
479 |
|
480 During regression testing Waf will run a number of tests that generate what we |
|
481 call trace files. The content of these trace files are compared with the |
|
482 reference traces. If they are identical, the regression tests report a PASS |
|
483 status. If a regression test fails you will see a FAIL indication along with a |
|
484 pointer to the offending trace file and its associated reference trace file |
|
485 along with a suggestion on diff parameters and options in order to see what |
|
486 has gone awry. If the error was discovered in a pcap file, it will be useful |
|
487 to convert the pcap files to text using tcpdump prior to comparison. |
|
488 |
|
489 Some regression tests wmay be SKIPped if the required support |
|
490 is not present. |
|
491 |
|
492 To run the regression tests, you provide Waf with the regression flag. |
475 |
493 |
476 @verbatim |
494 @verbatim |
477 ./waf --regression |
495 ./waf --regression |
478 @end verbatim |
496 @end verbatim |
479 |
497 |
480 Waf will verify that the current files in the @command{ns-3} distribution are |
498 You should see messages indicating that many tests are being run and are |
481 built and will then look for trace files in the aforementioned centralized |
499 passing. |
482 location. If your tool chain includes Mercurial, the regression tests will |
|
483 be downloaded from a repository at @code{code.nsnam.org}. If you do not have |
|
484 Mercurial installed, the reference traces will be downloaded from a tarball |
|
485 located in the releases section of @code{www.nsnam.org}. The particular name |
|
486 of the reference trace location is built from the @command{ns-3} version |
|
487 located in the VERSION file, so don't change that string yourself unless you |
|
488 know what you are doing. (Warning: The ns-3.2 release requires you |
|
489 to be online when you run regression tests because it synchronizes the |
|
490 trace directory with an online repository). |
|
491 |
|
492 Once the reference traces are downloaded to your local machine, Waf will run |
|
493 a number of tests that generate what we call trace files. The content of |
|
494 these trace files are compared with the reference traces just downloaded. If |
|
495 they are identical, the regression tests report a PASS status. If the |
|
496 regression tests pass, you should see something like, |
|
497 |
500 |
498 @verbatim |
501 @verbatim |
499 Entering directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build' |
502 Entering directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build' |
500 [647/669] regression-test (test-csma-bridge) |
503 [647/669] regression-test (test-csma-bridge) |
501 [648/669] regression-test (test-csma-broadcast) |
504 [648/669] regression-test (test-csma-broadcast) |
508 Regression testing summary: |
511 Regression testing summary: |
509 PASS: 22 of 22 tests passed |
512 PASS: 22 of 22 tests passed |
510 Build finished successfully (00:00:23) |
513 Build finished successfully (00:00:23) |
511 @end verbatim |
514 @end verbatim |
512 |
515 |
513 If a regression tests fails you will see a FAIL indication along with a |
516 If you want to take a look at an example of what might be checked during |
514 pointer to the offending trace file and its associated reference trace file |
517 a regression test, you can do the following: |
515 along with a suggestion on diff parameters and options in order to see what |
518 |
516 has gone awry. Some regression tests wmay be SKIPped if the required support |
519 @verbatim |
517 is not present. |
520 cd build/debug/regression/traces/second.ref |
|
521 tcpdump -nn -tt -r second-1-1.pcap |
|
522 @end verbatim |
|
523 |
|
524 The output should be clear to anyone who is familiar with tcpdump or net |
|
525 sniffers. We'll have much more to say on pcap files later in this tutorial. |
|
526 |
|
527 Remember to cd back into the top-level @command{ns-3} directory |
|
528 after you are done: |
|
529 |
|
530 @verbatim |
|
531 cd ../../../../.. |
|
532 @end verbatim |
518 |
533 |
519 @c ======================================================================== |
534 @c ======================================================================== |
520 @c Running a Script |
535 @c Running a Script |
521 @c ======================================================================== |
536 @c ======================================================================== |
522 |
537 |