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