freshen tutorial ns-3.2-RC3
authorTom Henderson <tomh@tomh.org>
Mon, 15 Sep 2008 21:37:40 -0700
changeset 3700fa1c7b813873
parent 3699 29473501ade8
child 3701 6105fe16df43
freshen tutorial
doc/tutorial/building-topologies.texi
doc/tutorial/conceptual-overview.texi
doc/tutorial/getting-started.texi
doc/tutorial/introduction.texi
     1.1 --- a/doc/tutorial/building-topologies.texi	Mon Sep 15 06:11:38 2008 -0700
     1.2 +++ b/doc/tutorial/building-topologies.texi	Mon Sep 15 21:37:40 2008 -0700
     1.3 @@ -812,7 +812,7 @@
     1.4  documentation.
     1.5  
     1.6  Now we will return to more familiar ground.  We next create a @code{WifiHelper}
     1.7 -object and set two default atributes that it will use when creating the actual
     1.8 +object and set two default attributes that it will use when creating the actual
     1.9  devices.
    1.10  
    1.11  @verbatim
    1.12 @@ -1240,12 +1240,13 @@
    1.13  @end verbatim
    1.14  
    1.15  If you are feeling brave, there is a list of all trace sources in the 
    1.16 -@command{ns-3} Doxygen which you can find in the ``NS-3 Modules'' section.  
    1.17 +@uref{http://www.nsnam.org/doxygen-release/index.html,,ns-3 Doxygen}
    1.18 +which you can find in the ``Modules'' tab.
    1.19  Under the ``core'' section, you will find a link to ``The list of all trace 
    1.20  sources.''  You may find it interesting to try and hook some of these 
    1.21 -traces yourself.  Additionally in the ``NS-3 Modules'' documentation, there is
    1.22 +traces yourself.  Additionally in the ``Modules'' documentation, there is
    1.23  a link to ``The list of all attributes.''  You can set the default value of 
    1.24 -any of these atributes via the command line as we have previously discussed.
    1.25 +any of these attributes via the command line as we have previously discussed.
    1.26  
    1.27  We have just scratched the surface of @command{ns-3} in this tutorial, but we 
    1.28  hope we have covered enough to get you started doing useful work.
     2.1 --- a/doc/tutorial/conceptual-overview.texi	Mon Sep 15 06:11:38 2008 -0700
     2.2 +++ b/doc/tutorial/conceptual-overview.texi	Mon Sep 15 21:37:40 2008 -0700
     2.3 @@ -731,10 +731,13 @@
     2.4  @verbatim
     2.5    ~/repos/ns-3-dev > ./waf
     2.6    Entering directory `/home/craigdo/repos/ns-3-dev/build'
     2.7 -  [432/477] cxx: scratch/first.cc -> build/debug/scratch/first_2.o
     2.8 -  [475/477] cxx_link: build/debug/scratch/first_2.o ...
     2.9 -  Compilation finished successfully
    2.10 -~/repos/ns-3-dev >
    2.11 +  [467/511] cxx: scratch/first.cc -> build/debug/scratch/first_1.o
    2.12 +  [468/511] cxx: scratch/multiple-sources/simple-main.cc -> build/debug/scratch/multiple-sources/simple-main_2.o
    2.13 +  [469/511] cxx: scratch/multiple-sources/simple-simulation.cc -> build/debug/scratch/multiple-sources/simple-simulation_2.o
    2.14 +  [470/511] cxx: scratch/simple.cc -> build/debug/scratch/simple_3.o
    2.15 +  [508/511] cxx_link: build/debug/scratch/first_1.o -> build/debug/scratch/first
    2.16 +  Compilation finished successfully 
    2.17 +  ~/repos/ns-3-dev >
    2.18  @end verbatim
    2.19  
    2.20  You can now run the example (note that if you build your program in the scratch
     3.1 --- a/doc/tutorial/getting-started.texi	Mon Sep 15 06:11:38 2008 -0700
     3.2 +++ b/doc/tutorial/getting-started.texi	Mon Sep 15 21:37:40 2008 -0700
     3.3 @@ -44,8 +44,9 @@
     3.4  
     3.5  @cindex tarball
     3.6  The @command{ns-3} code is available in Mercurial repositories on the server
     3.7 -code.nsnam.org.  You can download a tarball, but we recommend working with
     3.8 -Mercurial --- it will make your life easier in the long run.
     3.9 +code.nsnam.org.  You can download a tarball release at
    3.10 +@uref{http://www.nsnam.org/releases/}, or you can work with repositories
    3.11 +using Mercurial.
    3.12  
    3.13  @cindex repository
    3.14  If you go to the following link: @uref{http://code.nsnam.org/},
    3.15 @@ -62,11 +63,11 @@
    3.16  at:  @uref{http://code.nsnam.org/ns-3-dev/}.  The developers attempt to keep
    3.17  this repository in a consistent, working state but it is a development area 
    3.18  with unreleased code present, so you may want to consider staying with an 
    3.19 -official release.
    3.20 +official release if you do not need newly-introduced features.
    3.21  
    3.22  Since the release numbers are going to be changing, I will stick with 
    3.23  the more constant ns-3-dev here in the tutorial, but you can replace the 
    3.24 -string ``ns-3-dev'' with your choice of release (e.g., ns-3.1) in the text 
    3.25 +string ``ns-3-dev'' with your choice of release (e.g., ns-3.2) in the text 
    3.26  below.  You can find the latest version  of the code either by inspection of 
    3.27  the repository list or by going to the ``Getting Started'' web page and 
    3.28  looking for the latest release identifier.
    3.29 @@ -108,6 +109,15 @@
    3.30    doc/     ns3/       RELEASE_NOTES  src/      waf*
    3.31  @end verbatim
    3.32  
    3.33 +Similarly, if working from a released version instead, you can simply
    3.34 +@verbatim
    3.35 +  cd
    3.36 +  mkdir repos
    3.37 +  wget http://www.nsnam.org/releases/ns-3.2.tar.bz2
    3.38 +  bunzip2 ns-3.2.tar.bz2
    3.39 +  tar xvf ns-3.2.tar
    3.40 +@end verbatim 
    3.41 +
    3.42  You are now ready to build the @command{ns-3} distribution.
    3.43  
    3.44  @c ========================================================================
    3.45 @@ -137,34 +147,58 @@
    3.46  output that looks similar to the following,
    3.47  
    3.48  @verbatim
    3.49 -  ~/repos/ns-3-dev >./waf -d debug configure
    3.50 -  Checking for program g++                 : ok /usr/bin/g++
    3.51 -  Checking for compiler version            : ok Version 4.1.2
    3.52 -  Checking for program cpp                 : ok /usr/bin/cpp
    3.53 -  Checking for program ar                  : ok /usr/bin/ar
    3.54 -  Checking for program ranlib              : ok /usr/bin/ranlib
    3.55 -  Checking for compiler could create programs : ok
    3.56 -  Checking for compiler could create shared libs : ok
    3.57 -  Checking for compiler could create static libs : ok
    3.58 -  Checking for flags -O2 -DNDEBUG                : ok
    3.59 -  Checking for flags -g -DDEBUG                  : ok
    3.60 -  Checking for flags -g3 -O0 -DDEBUG             : ok
    3.61 -  Checking for flags -Wall                       : ok
    3.62 -  Checking for g++                               : ok
    3.63 -  Checking for header stdlib.h                   : ok
    3.64 -  Checking for header stdlib.h                   : ok
    3.65 -  Checking for header signal.h                   : ok
    3.66 -  Checking for high precision time implementation : 128-bit integer
    3.67 -  Checking for header stdint.h                    : ok
    3.68 -  Checking for header inttypes.h                  : ok
    3.69 -  Checking for header sys/inttypes.h              : not found
    3.70 -  Checking for package gtk+-2.0 >= 2.12           : not found
    3.71 -  Checking for package goocanvas gthread-2.0      : not found
    3.72 -  Checking for program diff                       : ok /usr/bin/diff
    3.73 -  Configuration finished successfully; project is now ready to build.
    3.74 -  ~/repos/ns-3-dev >
    3.75 +Checking for program g++                 : ok /usr/bin/g++ 
    3.76 +Checking for compiler version            : ok Version 4.0.1 
    3.77 +Checking for program cpp                 : ok /usr/bin/cpp 
    3.78 +Checking for program ar                  : ok /usr/bin/ar 
    3.79 +Checking for program ranlib              : ok /usr/bin/ranlib 
    3.80 +Checking for compiler could create programs : ok  
    3.81 +Checking for compiler could create shared libs : ok  
    3.82 +Checking for compiler could create static libs : ok  
    3.83 +Checking for flags -O2 -DNDEBUG                : ok  
    3.84 +Checking for flags -g -DDEBUG                  : ok  
    3.85 +Checking for flags -g3 -O0 -DDEBUG             : ok  
    3.86 +Checking for flags -Wall                       : ok  
    3.87 +Checking for g++                               : ok  
    3.88 +Checking for -Wno-error=deprecated-declarations compilation flag support : no 
    3.89 +Checking for header stdlib.h                   : ok  
    3.90 +Checking for header stdlib.h                   : ok  
    3.91 +Checking for header signal.h                   : ok  
    3.92 +Checking for library rt                        : not found 
    3.93 +Checking for header pthread.h                  : ok  
    3.94 +Checking for high precision time implementation: 128-bit integer 
    3.95 +Checking for header stdint.h                   : ok  
    3.96 +Checking for header inttypes.h                 : ok  
    3.97 +Checking for header sys/inttypes.h             : not found 
    3.98 +Checking for package gtk+-2.0 >= 2.12          : not found 
    3.99 +Checking for library sqlite3                   : ok  
   3.100 +Checking for package goocanvas gthread-2.0     : not found 
   3.101 +Checking for program python                    : ok /usr/local/bin/python 
   3.102 +Checking for Python version >= 2.3             : ok 2.4.3 
   3.103 +Checking for library python2.4                 : not found 
   3.104 +Checking for library python2.4                 : not found 
   3.105 +Checking for library python24                  : not found 
   3.106 +Checking for program python2.4-config          : not found 
   3.107 +Checking for header Python.h                   : not found 
   3.108 +Checking for program diff                      : ok /usr/bin/diff 
   3.109 +Checking for program hg                        : ok /opt/local/bin/hg 
   3.110 +---- Summary of optional NS-3 features:
   3.111 +Threading Primitives        : enabled
   3.112 +Real Time Simulator         : enabled
   3.113 +GtkConfigStore              : not enabled (library 'gtk+-2.0 >= 2.12' not found)
   3.114 +SQlite stats data output    : enabled
   3.115 +Network Simulation Cradle   : not enabled (--enable-nsc configure option not given)
   3.116 +Python Bindings             : not enabled (Python development headers not found.)
   3.117 +Configuration finished successfully; project is now ready to build. 
   3.118  @end verbatim
   3.119  
   3.120 +Note the trailing portion of the above output.  Some ns-3 options are
   3.121 +not enabled by default or require support from the underlying system.
   3.122 +For instance, to enable Python bindings, Python development headers must
   3.123 +be installed on the host machine, and they were not found in the above
   3.124 +example, so Python scripting will not be supported in the resulting build.
   3.125 +For this tutorial, we will focus on the non-optional pieces of ns-3.
   3.126 +
   3.127  The build system is now configured and you can build the debug versions of 
   3.128  the @command{ns-3} programs by simply typing,
   3.129  
   3.130 @@ -172,8 +206,10 @@
   3.131    ./waf
   3.132  @end verbatim
   3.133  
   3.134 +(Hint:  if you have a multicore machine, use the "-j JOBS" option to speed
   3.135 +up your build, where JOBS is the number of cores)
   3.136  You will see many Waf status messages displayed as the system compiles.  The
   3.137 -most important is the last one,
   3.138 +most important is the last one:
   3.139  
   3.140  @verbatim
   3.141    Compilation finished successfully
   3.142 @@ -187,8 +223,8 @@
   3.143  @section Testing ns-3
   3.144  
   3.145  @cindex unit tests
   3.146 -You can run the unit tests of the @command{ns-3} distribution by running the ``check''
   3.147 -command,
   3.148 +You can run the unit tests of the @command{ns-3} distribution by running the 
   3.149 +``check'' command,
   3.150  
   3.151  @verbatim
   3.152    ./waf check
   3.153 @@ -213,10 +249,10 @@
   3.154    ~/repos/ns-3-dev >
   3.155  @end verbatim
   3.156  
   3.157 -@cindex regression tests
   3.158  This command is typically run by @code{users} to quickly verify that an 
   3.159  @command{ns-3} distribution has built correctly.  
   3.160  
   3.161 +@cindex regression tests
   3.162  You can also run our regression test suite to ensure that your distribution and
   3.163  tool chain have produced binaries that generate output that is identical to
   3.164  reference output files stored in a central location.  To run the regression 
   3.165 @@ -234,7 +270,9 @@
   3.166  located in the releases section of @code{www.nsnam.org}.  The particular name 
   3.167  of the reference trace location is built from the @command{ns-3} version 
   3.168  located in the VERSION file, so don't change that string yourself unless you 
   3.169 -know what you are doing.
   3.170 +know what you are doing.  (Warning:  The ns-3.2 release requires you
   3.171 +to be online when you run regression tests because it synchronizes the
   3.172 +trace directory with an online repository).
   3.173  
   3.174  Once the reference traces are downloaded to your local machine, Waf will run
   3.175  a number of tests that generate what we call trace files.  The content of 
   3.176 @@ -245,27 +283,32 @@
   3.177  @verbatim
   3.178    ~/repos/ns-3-dev > ./waf --regression
   3.179    Entering directory `/home/craigdo/repos/ns-3-dev/build'
   3.180 -  Compilation finished successfully
   3.181 +  Compilation finished successfully 
   3.182    ========== Running Regression Tests ==========
   3.183    Synchronizing reference traces using Mercurial.
   3.184 -  http://code.nsnam.org/ns-3-dev-ref-traces
   3.185 -  Done.
   3.186 +  Pulling http://code.nsnam.org/ns-3-dev-ref-traces from repo.
   3.187 +  Skipping csma-bridge: Python bindings not available.
   3.188 +  SKIP test-csma-bridge
   3.189    PASS test-csma-broadcast
   3.190    PASS test-csma-multicast
   3.191    PASS test-csma-one-subnet
   3.192    PASS test-csma-packet-socket
   3.193 +  PASS test-realtime-udp-echo
   3.194    PASS test-simple-error-model
   3.195    PASS test-simple-global-routing
   3.196    PASS test-simple-point-to-point-olsr
   3.197    PASS test-tcp-large-transfer
   3.198    PASS test-udp-echo
   3.199 +  PASS test-wifi-wired-bridging
   3.200 +
   3.201    ~/repos/ns-3-dev >
   3.202  @end verbatim
   3.203  
   3.204  If a regression tests fails you will see a FAIL indication along with a
   3.205  pointer to the offending trace file and its associated reference trace file
   3.206  along with a suggestion on diff parameters and options in order to see what 
   3.207 -has gone awry.
   3.208 +has gone awry.  Python regression tests will be SKIPped if Python bindings
   3.209 +are not built.
   3.210  
   3.211  @c ========================================================================
   3.212  @c Running a Script
     4.1 --- a/doc/tutorial/introduction.texi	Mon Sep 15 06:11:38 2008 -0700
     4.2 +++ b/doc/tutorial/introduction.texi	Mon Sep 15 21:37:40 2008 -0700
     4.3 @@ -232,7 +232,10 @@
     4.4  @section Development Environment
     4.5  
     4.6  @cindex C++
     4.7 -As mentioned above, scripting in ns-3 is done in C++.  A working 
     4.8 +@cindex Python
     4.9 +As mentioned above, scripting in ns-3 is done in C++ or Python.
    4.10 +As of ns-3.2, most of the ns-3 API is available in Python, but the models
    4.11 +are written in C++ in either case.  A working 
    4.12  knowledge of C++ and object-oriented concepts is assumed in this document.
    4.13  We will take some time to review some of the more advanced concepts or 
    4.14  possibly unfamiliar language features, idioms and design patterns as they 
    4.15 @@ -243,23 +246,27 @@
    4.16  
    4.17  If you are new to C++, you may want to find a tutorial- or cookbook-based
    4.18  book or web site and work through at least the basic features of the language
    4.19 -before proceeding.
    4.20 +before proceeding.  For instance, 
    4.21 +@uref{http://www.cplusplus.com/doc/tutorial/,,this tutorial}.
    4.22  
    4.23  @cindex toolchain
    4.24  @cindex GNU
    4.25 -The @command{ns-3} system uses the GNU ``toolchain'' for development.  A 
    4.26 +The @command{ns-3} system uses several components of the GNU ``toolchain'' 
    4.27 +for development.  A 
    4.28  software toolchain is the set of programming tools available in the given 
    4.29  environment. For a quick review of what is included in the GNU toolchain see,
    4.30 -@uref{http://en.wikipedia.org/wiki/GNU_toolchain}.
    4.31 +@uref{http://en.wikipedia.org/wiki/GNU_toolchain}.  ns-3 uses gcc, 
    4.32 +GNU binutils, and gdb.  However, we do not use the GNU build system,
    4.33 +either make or autotools, using Waf instead.
    4.34  
    4.35  @cindex Linux
    4.36  Typically an @command{ns-3} author will work in Linux or a Linux-like
    4.37  environment.  For those running under Windows, there do exist environments 
    4.38  which simulate the Linux environment to various degrees.  The @command{ns-3} 
    4.39 -project supports development in the Cygwin and the MinGW environments for 
    4.40 -these users.  See @uref{http://www.cygwin.com/} and 
    4.41 -@uref{http://www.mingw.org/} for details on downloading and using these
    4.42 -systems.  Cygwin provides many of the popular Linux system commands.
    4.43 +project supports development in the Cygwin environment for 
    4.44 +these users.  See @uref{http://www.cygwin.com/} 
    4.45 +for details on downloading (MinGW is presently not supported).
    4.46 +Cygwin provides many of the popular Linux system commands.
    4.47  It can, however, sometimes be problematic due to the way it actually does its 
    4.48  emulation, and sometimes interactions with other Windows software can cause 
    4.49  problems.
    4.50 @@ -276,7 +283,10 @@
    4.51  Believe it or not, the @code{Logitech Process Monitor} insinuates itself into
    4.52  every DLL in the system when it is running.  It can cause your Cygwin or
    4.53  MinGW DLLs to die in mysterious ways and often prevents debuggers from 
    4.54 -running.  Beware of Logitech software.
    4.55 +running.  Beware of Logitech software when using Cygwin.
    4.56 +
    4.57 +Another alternative to Cygwin is to install a virtual machine environment
    4.58 +such as VMware server and install a Linux virtual machine.
    4.59  
    4.60  @node Socket Programming
    4.61  @section Socket Programming