--- a/doc/tutorial/getting-started.texi Mon Mar 23 19:23:11 2009 -0700
+++ b/doc/tutorial/getting-started.texi Tue Mar 24 00:51:10 2009 -0700
@@ -44,78 +44,229 @@
@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
+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.
+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 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''. 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}.
+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/}. 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.
+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.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.
+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.
-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):
+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 @code{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
- cd
- mkdir repos
- cd repos
- hg clone http://code.nanam.org/ns-3-dev
+ ./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
- destination directory: ns-3-dev
+ #
+ # 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 3276 changesets with 12301 changes to 1353 files
- 594 files updated, 0 files merged, 0 files removed, 0 files unresolved
+ added 79 changesets with 1102 changes to 222 files
+ 206 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:
+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
- AUTHORS examples/ README samples/ utils/ waf.bat*
- build/ LICENSE regression/ scratch/ VERSION wscript
- doc/ ns3/ RELEASE_NOTES src/ waf*
+ #
+ # 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
-Similarly, if working from a released version instead, you can simply
+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 @code{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 repos
- wget http://www.nsnam.org/releases/ns-3.2.tar.bz2
- bunzip2 ns-3.2.tar.bz2
- tar xvf ns-3.2.tar
+ 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.
@@ -127,19 +278,61 @@
@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 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,
+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 debug configure
+ ./waf -d optimized configure
@end verbatim
This runs Waf out of the local directory (which is provided as a convenience
@@ -147,57 +340,82 @@
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
+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
-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.
+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 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.
+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,
@@ -206,14 +424,8 @@
./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
+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
@@ -234,19 +446,22 @@
test has passed.
@verbatim
- ~/repos/ns-3-dev > ./waf check
- Entering directory `/home/craigdo/repos/ns-3-dev/build'
- Compilation finished successfully
+ Entering directory `/home/craigdo/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
- ~/repos/ns-3-dev >
+ -- 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
@@ -281,34 +496,25 @@
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
+ Entering directory `/home/craigdo/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
- 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 >
+ [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 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.
+has gone awry. Some regression tests wmay be SKIPped if the required support
+is not present.
@c ========================================================================
@c Running a Script