.. include:: replace.txt

Getting Started

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

Downloading ns-3

****************

The |ns3| 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, a text

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

present on your system before proceeding.  |ns3| provides a wiki

One such page is the "Installation" page,

http://www.nsnam.org/wiki/index.php/Installation.

The "Prerequisites" section of this wiki page explains which packages are 

required to support common |ns3| 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 |ns3| wiki 

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

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.

The |ns3| code is available in Mercurial repositories on the server

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

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.

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

``ns-3-allinone`` environment.  This is a set of scripts that manages the 

downloading and building of various subsystems of |ns3| for you.  We 

Downloading ns-3 Using Mercurial

++++++++++++++++++++++++++++++++

One practice is to create a directory called ``repos`` in one's home 

directory under which one can keep local Mercurial repositories.  

*Hint:  we will assume you do this later in the tutorial.*  If you adopt

that approach, you can get a copy of ``ns-3-allinone`` by typing the 

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

::

  cd

  mkdir repos

  cd repos

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

following displayed,

::

  requesting all changes

  adding changesets

  adding manifests

  adding file changes

  updating to branch default

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

look something like the following:

::

will be to use those scripts to download and build the |ns3|

distribution of your choice.

If you go to the following link: http://code.nsnam.org/,

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

the |ns3| development team.  The repositories of interest to you will

be prefixed with "ns-3".  Official releases of |ns3| will be 

numbered as ``ns-3.<release>.<hotfix>``.  For example, a second hotfix to a

still hypothetical release forty two of |ns3| would be numbered as

``ns-3.42.2``.

The current development snapshot (unreleased) of |ns3| may be found 

at http://code.nsnam.org/ns-3-dev/.  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.

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

text below.  You can find the latest version  of the

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

`"ns-3 Releases"

<http://www.nsnam.org/releases>`_

web page and clicking on the latest release link.

Go ahead and change into the ``ns-3-allinone`` directory you created when

::

::

::

::

::

::

You are now ready to build the |ns3| distribution.

Building ns-3

*************

Building with build.py

++++++++++++++++++++++

``allinone`` directory.  This program is called ``build.py``.  This 

program will get the project configured for you

in the most commonly useful way.  However, please note that more advanced

configuration and work with |ns3| will typically involve using the

native |ns3| build system, Waf, to be introduced later in this tutorial.  

using a tarball you should have a directory called something like 

Type the following:

::

  ./build.py --enable-examples --enable-tests

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

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

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

building all available modules.  Later, you can build

|ns3| without examples and tests, or eliminate the modules that

are not necessary for your work, if you wish.

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:

::

::

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

This just means that some ns-3 modules that have dependencies on

outside libraries may not have been built, or that the configuration

specifically asked not to build them.  It does not mean that the 

simulator did not build successfully or that it will provide wrong 

results for the modules listed as being built.

::

Building with Waf

+++++++++++++++++

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 

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

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

following commands,

::

  ./waf clean

  ./waf -d optimized --enable-examples --enable-tests configure

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

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

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

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

When the project is reconfigured and the build system checks for various 

dependencies, you should see

output that looks similar to the following,

::

  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 tests                   : enabled

  Build examples                : enabled

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

  'configure' finished successfully (2.870s)

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 |ns3| feature 

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

a feature to use the program ``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 that includes the examples and tests.

::

  ./waf clean

  ./waf -d debug --enable-examples --enable-tests configure

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

the |ns3| programs by simply typing

::

  ./waf

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

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

Here are a few more introductory tips about Waf.

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 |ns3|, 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 that also includes the examples and tests

::

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:

::

  ./waf --help

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

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

project in 

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

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

::

This allows users to work with multiple builds rather than always

overwriting the last build.

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

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

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

::

  CXX="clang++" ./waf configure

  ./waf build