@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.
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
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
dynamically synchronize the reference traces directory with an online
repository immediately prior to the run).
During regression testing 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. If they are identical, the regression tests report a PASS
status. If a regression test 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
has gone awry. If the error was discovered in a pcap file, it will be useful
to convert the pcap files to text using tcpdump prior to comparison.
Some regression tests wmay be SKIPped if the required support
is not present.
To run the regression tests, you provide Waf with the regression flag.
@verbatim
./waf --regression
@end verbatim
You should see messages indicating that many tests are being run and are
passing.
@verbatim
Entering directory `repos/ns-3-allinone/ns-3-dev/build'
[647/669] regression-test (test-csma-bridge)
[648/669] regression-test (test-csma-broadcast)
[649/669] regression-test (test-csma-multicast)
[650/669] regression-test (test-csma-one-subnet)
PASS test-csma-multicast
[651/669] regression-test (test-csma-packet-socket)
PASS test-csma-bridge
...
Regression testing summary:
PASS: 22 of 22 tests passed
Build finished successfully (00:00:23)
@end verbatim
If you want to take a look at an example of what might be checked during
a regression test, you can do the following:
@verbatim
cd build/debug/regression/traces/second.ref
tcpdump -nn -tt -r second-1-1.pcap
@end verbatim
The output should be clear to anyone who is familiar with tcpdump or net
sniffers. We'll have much more to say on pcap files later in this tutorial.
Remember to cd back into the top-level @command{ns-3} directory
after you are done:
@verbatim
cd ../../../../..
@end verbatim
@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}.