297 lines
11 KiB
Plaintext
297 lines
11 KiB
Plaintext
|
|
@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
|
|
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.
|
|
|
|
@cindex Mercurial
|
|
@cindex Waf
|
|
We are 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, but we recommend working with
|
|
Mercurial --- it will make your life easier in the long run.
|
|
|
|
@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 @comamnd{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 requred 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.
|
|
|
|
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.1) 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 any of the development versions 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 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
|
|
|
|
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
|
|
~/repos/ns-3-dev >./waf -d debug configure
|
|
Checking for program g++ : ok /usr/bin/g++
|
|
Checking for compiler version : ok Version 4.1.2
|
|
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 header stdlib.h : ok
|
|
Checking for header stdlib.h : ok
|
|
Checking for header signal.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 package goocanvas gthread-2.0 : not found
|
|
Checking for program diff : ok /usr/bin/diff
|
|
Configuration finished successfully; project is now ready to build.
|
|
~/repos/ns-3-dev >
|
|
@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 check
|
|
@end verbatim
|
|
|
|
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
|
|
|
|
@cindex regression tests
|
|
This command is typically run by @code{users} to quickly verify that an
|
|
@command{ns-3} distribution has built correctly.
|
|
|
|
You can also run @code{regression tests} to ensure that your distribution and
|
|
tool chain have produced binaries that generate trace files which are
|
|
compatible with reference trace files stored in a central location. To run the
|
|
regression tests you run 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 @code{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.
|
|
|
|
Once the reference traces are downloaded to your local machine, Waf will run
|
|
a number of tests that generate 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.
|
|
http://code.nsnam.org/ns-3-dev-ref-traces
|
|
Done.
|
|
PASS test-csma-broadcast
|
|
PASS test-csma-multicast
|
|
PASS test-csma-one-subnet
|
|
PASS test-csma-packet-socket
|
|
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
|
|
~/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 how to run diff in order to see what has gone awry.
|
|
|
|
@c ========================================================================
|
|
@c Testing ns-3
|
|
@c ========================================================================
|
|
|
|
@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
|
|
|
|
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}.
|
|
|
|
@emph{Congratulations. You are now an ns-3 user.}
|