@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 download a tarball release at
@uref{http://www.nsnam.org/releases/}, or you can work with repositories
using Mercurial.
@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 required 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
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.2) 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.
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
Similarly, if working from a released version instead, you can simply
@verbatim
cd
mkdir repos
wget http://www.nsnam.org/releases/ns-3.2.tar.bz2
bunzip2 ns-3.2.tar.bz2
tar xvf ns-3.2.tar
@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
Checking for program g++ : ok /usr/bin/g++
Checking for compiler version : ok Version 4.0.1
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 compiler could create programs : ok
Checking for compiler could create shared libs : ok
Checking for compiler could create static libs : ok
Checking for flags -O2 -DNDEBUG : ok
Checking for flags -g -DDEBUG : ok
Checking for flags -g3 -O0 -DDEBUG : ok
Checking for flags -Wall : ok
Checking for g++ : ok
Checking for -Wno-error=deprecated-declarations compilation flag support : no
Checking for header stdlib.h : ok
Checking for header stdlib.h : ok
Checking for header signal.h : ok
Checking for library rt : not found
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 package gtk+-2.0 >= 2.12 : not found
Checking for library sqlite3 : ok
Checking for package goocanvas gthread-2.0 : not found
Checking for program python : ok /usr/local/bin/python
Checking for Python version >= 2.3 : ok 2.4.3
Checking for library python2.4 : not found
Checking for library python2.4 : not found
Checking for library python24 : not found
Checking for program python2.4-config : not found
Checking for header Python.h : not found
Checking for program diff : ok /usr/bin/diff
Checking for program hg : ok /opt/local/bin/hg
---- Summary of optional NS-3 features:
Threading Primitives : enabled
Real Time Simulator : enabled
GtkConfigStore : not enabled (library 'gtk+-2.0 >= 2.12' not found)
SQlite stats data output : enabled
Network Simulation Cradle : not enabled (--enable-nsc configure option not given)
Python Bindings : not enabled (Python development headers not found.)
Configuration finished successfully; project is now ready to build.
@end verbatim
Note the trailing portion of the above output. Some ns-3 options are
not enabled by default or require support from the underlying system.
For instance, to enable Python bindings, Python development headers must
be installed on the host machine, and they were not found in the above
example, so Python scripting will not be supported in the resulting build.
For this tutorial, we will focus on the non-optional pieces of ns-3.
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
(Hint: if you have a multicore machine, use the "-j JOBS" option to speed
up your build, where JOBS is the number of cores)
You will see many Waf status messages displayed as the system compiles. The
most important is the last one:
@verbatim
Compilation finished successfully
@end verbatim
@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
~/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.
@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
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
know what you are doing. (Warning: The ns-3.2 release requires you
to be online when you run regression tests because it synchronizes the
trace directory with an online repository).
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'
Compilation finished successfully
========== Running Regression Tests ==========
Synchronizing reference traces using Mercurial.
Pulling http://code.nsnam.org/ns-3-dev-ref-traces from repo.
Skipping csma-bridge: Python bindings not available.
SKIP test-csma-bridge
PASS test-csma-broadcast
PASS test-csma-multicast
PASS test-csma-one-subnet
PASS test-csma-packet-socket
PASS test-realtime-udp-echo
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
PASS test-wifi-wired-bridging
~/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
has gone awry. Python regression tests will be SKIPped if Python bindings
are not built.
@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}.