1.1 --- a/doc/tutorial/introduction.texi Mon Feb 04 19:17:45 2008 -0800
1.2 +++ b/doc/tutorial/introduction.texi Mon Feb 04 23:09:07 2008 -0800
1.3 @@ -4,31 +4,63 @@
1.4 @c ========================================================================
1.5
1.6 @c ========================================================================
1.7 -@c Introduction
1.8 +@c Tutorial Goals
1.9 @c ========================================================================
1.10
1.11 -@node Introduction
1.12 -@chapter Introduction
1.13 +@node Tutorial Goals
1.14 +@unnumbered Tutorial Goals
1.15
1.16 -The @command{ns-3} simulator is a discrete-event network
1.17 +@c This is an unnumbered section, like a preface. Numbering
1.18 +@c starts with section 1 (Introduction)
1.19 +
1.20 +The goal of this ns-3 tutorial is to introduce new users of ns-3 to enough
1.21 +of the system to enable them to author simple simulation scripts and extract
1.22 +useful information from the simulations. We begin by introducing some of the
1.23 +other important resources that are available to those interested in using or
1.24 +writing scripts, models and even those interested in making contributions to
1.25 +the core ns-3 system. We provide an overview of some of the
1.26 +important abstractions, design patterns and idioms used when writing
1.27 +ns-3 scripts, and then dig right in by begining to write simulation
1.28 +scripts, run them and interpret results.
1.29 +
1.30 +After completing this tutorial, one should be able to:
1.31 +@itemize @bullet
1.32 +@item Find documentation resources in the distribution and on the web;
1.33 +@item Download and compile the ns-3 system;
1.34 +@item Understand the key software conventions of ns-3;
1.35 +@item Modify configuration parameters of existing scripts;
1.36 +@item Change the simulation output (tracing, logging, statistics);
1.37 +@item Extend the simulator to use new objects
1.38 +@item Write new ns-3 applications;
1.39 +@item See how to port code from ns-2;
1.40 +@item ... (more to follow)
1.41 +@end itemize
1.42 +
1.43 +@c ========================================================================
1.44 +@c PART: Introduction
1.45 +@c ========================================================================
1.46 +@c The below chapters are under the major heading "Introduction"
1.47 +@c This is similar to the Latex \part command
1.48 +@c
1.49 +@c ========================================================================
1.50 +@c Overview
1.51 +@c ========================================================================
1.52 +@node Overview
1.53 +@chapter Overview
1.54 +
1.55 +@menu
1.56 +* For ns-2 users::
1.57 +* Contributing::
1.58 +* Tutorial organization::
1.59 +@end menu
1.60 +
1.61 +The ns-3 simulator is a discrete-event network
1.62 simulator targeted primarily for research and educational use.
1.63 -The @uref{http://www.nsnam.org,,@command{ns-3} project}, started in
1.64 +The @uref{http://www.nsnam.org,,ns-3 project}, started in
1.65 2006, is an open-source project. The goal of the project is to
1.66 build a new network simulator primarily for research and educational use.
1.67
1.68 -The purpose of this tutorial is to introduce new @command{ns-3} users to the
1.69 -system in a structured way. It is sometimes difficult for new users to
1.70 -glean essential information from detailed manuals and to convert this
1.71 -information into working simulations. In this tutorial, we will build
1.72 -several example simulations, introducing and explaining key concepts and
1.73 -features as we go.
1.74 -
1.75 -As the tutorial unfolds, we will introduce the full @command{ns-3}
1.76 -documentation
1.77 -and provide pointers to source code for those interested in delving deeper
1.78 -into the workings of the system.
1.79 -
1.80 -Primary documentation for the @command{ns-3} project is available in
1.81 +Primary documentation for the ns-3 project is available in
1.82 three forms:
1.83 @itemize @bullet
1.84 @item @uref{http://www.nsnam.org/doxygen/index.html,,ns-3 Doxygen/Manual}: Documentation of the public APIs of the simulator
1.85 @@ -36,71 +68,145 @@
1.86 @item @uref{http://www.nsnam.org/wiki/index.php,, ns-3 wiki}
1.87 @end itemize
1.88
1.89 +The purpose of this tutorial is to introduce new ns-3 users to the
1.90 +system in a structured way. It is sometimes difficult for new users to
1.91 +glean essential information from detailed manuals and to convert this
1.92 +information into working simulations. In this tutorial, we will build
1.93 +several example simulations, introducing and explaining key concepts and
1.94 +features as we go.
1.95 +
1.96 +As the tutorial unfolds, we will introduce the full ns-3
1.97 +documentation
1.98 +and provide pointers to source code for those interested in delving deeper
1.99 +into the workings of the system.
1.100 +
1.101 A few key points are worth noting at the onset:
1.102 @itemize @bullet
1.103 -@item @command{ns-3} is not an extension of @uref{http://www.isi.edu/nsnam/ns,,ns-2}; it is a new
1.104 -simulator. The two simulators are both written in C++ but @command{ns-3}
1.105 -is a new simulator that does not support the @command{ns-2} APIs.
1.106 -Some models from @command{ns-2} have already been ported from @command{ns-2}
1.107 -to @command{ns-3}. The project will continue to maintain @command{ns-2} while
1.108 -@command{ns-3} is being built, and will study transition and
1.109 +@item ns-3 is not an extension of @uref{http://www.isi.edu/nsnam/ns,,ns-2};
1.110 +it is a new
1.111 +simulator. The two simulators are both written in C++ but ns-3
1.112 +is a new simulator that does not support the ns-2 APIs.
1.113 +Some models from ns-2 have already been ported from ns-2
1.114 +to ns-3. The project will continue to maintain ns-2 while
1.115 +ns-3 is being built, and will study transition and
1.116 integration mechanisms.
1.117 -@item @command{ns-3} is open-source, and the project strives to maintain
1.118 +@item ns-3 is open-source, and the project strives to maintain
1.119 an open environment for researchers to contribute and share their
1.120 software.
1.121 @end itemize
1.122
1.123 -The goal of this tutorial is to introduce new users of @command{ns-3} to enough
1.124 -of the system to enable them to author simple simulation scripts and extract
1.125 -useful information from the simulations. We begin by introducing some of the
1.126 -other important resources that are available to those interested in using or
1.127 -writing scripts, models and even those interested in making contributions to
1.128 -the core @command{ns-3} system. We provide an overview of some of the
1.129 -important abstractions, design patterns and idioms used when writing
1.130 -@command{ns-3} scripts, and then dig right in by begining to write simulation
1.131 -scripts, run them and interpret results.
1.132 +@node For ns-2 users
1.133 +@section For ns-2 users
1.134
1.135 -After completing this tutorial, one should be able to:
1.136 +For those familiar with ns-2, the most visible outward change
1.137 +when moving to ns-3 is the choice of scripting language.
1.138 +ns-2 is typically scripted in Tcl and results of simulations can
1.139 +be visualized using the Network Animator @command{nam}. In
1.140 +ns-3 there is currently no visualization module, and Python
1.141 +bindings have been developed (Tcl bindings have been prototyped
1.142 +using @uref{http://www.swig.org,,SWIG}, but are not supported by the
1.143 +current development team).
1.144 +In this tutorial, we will concentrate on
1.145 +scripting directly in C++ and interpreting results via trace files.
1.146 +
1.147 +But there are similarities as well (both, for example, are based
1.148 +on C++ objects, and some code from ns-2 has already been ported
1.149 +to ns-3). We will try to highlight differences between ns-2 and ns-3
1.150 +as we proceed in this tutorial.
1.151 +
1.152 +@node Contributing
1.153 +@section Contributing
1.154 +
1.155 +@cindex software configuration management
1.156 +ns-3 is a research and educational simulator, by and for the
1.157 +research community. It will rely on the ongoing contributions of
1.158 +the community to develop new models, debug or maintain
1.159 +existing ones, and share results. There are a few policies
1.160 +that we hope will encourage people to contribute to ns-3 like they
1.161 +have for ns-2:
1.162 @itemize @bullet
1.163 -@item Find documentation resources in the distribution and on the web;
1.164 -@item Download and compile the @command{ns-3} system;
1.165 -@item Use the provided devices to author network simulations of fairly
1.166 -significant complexity;
1.167 -@item Use the default value system to configure simulations;
1.168 -@item Write new @command{ns-3} applications;
1.169 -@item Use the tracing subsystem.
1.170 +@item open source licensing based on GNU GPLv2 compatibility
1.171 +@item @uref{http://www.nsnam.org/wiki/index.php,,wiki}
1.172 +@item @uref{http://www.nsnam.org/wiki/index.php/Contributed_Code,,Contributed Code} page, similar to ns-2's popular
1.173 +@uref{http://nsnam.isi.edu/nsnam/index.php/Contributed_Code,,Contributed Code}
1.174 +page
1.175 +@item @code{src/contrib} directory (we will host your contributed code)
1.176 +@item open @uref{http://www.nsnam.org/bugzilla,,bug tracker}
1.177 +@item ns-3 developers will gladly help potential contributors to get
1.178 +started with the simulator (please contact @uref{http://www.nsnam.org/people.html,,one of us})
1.179 +@end itemize
1.180 +
1.181 +If you are an ns user, please consider to provide your feedback,
1.182 +bug fixes, or code to the project.
1.183 +
1.184 +@node Tutorial organization
1.185 +@section Tutorial organization
1.186 +
1.187 +The tutorial assumes that new users might follow a path such as follows:
1.188 +
1.189 +@itemize @bullet
1.190 +@item browse the source code and documentation, to get a feel for
1.191 +the simulator and what it might be like to handle;
1.192 +@item try to download and build a copy;
1.193 +@item try to run a few sample programs, and perhaps change some configurations;
1.194 +@item look at simulation output, and try to adjust it
1.195 +@item study the software architecture of the system, to consider hacking it or
1.196 +extending it;
1.197 +@item write new models or port existing code to ns-3, and eventually post those
1.198 +models back to the community.
1.199 @end itemize
1.200
1.201 +As a result, we have tried to organize the tutorial along the above
1.202 +broad sequences of events.
1.203 +
1.204 @c ========================================================================
1.205 -@c Overview
1.206 +@c Browsing ns-3
1.207 @c ========================================================================
1.208
1.209 -@node Overview
1.210 -@chapter Overview
1.211 +@node Browsing
1.212 +@chapter Browsing ns-3
1.213
1.214 -This chapter is a brief tour of @command{ns-3}. It introduces the
1.215 -concept of discrete event simulation, provides a brief overview of
1.216 -@command{ns-3}, and provides a short contextual introduction for
1.217 -the existing @command{ns-2} user community.
1.218 +@menu
1.219 +* Source code::
1.220 +* Doxygen::
1.221 +* Other documentation::
1.222 +@end menu
1.223
1.224 -@node Discrete Event Simulation
1.225 -@section Discrete Event Simulation
1.226 +@node Source code
1.227 +@section Source code
1.228
1.229 -@node ns-3 Overview
1.230 -@section ns-3 Overview
1.231 +The most recent code can be browsed on our web server at the following link:
1.232 +@uref{http://code.nsnam.org/?sort=lastchange}. If you click on the bold
1.233 +repository names on the left of the page, you will see changelogs for
1.234 +these repositories, and links to the @emph{manifest}. From the manifest
1.235 +links, one can browse the source tree.
1.236
1.237 -@node For ns-2 users
1.238 -@section For @command{ns-2} users
1.239 +The top-level directory will look something like:
1.240 +@verbatim
1.241 + AUTHORS RELEASE_NOTES examples/ src/ waf*
1.242 + LICENSE VERSION ns3/ tutorial/ waf.bat*
1.243 + README doc/ samples/ utils/ wscript
1.244 +@end verbatim
1.245 +The source code is mainly in the @code{src} directory. Example
1.246 +scripts are in the @code{examples} directory. Both are good directories
1.247 +to start browsing some code.
1.248
1.249 -For those familiar with @command{ns-2}, the most visible outward change
1.250 -when moving to @command{ns-3} is the choice of scripting language.
1.251 -@command{ns-2} is typically scripted in Tcl and results of simulations are
1.252 -often visualized using the Network Animator @command{nam}. In
1.253 -@command{ns-3} there is currently no visualization module, and multiple
1.254 -language bindings are allowed. In this tutorial, we will concentrate on
1.255 -scripting directly in C++ and interpreting results via trace files. Scripting
1.256 -in other languages will typically be done via straightforward bindings of the
1.257 -target language into the underlying C++.
1.258 +For ns-2 users, who may be familiar with the @code{simple.tcl} example script
1.259 +in the ns-2 documentation, an analogous script is found in
1.260 +@code{examples/simple-point-to-point.cc} with a Python equivalent found
1.261 +in @emph{(pending Python merge)}.
1.262 +
1.263 +@node Doxygen
1.264 +@section Doxygen
1.265 +
1.266 +We document all of APIs using @uref{http://www.stack.nl/~dimitri/doxygen/,,Doxygen}. Current builds of this documentation are available at:
1.267 +@uref{http://www.nsnam.org/doxygen/index.html}, which are worth an initial
1.268 +look.
1.269 +
1.270 +@node Other documentation
1.271 +@section Other documentation
1.272 +
1.273 +See: @uref{http://www.nsnam.org/documents.html}.
1.274
1.275 @c ========================================================================
1.276 @c Resources
1.277 @@ -121,9 +227,9 @@
1.278 @section The Web
1.279
1.280 @cindex www.nsnam.org
1.281 -There are several important resources of which any @command{ns-3} user must be
1.282 +There are several important resources of which any ns-3 user must be
1.283 aware. The main web site is located at @uref{http://www.nsnam.org}
1.284 -and provides access to basic information about the @command{ns-3} system.
1.285 +and provides access to basic information about the ns-3 system.
1.286 Detailed documentation is available through the main web site at
1.287 @uref{http://www.nsnam.org/documents.html}.
1.288
1.289 @@ -133,7 +239,7 @@
1.290 and also gain access to the detailed software documentation. The software
1.291 system is documented in great detail using
1.292 @uref{http://www.stack.nl/~dimitri/doxygen/,,Doxygen}. There is a Wiki that
1.293 -complements the main @command{ns-3} web site which you will find at
1.294 +complements the main ns-3 web site which you will find at
1.295 @uref{http://www.nsnam.org/wiki/}.
1.296
1.297 You will find user and developer FAQs there as well as troubleshooting guides,
1.298 @@ -157,7 +263,7 @@
1.299
1.300 @cindex software configuration management
1.301 @cindex Mercurial
1.302 -The @command{ns-3} project uses Mercurial as its source code management system.
1.303 +The ns-3 project uses Mercurial as its source code management system.
1.304 Although you do not need to know much about Mercurial in order to complete
1.305 this tutorial, we recommend becoming familiar with Mercurial and using it
1.306 to access the source code. Mercurial has a web site at
1.307 @@ -169,8 +275,8 @@
1.308 and a QuickStart guide at
1.309 @uref{http://www.selenic.com/mercurial/wiki/index.cgi/QuickStart/}.
1.310
1.311 -You can also find vital information about using Mercurial and @command{ns-3}
1.312 -on the main @command{ns-3} web site.
1.313 +You can also find vital information about using Mercurial and ns-3
1.314 +on the main ns-3 web site.
1.315
1.316 @node Waf
1.317 @section Waf
1.318 @@ -187,9 +293,9 @@
1.319 alternatives have been developed. Recently these systems have been developed
1.320 using the Python language.
1.321
1.322 -The build system @code{Waf} is used on the @command{ns-3} project. It is one
1.323 +The build system @code{Waf} is used on the ns-3 project. It is one
1.324 of the new generation of Python-based build systems. You will not need to
1.325 -understand any Python to build the existing @command{ns-3} system, and will
1.326 +understand any Python to build the existing ns-3 system, and will
1.327 only have to understand a tiny and intuitively obvious subset of Python in
1.328 order to extend the system in most cases.
1.329
1.330 @@ -200,7 +306,7 @@
1.331 @section Environment, Idioms, and Design Patterns
1.332
1.333 @cindex C++
1.334 -As mentioned above, scripting in @command{ns-3} is done in C++. A working
1.335 +As mentioned above, scripting in ns-3 is done in C++. A working
1.336 knowledge of C++ and object-oriented concepts is assumed in this document.
1.337 We will take some time to review some of the more advanced concepts or
1.338 possibly unfamiliar language features, idioms and design patterns as they
1.339 @@ -217,26 +323,26 @@
1.340
1.341 @cindex toolchain
1.342 @cindex GNU
1.343 -The @command{ns-3} system uses the GNU ``toolchain'' for development.
1.344 +The ns-3 system uses the GNU ``toolchain'' for development.
1.345 A software toolchain is the set of programming tools available in the given
1.346 environment. For a quick review of what is included in the GNU toolchain see,
1.347 @uref{http://en.wikipedia.org/wiki/GNU_toolchain}.
1.348
1.349 @cindex Linux
1.350 -Typically a @command{ns-3} author will work in Linux or a Linux-like
1.351 +Typically an ns-3 author will work in Linux or a Linux-like
1.352 environment. For those running under Windows, there do exist environments
1.353 -which simulate the Linux environment to various degrees. The @command{ns-3}
1.354 +which simulate the Linux environment to various degrees. The ns-3
1.355 project supports development in the Cygwin and the MinGW environments for
1.356 these users. See @uref{http://www.cygwin.com/} and
1.357 @uref{http://www.mingw.org/} for details on downloading and using these
1.358 -systems. I use Cygwin in these cases since it provides all of the Linux tools
1.359 -I know and love. It can, however, sometimes be problematic due to the way it
1.360 +systems. Cygwin provides many of the popular Linux system commands.
1.361 +It can, however, sometimes be problematic due to the way it
1.362 actually does its emulation, and sometimes interactions with other Windows
1.363 software can cause problems.
1.364
1.365 @cindex Cygwin
1.366 @cindex MinGW
1.367 -If you do use Cygwin or MinGW; and use Logitech products, I will save you
1.368 +If you do use Cygwin or MinGW; and use Logitech products, we will save you
1.369 quite a bit of heartburn right off the bat and encourage you to take a look
1.370 at the @uref{http://www.mingw.org/MinGWiki/index.php/FAQ,,MinGW FAQ}.
1.371
1.372 @@ -254,7 +360,7 @@
1.373 In any system, there are a number of problems to be solved that happen
1.374 repeatedly. Often the solutions to these problems can be generalized and
1.375 applied in a similar way across the system. These solutions are called
1.376 -Design Patterns. The @command{ns-3} system relies on several classic design
1.377 +Design Patterns. The ns-3 system relies on several classic design
1.378 patterns.
1.379
1.380 @cindex design pattern
1.381 @@ -269,34 +375,34 @@
1.382
1.383 These low-level constructs, or idioms, extend upward in complexity, eventually
1.384 becoming implementations of design patterns. As you are exposed to more
1.385 -and more of the @command{ns-3} system, you will begin to recognize and be
1.386 +and more of the ns-3 system, you will begin to recognize and be
1.387 comfortable with the C++ implementations (idioms) of several important design
1.388 patterns.
1.389
1.390 @cindex functor
1.391 @cindex callback
1.392 @cindex smart pointer
1.393 -The @command{ns-3} code relies heavily on
1.394 +The ns-3 code relies heavily on
1.395 @emph{Generalized Functors, Callbacks,
1.396 Smart Pointers, Singletons, and Object Factories}. Although we will
1.397 not assume any detailed knowledge of the idioms and design patterns used
1.398 -in the @command{ns-3}
1.399 +in the ns-3
1.400 system, it will be useful for readers who intend to delve deeply into the
1.401 system to understand some important related concepts. We recommend two
1.402 resources: @uref{http://www.amazon.com/Design-Patterns-Object-Oriented-Addison-Wesley-Professional/dp/0201633612/,,Design Patterns: Elements of Reusable Object-Oriented Software, Gamma et. al.} and
1.403 @uref{http://www.amazon.com/exec/obidos/ASIN/0201704315,,Modern C++ Design: Generic Programming and Design Patterns Applied, Alexandrescu}.
1.404
1.405 Gamma addresses the abstract design patterns, and Alexandrescu addresses the
1.406 -C++ idioms you will often see throughout the @command{ns-3} code.
1.407 +C++ idioms you will often see throughout the ns-3 code.
1.408
1.409 @cindex template
1.410 -Almost any use of @command{ns-3} will require some basic knowledge of C++
1.411 +Almost any use of ns-3 will require some basic knowledge of C++
1.412 templates.
1.413 We will discuss the high-level uses in this tutorial. However, if you venture
1.414 deeply into the source code, you will see fairly heavy use of relatively
1.415 sophisticated C++ templates in some of low-level modules of the system. The
1.416 You don't have to be a template guru to complete this tutorial but if you
1.417 -expect to work in @command{ns-3} at a low level you will have to be
1.418 +expect to work in ns-3 within the simulation core, you will have to be
1.419 somewhat fluent
1.420 with templates. If you want to truly grok C++ templates we recommend,
1.421 @uref{http://www.amazon.com/Templates-Complete-Guide-David-Vandevoorde/dp/0201734842/,,C++ Templates: The Complete Guide, Vandevoorde and Josuttis}.
1.422 @@ -340,21 +446,21 @@
1.423 @cindex Waf
1.424 We are going to assume that you have Mercurial and Waf installed and running
1.425 on the target system as described in the Getting Started section of the
1.426 -@command{ns-3} web site: @uref{http://www.nsnam.org/getting_started.html}.
1.427 +ns-3 web site: @uref{http://www.nsnam.org/getting_started.html}.
1.428
1.429 @section Downloading
1.430 @cindex tarball
1.431 -The @command{ns-3} code is available in Mercurial repositories on the server
1.432 +The ns-3 code is available in Mercurial repositories on the server
1.433 code.nsnam.org. You can download a tarball, but we recommend working with
1.434 Mercurial --- it will make your life easier in the long run.
1.435
1.436 @cindex repository
1.437 If you go to the following link: @uref{http://code.nsnam.org/},
1.438 you will see a number of repositories. Many are the private repositories of
1.439 -the @command{ns-3} development team. The repositories of interest to you
1.440 +the ns-3 development team. The repositories of interest to you
1.441 will be
1.442 prefixed with ``ns-3''. The current development snapshot (unreleased) of
1.443 -@command{ns-3} may be found at: @uref{http://code.nsnam.org/ns-3-dev/}.
1.444 +ns-3 may be found at: @uref{http://code.nsnam.org/ns-3-dev/}.
1.445
1.446 The developers attempt to keep this repository in a consistent, working state
1.447 but it is a development area with unreleased code present, so you may want to
1.448 @@ -362,7 +468,7 @@
1.449
1.450 There will be a number of released repositories present at code.nsnam.org.
1.451 These repos will have names like ns-3.0.1 --- which referes to release 3.0.1
1.452 -of the network simulator (or if you like, release 0.1 of @command{ns-3}).
1.453 +of the network simulator (or if you like, release 0.1 of ns-3).
1.454 Since the releases are changing at a rate of one per month, I will stick with
1.455 the more constant ns-3-dev here, but you can replace the string ns-3-dev with
1.456 your choice of release (e.g., ns-3.0.5) below. You can find the latest
1.457 @@ -370,11 +476,12 @@
1.458 to the ``Getting Started'' web page and looking for the latest release
1.459 identifier.
1.460
1.461 -I typically create a directory called @code{repos} in my home directory under
1.462 -which I keep all of my local Mercurial repositories. @emph{Hint: I will
1.463 +One practice is to create a directory called @code{repos} in one's home
1.464 +directory under which one can keep local Mercurial repositories.
1.465 +@emph{Hint: we will
1.466 assume you do this later in the tutorial.} If you adopt that approach, you
1.467 -can get a copy of the development version of @command{ns-3} by typing
1.468 -the following into your Linux shell (I use bash).
1.469 +can get a copy of any of the development versions of ns-3 by typing
1.470 +the following into your Linux shell (assuming you have installed Mercurial):
1.471
1.472 @verbatim
1.473 cd
1.474 @@ -405,14 +512,14 @@
1.475 README doc/ samples/ utils/ wscript
1.476 @end verbatim
1.477
1.478 -You are now ready to build the @command{ns-3} distribution.
1.479 +You are now ready to build the ns-3 distribution.
1.480
1.481 @section Building
1.482 @cindex Waf!build
1.483 @cindex Waf!configure
1.484 @cindex Waf!debug
1.485 @cindex Waf!compile
1.486 -We use Waf to build the @command{ns-3} project. The first thing you
1.487 +We use Waf to build the ns-3 project. The first thing you
1.488 will need to do is to configure the build. For reasons that will become clear
1.489 later, we are going to work with debug builds in the tutorial. To explain to
1.490 Waf that it should do debug builds you will need to execute the following
1.491 @@ -452,10 +559,10 @@
1.492 @end verbatim
1.493
1.494 The build system is now configured and you can build the debug versions of
1.495 -the @command{ns-3} programs by simply typing,
1.496 +the ns-3 programs by simply typing,
1.497
1.498 @verbatim
1.499 - ./waf
1.500 + ./waf check
1.501 @end verbatim
1.502
1.503 You will see many Waf status messages displayed as the system compiles. The
1.504 @@ -465,12 +572,14 @@
1.505 Compilation finished successfully
1.506 @end verbatim
1.507
1.508 +and you will see a number of software unit tests subsequently execute.
1.509 +
1.510 @section Running a Script
1.511 @cindex Waf!run
1.512 We typically run scripts under the control of Waf. This allows the build
1.513 system to ensure that the shared library paths are set correctly and that
1.514 the libraries are available at run time. To run a program, simply use the
1.515 -@code{run} option in Waf. Let's run the @command{ns-3} equivalent of the hello
1.516 +@code{run} option in Waf. Let's run the ns-3 equivalent of the hello
1.517 world program by typing the following:
1.518
1.519 @verbatim
1.520 @@ -485,7 +594,10 @@
1.521 Hello Simulator
1.522 @end verbatim
1.523
1.524 -@emph{Congratulations. You are now an @command{ns-3} user.}
1.525 +If you want to run programs under another tool such as gdb or valgrind,
1.526 +see this @uref{http://www.nsnam.org/wiki/index.php/User_FAQ#How_to_run_NS-3_programs_under_another_tool,,wiki entry}.
1.527 +
1.528 +@emph{Congratulations. You are now an ns-3 user.}
1.529
1.530 @c ========================================================================
1.531 @c Some Prerequisites
1.532 @@ -502,19 +614,19 @@
1.533 @section Abstractions
1.534
1.535 In this section, we'll review some terms that are commonly used in
1.536 -networking, but have a specific meaning in @command{ns-3}.
1.537 +networking, but have a specific meaning in ns-3.
1.538
1.539 @subsection Node
1.540 @cindex Node
1.541 In Internet jargon, a computing device that connects to a network is called
1.542 -a @emph{host} or sometimes an @emph{end system}. Because @command{ns-3} is a
1.543 +a @emph{host} or sometimes an @emph{end system}. Because ns-3 is a
1.544 @emph{network} simulator, not specifically an @emph{Internet} simulator, we
1.545 intentionally do not use the term host since it is closely associated with
1.546 the Internet and its protocols. Instead, we use a more generic term also
1.547 used by other simulators that originates in Graph Theory --- the @emph{node}.
1.548
1.549 @cindex Node!class
1.550 -In @command{ns-3} the basic computing device abstraction is called the
1.551 +In ns-3 the basic computing device abstraction is called the
1.552 node. This abstraction is represented in C++ by the class @code{Node}. The
1.553 @code{Node} class provides methods for managing the representations of
1.554 computing devices in simulations. Developers are expected to specialize the
1.555 @@ -527,7 +639,7 @@
1.556 You should think of a @code{Node} as a computer to which you will add
1.557 functionality. One adds things like applications, protocol stacks and
1.558 peripheral cards with their associated drivers to enable the computer to do
1.559 -useful work. We use the same basic model in @command{ns-3}.
1.560 +useful work. We use the same basic model in ns-3.
1.561
1.562 @subsection Application
1.563 @cindex Application
1.564 @@ -542,14 +654,14 @@
1.565 @cindex system call
1.566 Often, the line of separation between system and application software is made
1.567 at the privilege level change that happens in operating system traps.
1.568 -In @command{ns-3} there is no real concept of operating system and especially
1.569 +In ns-3 there is no real concept of operating system and especially
1.570 no concept of privilege levels or system calls. We do, however, have the
1.571 idea of an application. Just as software applications run on computers to
1.572 -perform tasks in the ``real world,'' @command{ns-3} applications run on
1.573 -@command{ns-3} @code{Node}s to drive simulations in the simulated world.
1.574 +perform tasks in the ``real world,'' ns-3 applications run on
1.575 +ns-3 @code{Node}s to drive simulations in the simulated world.
1.576
1.577 @cindex Application!class
1.578 -In @command{ns-3} the basic abstraction for a user program that generates some
1.579 +In ns-3 the basic abstraction for a user program that generates some
1.580 activity to be simulated is the application. This abstraction is represented
1.581 in C++ by the class @code{Application}. The @code{Application} class provides
1.582 methods for managing the representations of our version of user-level
1.583 @@ -567,7 +679,7 @@
1.584 over which data flows in these netowrks are called @emph{channels}. When
1.585 you connect your Ethernet cable to the plug in the wall, you are connecting
1.586 your computer to an Ethernet communication channel. In the simulated world
1.587 -of @command{ns-3} one connects a @code{Node} to an object representing a
1.588 +of ns-3 one connects a @code{Node} to an object representing a
1.589 communication channel. Here the basic communication subnetwork abstraction
1.590 is called the channel and is represented in C++ by the class @code{Channel}.
1.591
1.592 @@ -602,7 +714,7 @@
1.593 collectively known as @emph{net devices}. In Unix and Linux you refer
1.594 to these net devices by names such as @emph{eth0}.
1.595
1.596 -In @command{ns-3} the @emph{net device} abstraction covers both the software
1.597 +In ns-3 the @emph{net device} abstraction covers both the software
1.598 driver and the simulated hardware. A net device is ``attached'' to a
1.599 @code{Node} in order to enable the @code{Node} to communicate with other
1.600 @code{Node}s in the simulation via @code{Channel}s. Just as in a real
1.601 @@ -619,13 +731,13 @@
1.602
1.603 @subsection Topology Helpers
1.604 In a real network, you will find host computers with added (or built-in)
1.605 -NICs. In @command{ns-3} we would say that you will find @code{Nodes} with
1.606 +NICs. In ns-3 we would say that you will find @code{Nodes} with
1.607 attached @code{NetDevices}. In a large simulated network you will need to
1.608 arrange many connections between @code{Node}s, @code{NetDevice}s and
1.609 @code{Channel}s.
1.610
1.611 Since connecting a @code{NetDevice} to a @code{Node}, and a @code{NetDevice}
1.612 -to a @code{Channel} is such a common task in @command{ns-3} we provide what we
1.613 +to a @code{Channel} is such a common task in ns-3 we provide what we
1.614 call @emph{topology helpers} to make this as easy as possible. Topology
1.615 helpers perform much of the dirty work of creating and connecting net devices.
1.616 For example, it may take several distinct method calls to create a NetDevice,
1.617 @@ -652,7 +764,7 @@
1.618 @cindex InternetNode
1.619 @cindex CreateObject
1.620 @cindex Ptr
1.621 -In @command{ns-3}, if we want to create an @code{InternetNode} in a
1.622 +In ns-3, if we want to create an @code{InternetNode} in a
1.623 script, we will
1.624 typically do something like the following example:
1.625
1.626 @@ -884,12 +996,12 @@
1.627 underlying data can be freed.
1.628
1.629 @cindex reference counting!intrusive
1.630 -The @command{ns-3} smart pointer mechanism uses a mechanism called intrusive
1.631 +The ns-3 smart pointer mechanism uses a mechanism called intrusive
1.632 reference counting to determine when a memory block should be automatically
1.633 deallocated. The term ``intrusive'' means that a reference count (a count of
1.634 variables required to have valid data) is stored in the object being managed
1.635 instead of in a proxy object. This means that each piece of memory managed by
1.636 -a @command{ns-3} smart pointer includes a reference count. When a smart
1.637 +a ns-3 smart pointer includes a reference count. When a smart
1.638 pointer to a reference counted object is created, this reference count is
1.639 incremented. This indicates that a new variable requires a valid data object
1.640 be present. When a smart pointer to a reference counted object is destroyed
1.641 @@ -916,7 +1028,7 @@
1.642 memory leaks.
1.643
1.644 Now, we want to make this feature available as widely as possible to objects
1.645 -in the @command{ns-3} system. The basic operations of the smart pointer class
1.646 +in the ns-3 system. The basic operations of the smart pointer class
1.647 are the same across any intrusively reference counted object. C++ provides a
1.648 mechanism to achieve this kind of generic behavior --- the template. Let's
1.649 examine the declaration of the smart pointer in more detail. First consider
1.650 @@ -1076,7 +1188,7 @@
1.651 between these completely unrelated objects (CsmaChannel and Node).
1.652
1.653 @subsection Summary
1.654 -Going back to our infamous first line of @command{ns-3} code, we said that if
1.655 +Going back to our infamous first line of ns-3 code, we said that if
1.656 we want to create an InternetNode in a script, we will typically do something
1.657 like:
1.658
1.659 @@ -1106,9 +1218,9 @@
1.660 @chapter A First ns-3 script
1.661 @cindex design pattern
1.662 @cindex idiom
1.663 -Lets build a simple network using the @command{ns-3} design patterns, idioms,
1.664 +Lets build a simple network using the ns-3 design patterns, idioms,
1.665 classes and helpers we have just looked at. If you downloaded the system as
1.666 -was suggested above, you will have a release of @command{ns-3} in a directory
1.667 +was suggested above, you will have a release of ns-3 in a directory
1.668 called @code{repos} under your home directory. Change into that directory,
1.669 where you should see a directory structure something like the following.
1.670
1.671 @@ -1140,8 +1252,8 @@
1.672 }
1.673 @end verbatim
1.674
1.675 -This is the @command{ns-3} version of the ubiquitous hello-world program. It
1.676 -uses the @command{ns-3} Log module to print ``Hello Simulator'' into the
1.677 +This is the ns-3 version of the ubiquitous hello-world program. It
1.678 +uses the ns-3 Log module to print ``Hello Simulator'' into the
1.679 standard error output stream.
1.680
1.681 @cindex logging
1.682 @@ -1162,7 +1274,7 @@
1.683 @end verbatim
1.684
1.685 @cindex include files
1.686 -The @command{ns-3} build system places the core include files it needs into a
1.687 +The ns-3 build system places the core include files it needs into a
1.688 directory called @code{ns-3} and so whenever you need to include one of the
1.689 core files you need to explicitly code this. The file @code{ptr.h} defines
1.690 the generic smart pointer that we use. The file @code{internet-node.h}
1.691 @@ -1315,9 +1427,9 @@
1.692 similar to a multi-homed host. Each time you add a net device, you will get
1.693 a new index. Since the IP address for a multi-homed host is associated with
1.694 a net device, we need to provide that index (which we have saved) to the
1.695 -topology helper. We provide an IP version four address via the @command{ns-3}
1.696 +topology helper. We provide an IP version four address via the ns-3
1.697 class @code{Ipv4Address} which takes a dotted decimal string as a constructor
1.698 -parameter. We also provide a network mask using the @command{ns-3} class
1.699 +parameter. We also provide a network mask using the ns-3 class
1.700 @code{Ipv4Mask} which also takes a dotted decimal string. The code to
1.701 perform the IP address assignment, then, looks like the following:
1.702
1.703 @@ -1398,9 +1510,9 @@
1.704
1.705 @section Using Applications
1.706 @cindex Create
1.707 -As mentioned above, we use @code{Application}s in @command{ns-3} to generate
1.708 +As mentioned above, we use @code{Application}s in ns-3 to generate
1.709 the data used to drive simulations. An @code{Application} is added to a
1.710 -@command{ns-3} node conceptually just as if you would add an application to a
1.711 +ns-3 node conceptually just as if you would add an application to a
1.712 computer. When an application is created (using the @code{Create} template)
1.713 we tell the application which @code{Node} it belongs to (and therefore on
1.714 which node it is running) by passing a smart pointer to that @code{Node} in
1.715 @@ -1487,7 +1599,7 @@
1.716 @end verbatim
1.717
1.718 Which approach to take is a matter of style, really, and you will probably
1.719 -see all three approaches taken in the @command{ns-3} code. You should be
1.720 +see all three approaches taken in the ns-3 code. You should be
1.721 comfortable seeing and using all three methods.
1.722
1.723 @subsection A UDP Echo Server Application
1.724 @@ -1507,7 +1619,7 @@
1.725
1.726 We only need to tell the application which node to reside on and which port
1.727 to listen on for UDP packets. The code to actually create the
1.728 -@code{UdpEchoServer} application uses the now quite familiar @command{ns-3} object
1.729 +@code{UdpEchoServer} application uses the now quite familiar ns-3 object
1.730 creation idiom.
1.731
1.732 @subsection A UDP Echo Client-Server Simulation
1.733 @@ -1586,14 +1698,14 @@
1.734 @section Using the Simulation Engine
1.735 @cindex model
1.736 @cindex simulation executive
1.737 -You could say that the heart of the @command{ns-3} system is the
1.738 +You could say that the heart of the ns-3 system is the
1.739 @emph{simulation engine} (sometimes called the simulation executive in other
1.740 systems).
1.741
1.742 In a computer simulation, a computer @emph{model} of a real world @emph{system}
1.743 is constructed. This is typically done to minimize cost since you do not have
1.744 to actually buy, install and maintain physical hardware. In the case of
1.745 -@command{ns-3}, a model is a representation of a networking component that is
1.746 +ns-3, a model is a representation of a networking component that is
1.747 designed to imitate some number of important behaviors or characteristics of
1.748 an actual component in a real network. A system is a collection of models
1.749 arranged for the purpose of analyzing some behavior.
1.750 @@ -1604,7 +1716,7 @@
1.751 @cindex InternetNode
1.752 @cindex NIC
1.753 @cindex CSMA
1.754 -We have already encountered several @command{ns-3} models without specifically
1.755 +We have already encountered several ns-3 models without specifically
1.756 calling them so. The @code{InternetNode}, @code{CsmaNetDevice} and
1.757 @code{CsmaChannel} objects are models of an Internet computing node, a CSMA
1.758 network interface card (NIC), and a network cable able to move data to and
1.759 @@ -1624,7 +1736,7 @@
1.760 @cindex Ethernet
1.761 No model will fully implement @emph{all} of the behaviors of a piece of
1.762 hardware. It is important to understand what is being modeled by the
1.763 -@command{ns-3} components you are using and what is not. For example, the Csma
1.764 +ns-3 components you are using and what is not. For example, the Csma
1.765 components we use in this tutorial model a highly abstract multiple access
1.766 network that is topologically equivalent to an Ethernet. It is not necessarily
1.767 true that results found in a simulation using the Csma models will apply to
1.768 @@ -1661,7 +1773,7 @@
1.769 @cindex function object
1.770 @cindex callback
1.771 @cindex Callback
1.772 -In @command{ns-3} an event is basically a pre-packaged function call called a
1.773 +In ns-3 an event is basically a pre-packaged function call called a
1.774 @emph{functor}. Functors are also known as @emph{function objects}, which is
1.775 a more descriptive term --- an object (in the object-oriented programming
1.776 sense) that can be called as if it was a function. Typically one uses a
1.777 @@ -1673,9 +1785,9 @@
1.778 complete by calling some function you provide. This provided function is
1.779 known as a callback function. [Imagine calling someone on the telephone and
1.780 asking them to do something for you. You also ask them to @emph{call you back}
1.781 -when they are done.] Events in the @command{ns-3} system work conceptually
1.782 +when they are done.] Events in the ns-3 system work conceptually
1.783 the same way, except that instead of an I/O completion driving the process,
1.784 -the arrival of some simulated time drives the process. The @command{ns-3}
1.785 +the arrival of some simulated time drives the process. The ns-3
1.786 deferred exectution mechanism is via a class called @code{Callback}.
1.787
1.788 @cindex Time
1.789 @@ -1688,7 +1800,7 @@
1.790 @section Driving the Simulation
1.791 @cindex Application
1.792 As mentioned previously, time is the driving force behind the progress of
1.793 -a @command{ns-3} simulation. Events are scheduled to happen at certain times
1.794 +a ns-3 simulation. Events are scheduled to happen at certain times
1.795 by calling methods of the simulation engine, either directly or indirectly
1.796 through, for example, an @code{Application}.
1.797
1.798 @@ -1738,7 +1850,7 @@
1.799 you would attempt to start a client application in the real world.
1.800
1.801 @cindex socket!sendto
1.802 -The @command{ns-3} equivalent of the call to @code{sendo} in the client will
1.803 +The ns-3 equivalent of the call to @code{sendo} in the client will
1.804 schedule (immediately) the transmission of a UDP packet over the just created
1.805 socket. This will cause the packet to percolate down the protocol stack and
1.806 eventually into the channel. The channel will schedule a reception event in
1.807 @@ -1763,7 +1875,7 @@
1.808 Simulator::Destroy ();
1.809 @end verbatim
1.810
1.811 -We now have the makings of a complete @command{ns-3} network simulation. The
1.812 +We now have the makings of a complete ns-3 network simulation. The
1.813 source code for the script should look like the following:
1.814
1.815 @verbatim
1.816 @@ -1848,7 +1960,7 @@
1.817 @cindex tutorial-csma-echo.cc
1.818 Just to make sure you don't get caught up in debugging typographical errors
1.819 we have provided this source code for you (along with a copyright header) in
1.820 -the @code{tutorial} subdirectory of the @command{ns-3} distribution as
1.821 +the @code{tutorial} subdirectory of the ns-3 distribution as
1.822 @code{tutorial-csma-echo.cc}. We used this opportunity to do some ``clean up''
1.823 of some of our example cases by passing parameters using implicit conversion
1.824 sequences and removing some of the named parameters. [These were used for
1.825 @@ -1861,7 +1973,7 @@
1.826 which is Python-based. We have to change gears slightly and switch ourselves
1.827 to Python mode in order to proceed.
1.828
1.829 -In each subdirectory of the @command{ns-3} distribution in which there are
1.830 +In each subdirectory of the ns-3 distribution in which there are
1.831 source files, you will find two files: one will be named @code{waf} and one
1.832 will be named @code{wscript}. The former, @code{waf}, is a link that allows
1.833 one to start the build process from any subdirectory. We can ignore that one.
1.834 @@ -1918,7 +2030,3 @@
1.835 UDP Echo Simulation
1.836 ~/repos/ns-3-dev/tutorial >
1.837 @end verbatim
1.838 -
1.839 -Wow! Wasn't that cool! I'm sure you can barely contain yourself at this
1.840 -point. Okay, well, maybe we should figure out how to get some useful
1.841 -information out of that simulation. It did run ... I promise.
2.1 --- a/doc/tutorial/routing.texi Mon Feb 04 19:17:45 2008 -0800
2.2 +++ b/doc/tutorial/routing.texi Mon Feb 04 23:09:07 2008 -0800
2.3 @@ -6,7 +6,7 @@
2.4 module, and some details about the routing approachs currently
2.5 implemented.
2.6
2.7 -@node Overview
2.8 +@node Routing-Overview
2.9 @section Overview
2.10
2.11 We intend to support traditional routing approaches and protocols,
3.1 --- a/doc/tutorial/tutorial.texi Mon Feb 04 19:17:45 2008 -0800
3.2 +++ b/doc/tutorial/tutorial.texi Mon Feb 04 23:09:07 2008 -0800
3.3 @@ -66,7 +66,7 @@
3.4 @contents
3.5
3.6 @ifnottex
3.7 -@node Top, Introduction, Full Table of Contents
3.8 +@node Top, Overview, Full Table of Contents
3.9 @top ns-3 Tutorial (html version)
3.10
3.11 For a pdf version of this tutorial,
3.12 @@ -76,14 +76,15 @@
3.13 @end ifnottex
3.14
3.15 @menu
3.16 -* Introduction::
3.17 -Part 1: Overview
3.18 +* Tutorial Goals::
3.19 +Part 1: Getting Started with ns-3
3.20 * Overview::
3.21 +* Browsing::
3.22 * Resources::
3.23 * Downloading and Compiling::
3.24 * Some-Prerequisites::
3.25 * A-First-ns-3-Script::
3.26 -Part 2: Details
3.27 +Part 2-: Details
3.28 * ns-3 Callbacks::
3.29 * Simulation Output::
3.30 * ns-3 routing overview::