@c ========================================================================

@c Begin document body here

@c ========================================================================

@c ========================================================================

@c PART:  Getting Started

@c ========================================================================

@c The below chapters are under the major heading "Getting Started"

@c This is similar to the Latex \part command

@c

@c ========================================================================

@c Getting Started

@c ========================================================================

@node Getting Started

@chapter Getting Started

@menu

* Downloading ns-3::

* Building ns-3::

* Testing ns-3::

* Running a Script::

@end menu

@c ========================================================================

@c Downloading ns-3

@c ========================================================================

@node Downloading ns-3

@section Downloading ns-3

@cindex Linux

@cindex Cygwin

@cindex GNU

@cindex toolchain

@cindex Mercurial

@cindex Waf

From this point forward, we are going to assume that the reader is working in

Linux or a Linux emulation environment (Linux, Cygwin, etc.) and has the GNU

toolchain installed and verified.  We are also going to assume that you have

Mercurial and Waf installed and running on the target system as described in

the Getting Started section of the  @command{ns-3} web site: 

@uref{http://www.nsnam.org/getting_started.html}.

@cindex tarball

The @command{ns-3} code is available in Mercurial repositories on the server

@cindex repository

If you go to the following link: @uref{http://code.nsnam.org/},

you will see a number of repositories.  Many are the private repositories of

the @command{ns-3} development team.  The repositories of interest to you will

be prefixed with ``ns-3''.  The current development snapshot (unreleased)

of @command{ns-3} may be found at: @uref{http://code.nsnam.org/ns-3-dev/}.

Official releases of @command{ns-3} will be numbered as @code{ns-3.<release>}

with any requred  hotfixes added as minor release numbers.  For example, a 

second hotfix to a hypothetical release nine of @command{ns-3} would be

numbered @code{ns-3.9.2}.

The current development snapshot (unreleased) of @command{ns-3} may be found 

at:  @uref{http://code.nsnam.org/ns-3-dev/}.  The developers attempt to keep

this repository in a consistent, working state but it is a development area 

with unreleased code present, so you may want to consider staying with an 

Since the release numbers are going to be changing, I will stick with 

the more constant ns-3-dev here in the tutorial, but you can replace the 

below.  You can find the latest version  of the code either by inspection of 

the repository list or by going to the ``Getting Started'' web page and 

looking for the latest release identifier.

One practice is to create a directory called @code{repos} in one's home 

directory under which one can keep local Mercurial repositories.  

@emph{Hint:  we will assume you do this later in the tutorial.}  If you adopt

that approach, you can get a copy of the development version of 

@command{ns-3} by typing the following into your Linux shell (assuming you 

have installed Mercurial):

@verbatim

  cd

  mkdir repos

  cd repos

  hg clone http://code.nanam.org/ns-3-dev

@end verbatim

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

following,

@verbatim

  destination directory: ns-3-dev

  requesting all changes

  adding changesets

  adding manifests

  adding file changes

  added 3276 changesets with 12301 changes to 1353 files

  594 files updated, 0 files merged, 0 files removed, 0 files unresolved

@end verbatim

After the clone command completes, you should have a directory called 

ns-3-dev under your @code{~/repos} directory, the contents of which should 

look something like the following:

@verbatim

  AUTHORS  examples/  README         samples/  utils/   waf.bat*

  build/   LICENSE    regression/    scratch/  VERSION  wscript

  doc/     ns3/       RELEASE_NOTES  src/      waf*

@end verbatim

You are now ready to build the @command{ns-3} distribution.

@c ========================================================================

@c Building ns-3

@c ========================================================================

@node Building ns-3

@section Building ns-3

@cindex building with Waf

@cindex configuring Waf

@cindex building debug version with Waf

@cindex compiling with Waf

@cindex unit tests with Waf

@cindex regression tests with Waf

We use Waf to build the @command{ns-3} project.  The first thing you will need

to do is to configure the build.  For reasons that will become clear later, 

we are going to work with debug builds in the tutorial.  To explain to Waf 

that it should do debug builds you will need to execute the following command,

@verbatim

  ./waf -d debug configure

@end verbatim

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

for you).  As the build system checks for various dependencies you should see

output that looks similar to the following,

@verbatim

@end verbatim

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

the @command{ns-3} programs by simply typing,

@verbatim

  ./waf

@end verbatim

You will see many Waf status messages displayed as the system compiles.  The

@verbatim

  Compilation finished successfully

@end verbatim

@c ========================================================================

@c Testing ns-3

@c ========================================================================

@node Testing ns-3

@section Testing ns-3

@cindex unit tests

@verbatim

  ./waf check

@end verbatim

You should see a report from each unit test that executes indicating that the

test has passed.

@verbatim

  ~/repos/ns-3-dev > ./waf check

  Entering directory `/home/craigdo/repos/ns-3-dev/build'

  Compilation finished successfully

  PASS AddressHelper

  PASS Wifi

  PASS DcfManager

  ...

  PASS Object

  PASS Ptr

  PASS Callback

  ~/repos/ns-3-dev >

@end verbatim

This command is typically run by @code{users} to quickly verify that an 

@command{ns-3} distribution has built correctly.  

You can also run our regression test suite to ensure that your distribution and

tool chain have produced binaries that generate output that is identical to

reference output files stored in a central location.  To run the regression 

tests, you provide Waf with the regression flag.

@verbatim

  ./waf --regression

@end verbatim

Waf will verify that the current files in the @command{ns-3} distribution are

built and will then look for trace files in the aforementioned centralized 

location.  If your tool chain includes Mercurial, the regression tests will 

be downloaded from a repository at @code{code.nsnam.org}.  If you do not have 

Mercurial installed, the reference traces will be downloaded from a tarball 

located in the releases section of @code{www.nsnam.org}.  The particular name 

of the reference trace location is built from the @command{ns-3} version 

located in the VERSION file, so don't change that string yourself unless you 

Once the reference traces are downloaded to your local machine, Waf will run

a number of tests that generate what we call trace files.  The content of 

these trace files are compared with the reference traces just downloaded.  If 

they are identical, the regression tests report a PASS status.  If the 

regression tests pass, you should see something like,

@verbatim

  ~/repos/ns-3-dev > ./waf --regression

  Entering directory `/home/craigdo/repos/ns-3-dev/build'

  ========== Running Regression Tests ==========

  Synchronizing reference traces using Mercurial.

  PASS test-csma-broadcast

  PASS test-csma-multicast

  PASS test-csma-one-subnet

  PASS test-csma-packet-socket

  PASS test-simple-error-model

  PASS test-simple-global-routing

  PASS test-simple-point-to-point-olsr

  PASS test-tcp-large-transfer

  PASS test-udp-echo

  ~/repos/ns-3-dev >

@end verbatim

If a regression tests fails you will see a FAIL indication along with a

pointer to the offending trace file and its associated reference trace file

along with a suggestion on diff parameters and options in order to see what 

@c ========================================================================

@c Running a Script

@c ========================================================================

@node Running a Script

@section Running a Script

@cindex running a script with Waf

We typically run scripts under the control of Waf.  This allows the build 

system to ensure that the shared library paths are set correctly and that

the libraries are available at run time.  To run a program, simply use the

@code{--run} option in Waf.  Let's run the @command{ns-3} equivalent of the

ubiquitous hello world program by typing the following:

@verbatim

  ./waf --run hello-simulator

@end verbatim

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

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

produces the following output.

@verbatim

  Hello Simulator

@end verbatim

@emph{Congratulations.  You are now an ns-3 user.}

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

see this @uref{http://www.nsnam.org/wiki/index.php/User_FAQ#How_to_run_NS-3_programs_under_another_tool,,wiki entry}.