unison/doc/tutorial/getting-started.texi

@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.}