@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

code.nsnam.org.  You can also download a tarball release at

@uref{http://www.nsnam.org/releases/}, or you can work with repositories

using Mercurial.  We recommend using Mercurial unless there's a good reason

not to.  See the end of this section for instructions on how to get a tarball

release.

@cindex repository

The simplest way to get started using Mercurial repositories is to use the

@code{ns-3-allinone} environment.  This is a set of scripts that manages the 

downloading and building of various subystems of @command{ns-3} for you.  We 

recommend that you begin your @command{ns-3} adventures in this environment

as it can really simplify your life at this point.

@subsection Downloading ns-3 Using Mercurial

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 @code{ns-3-allinone} by typing the 

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

@verbatim

  cd

  mkdir repos

  cd repos

  hg clone http://code.nsnam.org/ns-3-allinone

@end verbatim

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

following displayed,

@verbatim

  destination directory: ns-3-allinone

  requesting all changes

  adding changesets

  adding manifests

  adding file changes

  added 26 changesets with 40 changes to 7 files

  7 files updated, 0 files merged, 0 files removed, 0 files unresolved

@end verbatim

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

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

look something like the following:

@verbatim

  build.py*  constants.py  dist.py*  download.py*  README  util.py

@end verbatim

Notice that you really just downloaded some Python scripts.  The next step

will be to use those scripts to download and build the @command{ns-3}

distribution of your choice.

@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''.  Official releases of @command{ns-3} will be 

numbered as @code{ns-3.<release>.<hotfix>}.  For example, a second hotfix to a

still hypothetical release nine of @command{ns-3} would be numbered as

@code{ns-3.9.2}.

We have had a regression testing framework in place since the first release.

For each release, a set of output files that define ``good behavior'' are saved.

These known good output files are called reference traces and are associated 

with a given release by name.  For example, in @uref{http://code.nsnam.org/}

you will find a repository named @code{ns-3.1} which is the first stable release

of @command{ns-3}.  You will also find a separate repository named 

@code{ns-3.1-ref-traces} that holds the reference traces for the @code{ns-3.1}

release.  It is crucial to keep these files consistent if you want to do any

regression testing of your repository.  This is a good idea to do at least once

to verify everything has built correctly.

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

at @uref{http://code.nsnam.org/ns-3-dev/} and the associated reference traces

may be found at @uref{http://code.nsnam.org/ns-3-dev-ref-traces/}.  The 

developers attempt to keep these repository in consistent, working states but

they are in a development area with unreleased code present, so you may want 

to consider staying with an official release if you do not need newly-

introduced features.

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 

string ``ns-3-dev'' with your choice of release (e.g., ns-3.4 and 

ns-3.4-ref-traces) in the text 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.

Go ahead and change into the @code{ns-3-allinone} directory you created when

you cloned that repository.  We are now going to use the @code{download.py} 

script to pull down the various pieces of @command{ns-3} you will be using/

Go ahead and type the following into your shell (remember you can substitute

the name of your chosen release number instead of @code{ns-3-dev} -- like

@code{"ns-3.4"} and @code{"ns-3.4-ref-traces"} if you want to work with a 

stable release).

@verbatim

  ./download.py -n ns-3-dev -r ns-3-dev-ref-traces

@end verbatim

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

following,

@verbatim

      #

      # Get NS-3

      #

  Cloning ns-3 branch

   =>  hg clone http://code.nsnam.org/ns-3-dev ns-3-dev

  requesting all changes

  adding changesets

  adding manifests

  adding file changes

  added 4292 changesets with 15368 changes to 1671 files

  823 files updated, 0 files merged, 0 files removed, 0 files unresolved

@end verbatim

This is output by the download script as it fetches the actual @code{ns-3}

code from the repository.  Next, you should see something like,

@verbatim

      #

      # Get the regression traces

      #

  Synchronizing reference traces using Mercurial.

   =>  hg clone http://code.nsnam.org/ns-3-dev-ref-traces ns-3-dev-ref-traces

  requesting all changes

  adding changesets

  adding manifests

  adding file changes

  added 79 changesets with 1102 changes to 222 files

  206 files updated, 0 files merged, 0 files removed, 0 files unresolved

@end verbatim

This is the download script fetching the reference trace files for you.

The download script is smart enough to know that on some platforms various

pieces of ns-3 are not supported.  On your platform you may not see some

of these pieces come down.  However, on most platforms, the process should

continue with something like,

@verbatim

      #

      # Get PyBindGen

      #

  Required pybindgen version:  0.10.0.630

  Trying to fetch pybindgen; this will fail if no network connection is available.  Hit Ctrl-C to skip.

   =>  bzr checkout -rrevno:630 https://launchpad.net/pybindgen pybindgen

  Fetch was successful.

@end verbatim

This was the download script getting the Python bindings generator for you.

Next you should see (modulo platform variations) something along the lines of,

@verbatim

      #

      # Get NSC

      #

  Required NSC version:  nsc-0.5.0

  Retrieving nsc from https://secure.wand.net.nz/mercurial/nsc

   =>  hg clone https://secure.wand.net.nz/mercurial/nsc nsc

  requesting all changes

  adding changesets

  adding manifests

  adding file changes

  added 270 changesets with 17375 changes to 14991 files

  10614 files updated, 0 files merged, 0 files removed, 0 files unresolved 

@end verbatim

This part of the process is the script downloading the Network Simulation

Cradle for you.

After the clone command completes, you should have several new directories

under @code{~/repos/ns-3-allinone}:

@verbatim

  build.py*     constants.pyc  download.py*  ns-3-dev-ref-traces/  pybindgen/  util.py

  constants.py  dist.py*       ns-3-dev/     nsc/                  README      util.pyc

@end verbatim

Go ahead and change into @code{ns-3-dev} under your @code{~/repos/ns-3-allinone} 

directory.  You should see something like the following there:

@verbatim

  AUTHORS       examples/  regression/    scratch/  waf*

  bindings/     LICENSE    regression.py  src/      waf.bat*

  CHANGES.html  ns3/       RELEASE_NOTES  utils/    wscript

  doc/          README     samples/       VERSION   wutils.py

@end verbatim

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

@subsection Downloading ns-3 Using a Tarball

The process for downloading @command{ns-3} via tarball is simpler than the

Mercurial process since all of the pieces are pre-packaged for you.  You just

have to pick a release, download it and decompress it.

As mentioned above, one practice is to create a directory called @code{repos}

in one's home directory under which one can keep local Mercurial repositories.

One could also keep a @code{tarballs} directory.  @emph{Hint:  the tutorial

will assume you downloaded into a @code{repos} directory, so remember the

placekeeper.}  If you adopt the @code{tarballs} directory approach, you can 

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

(substitute the appropriate version numbers, of course):

@verbatim

  cd

  mkdir tarballs

  cd tarballs

  wget http://www.nsnam.org/releases/ns-allinone-3.4.tar.bz2

  bunzip2 ns-allinone-3.4.tar.bz2

  tar xf ns-3.4.tar

@end verbatim 

If you change into the directory @code{ns-allinone-3.4} you should see a

number of files:

@verbatim

build.py*     ns-3.4-RC2/             nsc-0.5.0/             util.py

constants.py  ns-3.4-RC2-ref-traces/  pybindgen-0.10.0.630/

@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

@subsection Building with build.py

@cindex building with build.py

The first time you build the @command{ns-3} project you should build using the

@command{allinone} environment.  This will get the project configured for you

in the most commonly useful way.

Change into the directory you created in the download section above.  If you

downloaded using Mercurial you should have a directory called 

@code{ns-3-allinone} under your @code{~/repos} directory.  If you downloaded

using a tarball you should have a directory called something like 

@code{ns-3-allinone-3.4} under your @code{~/tarballs} directory.  Take a deep

breath and type the following:

@verbatim

  ./build.py

@end verbatim

You will see lots of typical compiler output messages displayed as the build

script builds the various pieces you downloaded.  Eventually you should see the

following magic words:

@verbatim

  Build finished successfully (00:02:37)

  Leaving directory `./ns-3-dev'

@end verbatim

Once the project has built you can say goodbye to your old friends, the 

@code{ns-3-allinone} scripts.  You got what you needed from them and will now 

interact directly with Waf and we do it in the @code{ns-3-dev} directory and

not in the @code{ns-3-allinone} directory.  Go ahead and change into the 

@code{ns-3-dev} directory (or the directory for the appropriate release you

downloaded.

@verbatim

  cd ns-3-dev

@end verbatim

@subsection Building with Waf

@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 configure and build the @command{ns-3} project.  It's not 

strictly required at this point, but it will be valuable to take a slight

detour and look at how to make changes to the configuration of the project.

Probably the most useful configuration change you can make will be to 

build the optimized version of the code.  By default you have configured

your project to build the debug version.  Let's tell the project to do

make an optimized build.  To explain to Waf that it should do optimized

builds you will need to execute the following command,

@verbatim

  ./waf -d optimized 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

Checking for program g++                 : ok /usr/bin/g++

Checking for program cpp                 : ok /usr/bin/cpp

Checking for program ar                  : ok /usr/bin/ar

Checking for program ranlib              : ok /usr/bin/ranlib

Checking for g++                         : ok

Checking for program pkg-config          : ok /usr/bin/pkg-config

Checking for regression reference traces  : ok ../ns-3-dev-ref-traces (guessed)

Checking for -Wno-error=deprecated-declarations support : yes

Checking for header stdlib.h                            : ok

Checking for header signal.h                            : ok

Checking for header pthread.h                           : ok

Checking for high precision time implementation         : 128-bit integer

Checking for header stdint.h                            : ok

Checking for header inttypes.h                          : ok

Checking for header sys/inttypes.h                      : not found

Checking for library rt                                 : ok

Checking for header netpacket/packet.h                  : ok

Checking for header linux/if_tun.h                      : ok

Checking for pkg-config flags for GTK_CONFIG_STORE      : ok

Package libxml-2.0 was not found in the pkg-config search path.

Perhaps you should add the directory containing `libxml-2.0.pc'

to the PKG_CONFIG_PATH environment variable

No package 'libxml-2.0' found

Checking for pkg-config flags for LIBXML2               : not found

Checking for library sqlite3                            : ok

Checking for NSC location                               : ok ../nsc (guessed)

Checking for library dl                                 : ok

Checking for NSC supported architecture x86_64          : ok

Package goocanvas was not found in the pkg-config search path.

Perhaps you should add the directory containing `goocanvas.pc'

to the PKG_CONFIG_PATH environment variable

No package 'goocanvas' found

Checking for pkg-config flags for MOBILITY_VISUALIZER   : not found

Checking for program python                             : ok /usr/bin/python

Checking for Python version >= 2.3                      : ok 2.5.2

Checking for library python2.5                          : ok

Checking for program python2.5-config                   : ok /usr/bin/python2.5-config

Checking for header Python.h                            : ok

Checking for -fvisibility=hidden support                : yes

Checking for pybindgen location                         : ok ../pybindgen (guessed)

Checking for Python module pybindgen                    : ok

Checking for pybindgen version                          : ok 0.10.0.630

Checking for Python module pygccxml                     : ok

Checking for pygccxml version                           : ok 0.9.5

Checking for program gccxml                             : ok /usr/local/bin/gccxml

Checking for gccxml version                             : ok 0.9.0

Checking for program sudo                               : ok /usr/bin/sudo

Checking for program hg                                 : ok /usr/bin/hg

Checking for program valgrind                           : ok /usr/bin/valgrind

---- Summary of optional NS-3 features:

Threading Primitives          : enabled

Real Time Simulator           : enabled

Emulated Net Device           : enabled

Tap Bridge                    : enabled

GtkConfigStore                : enabled

XmlIo                         : not enabled (library 'libxml-2.0 >= 2.7' not found)

SQlite stats data output      : enabled

Network Simulation Cradle     : enabled

Python Bindings               : enabled

Python API Scanning Support   : enabled

Use sudo to set suid bit      : not enabled (option --enable-sudo not selected)

Configuration finished successfully (00:00:02); project is now ready to build.

@end verbatim

Note the last part of the above output.  Some ns-3 options are not enabled by

default or require support from the underlying system to work properly

For instance, to enable XmlTo, the library libxml-2.0 must be found on the

system.  in the example above, this library was not found and the corresponding

feature was not enabled.  There is a feature to use sudo to set the suid bit of

certain programs.  This was not enabled by default.

@verbatim

  ./waf -d debug configure

@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

Okay, sorry, I made you build the @command{ns-3} part of the system twice,

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

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

@c Testing ns-3

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

@node Testing ns-3

@section Testing ns-3

@cindex unit tests

You can run the unit tests of the @command{ns-3} distribution by running the 

``check'' command,

@verbatim

  ./waf check

@end verbatim

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

test has passed.

@verbatim

  Entering directory `repos/ns-3-allinone/ns-3-dev/build'

  Build finished successfully (00:00:00)

  -- Running NS-3 C++ core unit tests...

  PASS AddressHelper

  PASS Wifi

  PASS DcfManager

  ...

  PASS Object

  PASS Ptr

  PASS Callback

  -- Running NS-3 Python bindings unit tests...

  ...........

  ----------------------------------------------------------------------

  Ran 11 tests in 0.003s

  OK

@end verbatim

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

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

@cindex regression tests

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

known-good reference output files.  You downloaded these reference traces to 

your machine during the download process above.  (Warning:  The @code{ns-3.2} 

and @code{ns-3.3} releases do not use the @code{ns-3-allinone} environment

and require you to be online when you run regression tests because they