F5/unison
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

freshen tutorial

Browse Source
This commit is contained in:
Tom Henderson
2008-09-15 21:37:40 -07:00
parent fea009e803
commit c060f84ef9
4 changed files with 113 additions and 56 deletions
Download Patch File Download Diff File Expand all files Collapse all files

9
doc/tutorial/building-topologies.texi
View File

@@ -812,7 +812,7 @@ usual, you will find the documentation in the ``Classes'' tab of the Doxygen
documentation.
Now we will return to more familiar ground. We next create a @code{WifiHelper}
object and set two default atributes that it will use when creating the actual
object and set two default attributes that it will use when creating the actual
devices.
@verbatim
@@ -1240,12 +1240,13 @@ they happen.
@end verbatim
If you are feeling brave, there is a list of all trace sources in the
@command{ns-3} Doxygen which you can find in the ``NS-3 Modules'' section.
@uref{http://www.nsnam.org/doxygen-release/index.html,,ns-3 Doxygen}
which you can find in the ``Modules'' tab.
Under the ``core'' section, you will find a link to ``The list of all trace
sources.'' You may find it interesting to try and hook some of these
traces yourself. Additionally in the ``NS-3 Modules'' documentation, there is
traces yourself. Additionally in the ``Modules'' documentation, there is
a link to ``The list of all attributes.'' You can set the default value of
any of these atributes via the command line as we have previously discussed.
any of these attributes via the command line as we have previously discussed.
We have just scratched the surface of @command{ns-3} in this tutorial, but we
hope we have covered enough to get you started doing useful work.

11
doc/tutorial/conceptual-overview.texi
View File

@@ -731,10 +731,13 @@ and then build it using waf,
@verbatim
~/repos/ns-3-dev > ./waf
Entering directory `/home/craigdo/repos/ns-3-dev/build'
[432/477] cxx: scratch/first.cc -> build/debug/scratch/first_2.o
[475/477] cxx_link: build/debug/scratch/first_2.o ...
Compilation finished successfully
~/repos/ns-3-dev >
[467/511] cxx: scratch/first.cc -> build/debug/scratch/first_1.o
[468/511] cxx: scratch/multiple-sources/simple-main.cc -> build/debug/scratch/multiple-sources/simple-main_2.o
[469/511] cxx: scratch/multiple-sources/simple-simulation.cc -> build/debug/scratch/multiple-sources/simple-simulation_2.o
[470/511] cxx: scratch/simple.cc -> build/debug/scratch/simple_3.o
[508/511] cxx_link: build/debug/scratch/first_1.o -> build/debug/scratch/first
Compilation finished successfully
~/repos/ns-3-dev >
@end verbatim
You can now run the example (note that if you build your program in the scratch

121
doc/tutorial/getting-started.texi
View File

@@ -44,8 +44,9 @@ the Getting Started section of the @command{ns-3} web site:
@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.
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/},
@@ -62,11 +63,11 @@ 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.
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.1) in the text
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.
@@ -108,6 +109,15 @@ look something like the following:
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 ========================================================================
@@ -137,34 +147,58 @@ 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 >
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,
@@ -172,8 +206,10 @@ the @command{ns-3} programs by simply typing,
./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,
most important is the last one:
@verbatim
Compilation finished successfully
@@ -187,8 +223,8 @@ most important is the last one,
@section Testing ns-3
@cindex unit tests
You can run the unit tests of the @command{ns-3} distribution by running the ``check''
command,
You can run the unit tests of the @command{ns-3} distribution by running the
``check'' command,
@verbatim
./waf check
@@ -213,10 +249,10 @@ test has passed.
~/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.
@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
@@ -234,7 +270,9 @@ 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.
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
@@ -245,27 +283,32 @@ 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
Compilation finished successfully
========== Running Regression Tests ==========
Synchronizing reference traces using Mercurial.
http://code.nsnam.org/ns-3-dev-ref-traces
Done.
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.
has gone awry. Python regression tests will be SKIPped if Python bindings
are not built.
@c ========================================================================
@c Running a Script

28
doc/tutorial/introduction.texi
View File

@@ -232,7 +232,10 @@ found at @uref{http://freehackers.org/~tnagy/waf.html}.
@section Development Environment
@cindex C++
As mentioned above, scripting in ns-3 is done in C++. A working
@cindex Python
As mentioned above, scripting in ns-3 is done in C++ or Python.
As of ns-3.2, most of the ns-3 API is available in Python, but the models
are written in C++ in either case. A working
knowledge of C++ and object-oriented concepts is assumed in this document.
We will take some time to review some of the more advanced concepts or
possibly unfamiliar language features, idioms and design patterns as they
@@ -243,23 +246,27 @@ in print.
If you are new to C++, you may want to find a tutorial- or cookbook-based
book or web site and work through at least the basic features of the language
before proceeding.
before proceeding. For instance,
@uref{http://www.cplusplus.com/doc/tutorial/,,this tutorial}.
@cindex toolchain
@cindex GNU
The @command{ns-3} system uses the GNU ``toolchain'' for development. A
The @command{ns-3} system uses several components of the GNU ``toolchain''
for development. A
software toolchain is the set of programming tools available in the given
environment. For a quick review of what is included in the GNU toolchain see,
@uref{http://en.wikipedia.org/wiki/GNU_toolchain}.
@uref{http://en.wikipedia.org/wiki/GNU_toolchain}. ns-3 uses gcc,
GNU binutils, and gdb. However, we do not use the GNU build system,
either make or autotools, using Waf instead.
@cindex Linux
Typically an @command{ns-3} author will work in Linux or a Linux-like
environment. For those running under Windows, there do exist environments
which simulate the Linux environment to various degrees. The @command{ns-3}
project supports development in the Cygwin and the MinGW environments for
these users. See @uref{http://www.cygwin.com/} and
@uref{http://www.mingw.org/} for details on downloading and using these
systems. Cygwin provides many of the popular Linux system commands.
project supports development in the Cygwin environment for
these users. See @uref{http://www.cygwin.com/}
for details on downloading (MinGW is presently not supported).
Cygwin provides many of the popular Linux system commands.
It can, however, sometimes be problematic due to the way it actually does its
emulation, and sometimes interactions with other Windows software can cause
problems.
@@ -276,7 +283,10 @@ crash creating a sh.exe.stackdump file when I try to compile my source code.''
Believe it or not, the @code{Logitech Process Monitor} insinuates itself into
every DLL in the system when it is running. It can cause your Cygwin or
MinGW DLLs to die in mysterious ways and often prevents debuggers from
running. Beware of Logitech software.
running. Beware of Logitech software when using Cygwin.
Another alternative to Cygwin is to install a virtual machine environment
such as VMware server and install a Linux virtual machine.
@node Socket Programming
@section Socket Programming