@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 Prerequisites

@cindex Dependencies

The @command{ns-3} system as a whole is a fairly complex system and has a

number of dependencies on other components.  Along with the systems you will

most likely deal with every day (the GNU toolchain, Mercurial, you programmer

editor) you will need to ensure that a number of additional libraries are

present on your system before proceeding.  @command{ns-3} provides a wiki

for your reading pleasure that includes pages with many useful hints and tips.

One such page is the ``Installation'' page,

@uref{http://www.nsnam.org/wiki/index.php/Installation}.

The ``Prerequisites'' section of this wiki page explains which packages are 

required to support common @command{ns-3} options, and also provides the 

commands used to install them for common Linux variants.  Cygwin users will

have to use the Cygwin installer (if you are a Cygwin user, you used it to

install Cygwin). 

You may want to take this opportunity to explore the @command{ns-3} wiki 

a bit since there really is a wealth of information there. 

@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 along with the prerequisites mentioned 

above.  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

@uref{http://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 subsystems 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 31 changesets with 45 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}.

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

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 

code either by inspection of the repository list or by going to the 

@uref{http://www.nsnam.org/getting_started.html,,``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

stable release).

@verbatim

@end verbatim

above is actually redundant.  We provide this example to illustrate how to

specify alternate repositories.  In order to download @code{ns-3-dev} you 

can actually use the defaults and simply type,

@verbatim

  ./download.py

@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 4634 changesets with 16500 changes to 1762 files

  870 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}

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.640

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

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

  Fetch was successful.

@end verbatim

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

Note that you will need bazaar (bzr), a version control system, to download 

PyBindGen. 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 273 changesets with 17565 changes to 15175 files

  10622 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. Note that NSC is not supported on OSX or Cygwin and works 

best with gcc-3.4 or gcc-4.2 or greater series.

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

@verbatim

@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

@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.6.tar.bz2

  tar xjf ns-allinone-3.6.tar.bz2

@end verbatim 

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

number of files:

@verbatim

@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-allinone-3.6} 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

  Waf: Leaving directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build'

  'build' finished successfully (2m30.586s)

@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,

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

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 -Wno-error=deprecated-declarations support : yes

  Checking for -Wl,--soname=foo 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 pkg-config flags for GSL                   : ok

  Checking for header linux/if_tun.h                      : ok

  Checking for pkg-config flags for GTK_CONFIG_STORE      : ok

  Checking for pkg-config flags for LIBXML2               : ok

  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

  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.640

  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

  GNU Scientific Library (GSL)  : enabled

  Tap Bridge                    : enabled

  GtkConfigStore                : enabled

  XmlIo                         : enabled

  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)

  Build examples and samples    : enabled

  Static build                  : not enabled (option --enable-static not selected)

  'configure' finished successfully (2.870s)

@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.  If this library were not found, the corresponding @command{ns-3} feature 

would not be enabled and a message would be displayed.  Note further that there is 

a feature to use the program @code{sudo} to set the suid bit of certain programs.

This is not enabled by default and so this feature is reported as ``not enabled.''

Now go ahead and switch back to the debug build.

@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

Some waf commands are meaningful during the build phase and some commands are valid

in the configuration phase.  For example, if you wanted to use the emulation 

features of @command{ns-3} you might want to enable setting the suid bit using

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

you could reconfigure using the following command

@verbatim

  ./waf -d debug --enable-sudo configure

@end verbatim

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

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

available in waf.  To explore these options, type:

@verbatim

  ./waf --help

@end verbatim

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

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 

``./test.py -c core'' script,

@verbatim

  ./test.py -c core

@end verbatim

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

see a report saying that,

@verbatim

  47 of 47 tests passed (47 passed, 0 failed, 0 crashed, 0 valgrind errors)

@end verbatim

This is the important message.

You will also see output from the test runner and the output will actually look something like,

@verbatim

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

  Waf: Leaving directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build'

  'build' finished successfully (1.799s)

  PASS: TestSuite ns3-wifi-interference

  PASS: TestSuite histogram

  PASS: TestSuite sample

  PASS: TestSuite ipv4-address-helper

  PASS: TestSuite devices-wifi

  PASS: TestSuite propagation-loss-model

  ...

  PASS: TestSuite attributes

  PASS: TestSuite config

  PASS: TestSuite global-value