--- a/doc/tutorial/conceptual-overview.texi Sun Jun 29 20:48:18 2008 -0700
+++ b/doc/tutorial/conceptual-overview.texi Sun Jun 29 21:22:33 2008 -0700
@@ -4,56 +4,47 @@
@c ========================================================================
@c ========================================================================
-@c PART: Conceptual Overview
-@c ========================================================================
-@c The below chapters are under the major heading "Getting Started"
-@c This is similar to the Latex \part command
-@c ========================================================================
-@c Some Conceptual Overview
+@c Conceptual Overview
@c ========================================================================
@node Conceptual Overview
@chapter Conceptual Overview
@menu
* Key Abstractions::
+* A First ns-3 script
@end menu
The first thing we need to do before actually starting to look at or write
-ns-3 code is to explain a few core concepts, abstractions and idioms in the
+@command{ns-3} code is to explain a few core concepts and abstractions in the
system. Much of this may appear transparently obvious to some, but we
-recommend taking the time to read through this chapter just to ensure you
+recommend taking the time to read through this section just to ensure you
are starting on a firm foundation.
@node Key Abstractions
@section Key Abstractions
In this section, we'll review some terms that are commonly used in
-networking, but have a specific meaning in ns-3.
+networking, but have a specific meaning in @command{ns-3}.
@subsection Node
@cindex Node
In Internet jargon, a computing device that connects to a network is called
-a @emph{host} or sometimes an @emph{end system}. Because ns-3 is a
+a @emph{host} or sometimes an @emph{end system}. Because @command{ns-3} is a
@emph{network} simulator, not specifically an @emph{Internet} simulator, we
intentionally do not use the term host since it is closely associated with
the Internet and its protocols. Instead, we use a more generic term also
used by other simulators that originates in Graph Theory --- the @emph{node}.
@cindex class Node
-In ns-3 the basic computing device abstraction is called the
+In @command{ns-3} the basic computing device abstraction is called the
node. This abstraction is represented in C++ by the class @code{Node}. The
@code{Node} class provides methods for managing the representations of
-computing devices in simulations. Developers are expected to specialize the
-@code{Node} in the object-oriented programming sense to create new computing
-device models. In this tutorial, we will use a specialization of class
-@code{Node} called @code{InternetNode}. As you might expect, the
-@code{InternetNode} is a class that represents a host in the Internet sense,
-and automatically provides core IPv4 networking protocols.
+computing devices in simulations.
You should think of a @code{Node} as a computer to which you will add
functionality. One adds things like applications, protocol stacks and
peripheral cards with their associated drivers to enable the computer to do
-useful work. We use the same basic model in ns-3.
+useful work. We use the same basic model in @command{ns-3}.
@subsection Application
@cindex Application
@@ -68,23 +59,24 @@
@cindex system call
Often, the line of separation between system and application software is made
at the privilege level change that happens in operating system traps.
-In ns-3 there is no real concept of operating system and especially
+In @command{ns-3} there is no real concept of operating system and especially
no concept of privilege levels or system calls. We do, however, have the
idea of an application. Just as software applications run on computers to
-perform tasks in the ``real world,'' ns-3 applications run on
-ns-3 @code{Node}s to drive simulations in the simulated world.
+perform tasks in the ``real world,'' @command{ns-3} applications run on
+@command{ns-3} @code{Node}s to drive simulations in the simulated world.
@cindex class Application
-In ns-3 the basic abstraction for a user program that generates some
+In @command{ns-3} the basic abstraction for a user program that generates some
activity to be simulated is the application. This abstraction is represented
in C++ by the class @code{Application}. The @code{Application} class provides
methods for managing the representations of our version of user-level
applications in simulations. Developers are expected to specialize the
-@code{Application} in the object-oriented programming sense to create new
+@code{Application} class in the object-oriented programming sense to create new
applications. In this tutorial, we will use specializations of class
-@code{Application} called @code{UdpEchoClient} and @code{UdpEchoServer}.
-As you might expect, these applications compose a client/server application set
-used to generate and echo simulated network packets
+@code{Application} called @code{UdpEchoClientApplication} and
+@code{UdpEchoServerApplication}. As you might expect, these applications
+compose a client/server application set used to generate and echo simulated
+network packets
@subsection Channel
@cindex Channel
@@ -93,7 +85,7 @@
over which data flows in these netowrks are called @emph{channels}. When
you connect your Ethernet cable to the plug in the wall, you are connecting
your computer to an Ethernet communication channel. In the simulated world
-of ns-3 one connects a @code{Node} to an object representing a
+of @command{ns-3} one connects a @code{Node} to an object representing a
communication channel. Here the basic communication subnetwork abstraction
is called the channel and is represented in C++ by the class @code{Channel}.
@@ -105,10 +97,10 @@
switch, or three-dimensional space in the case of wireless networks.
We will use specialized versions of the @code{Channel} called
-@code{CsmaChannel} and @code{PointToPointChannel} in this tutorial. The
-@code{CsmaChannel}, for example, models a version of a communication subnetwork
-that implements a @emph{carrier sense multiple access} communication medium.
-This gives us Ethernet-like functionality.
+@code{CsmaChannel}, @code{PointToPointChannel} and @code{WifiChannel} in this
+tutorial. The @code{CsmaChannel}, for example, models a version of a
+communication subnetwork that implements a @emph{carrier sense multiple
+access} communication medium. This gives us Ethernet-like functionality.
@subsection Net Device
@cindex NetDevice
@@ -127,8 +119,8 @@
collectively known as @emph{net devices}. In Unix and Linux you refer
to these net devices by names such as @emph{eth0}.
-In ns-3 the @emph{net device} abstraction covers both the software
-driver and the simulated hardware. A net device is ``attached'' to a
+In @command{ns-3} the @emph{net device} abstraction covers both the software
+driver and the simulated hardware. A net device is ``installed'' in a
@code{Node} in order to enable the @code{Node} to communicate with other
@code{Node}s in the simulation via @code{Channel}s. Just as in a real
computer, a @code{Node} may be connected to more than one @code{Channel} via
@@ -137,55 +129,60 @@
The net device abstraction is represented in C++ by the class @code{NetDevice}.
The @code{NetDevice} class provides methods for managing connections to
@code{Node} and @code{Channel} objects; and may be specialized by developers
-in the object-oriented programming sense. We will use the specialized version
-of the @code{NetDevice} called the @code{CsmaNetDevice} in this tutorial.
+in the object-oriented programming sense. We will use the several specialized
+versions of the @code{NetDevice} called @code{CsmaNetDevice},
+@code{PointToPointNetDevice}, and @code{WifiNetDevice} in this tutorial.
Just as an Ethernet NIC is designed to work with an Ethernet network, the
-@code{CsmaNetDevice} is designed to work with a @code{CsmaChannel}.
+@code{CsmaNetDevice} is designed to work with a @code{CsmaChannel}; the
+@code{PointToPointNetDevice} is designed to work with a
+@code{PointToPointChannel} and a @code{WifiNetNevice} is designed to work with
+a @code{WifiChannel}.
@subsection Topology Helpers
@cindex helper
@cindex topology
@cindex topology helper
In a real network, you will find host computers with added (or built-in)
-NICs. In ns-3 we would say that you will find @code{Nodes} with
+NICs. In @command{ns-3} we would say that you will find @code{Nodes} with
attached @code{NetDevices}. In a large simulated network you will need to
arrange many connections between @code{Node}s, @code{NetDevice}s and
@code{Channel}s.
Since connecting @code{NetDevice}s to @code{Node}s, @code{NetDevice}s
to @code{Channel}s, assigning IP addresses, etc., are such common tasks
-in ns-3 we provide what we call @emph{topology helpers} to make this as easy
-as possible. For example, will take several distinct ns-3 core operations
-to create a NetDevice, add a MAC address, connect the net device to a
-@code{Node}, configure the protocol stack, and then connect the
-@code{NetDevice} to a @code{Channel}. More higher level operations would be
-required to connect multiple devices onto multipoint channels and then to
+in @command{ns-3}, we provide what we call @emph{topology helpers} to make
+this as easy as possible. For example, will take several distinct
+@command{ns-3} core operations to create a NetDevice, add a MAC address,
+connect the net device to a @code{Node}, configure the protocol stack, and
+then connect the @code{NetDevice} to a @code{Channel}. More operations would
+be required to connect multiple devices onto multipoint channels and then to
connect networks together into internetworks. We use topology helper objects
-to compose those distinct operations into an easy to use model.
+to combine those many distinct operations into an easy to use model.
@c ========================================================================
@c A First ns-3 script
@c ========================================================================
@node A First ns-3 Script
-@chapter A First ns-3 Script
+@section A First ns-3 script
@cindex first script
If you downloaded the system as was suggested above, you will have a release
-of ns-3 in a directory called @code{repos} under your home directory. Change
-into that release directory, and you should find a directory structure
-something like the following:
+of @command{ns-3} in a directory called @code{repos} under your home
+directory. Change into that release directory, and you should find a
+directory structure something like the following:
@verbatim
- AUTHORS examples/ README samples/ tutorial/ waf*
- build/ LICENSE regression/ scratch/ utils/ waf.bat*
- doc/ ns3/ RELEASE_NOTES src/ VERSION wscript
+ AUTHORS examples/ README samples/ utils/ waf.bat*
+ build/ LICENSE regression/ scratch/ VERSION wscript
+ doc/ ns3/ RELEASE_NOTES src/ waf*
@end verbatim
@cindex first.cc
Change into the examples directory. You should see a file named
@code{first.cc} located there. This is a script that will create a simple
point-to-point link between two nodes and echo a single packet between the
-nodes. Let's take a look at the script line by line.
+nodes. Let's take a look at that script line by line.
+@subsection Boilerplate
The first line in the file is an emacs mode line. This tells emacs about the
formatting conventions (coding style) we use in our source code.
@@ -194,16 +191,21 @@
@end verbatim
This is always a somewhat controversial subject, so we might as well get it
-out of the way immediately. The ns-3 project, like most large projects, has
-adopted a coding style to which all contributed code must adhere. If you want
-to contribute your code to the project, you will eventually have to conform to
-the ns-3 coding style as described in INSERT LINK TO CODING STYLE PAGE ON WEB.
+out of the way immediately. The @code{ns-3} project, like most large
+projects, has adopted a coding style to which all contributed code must
+adhere. If you want to contribute your code to the project, you will
+eventually have to conform to the @command{ns-3} coding standard as described
+in the file @code{doc/codingstd.txt}. We recommend that you, well, just get
+used to the look and feel of @code{ns-3} code and adopt this standard whenever
+you are working with our code. All of the development team have done so.
The emacs mode line above makes it easier to get the formatting correct if you
use the emacs editor.
-The ns-3 simulator is licentsed using the GNU General Public License. You
-will see the appropriate GNU legalese at the head of every file in the ns-3
-distribution.
+The @command{ns-3} simulator is licentsed using the GNU General Public
+License. You will see the appropriate GNU legalese at the head of every file
+in the @command{ns-3} distribution. Often you will see a copyright notice for
+one of the institutions involved in the @code{ns-3} project and an author
+listed.
@verbatim
/*
@@ -222,7 +224,7 @@
*/
@end verbatim
-@section Module Includes
+@subsection Module Includes
The code proper starts with a number of include statements. To help our high
level users deal with the large number of include files present in the system,
we group includes according to relatively large modules. We provide a single
@@ -230,9 +232,9 @@
module. Rather than having to look up exactly what header you need, and
possibly have to get dependencies right, we give you the ability to load a
group of files at a large granularity. This is not the most efficient approach
-but it certainly makes writing scripts much easier. Each of the ns-3 files
-is placed in a directory called @code{ns3} to help with include file name
-collisions.
+but it certainly makes writing scripts much easier. Each of the
+@command{ns-3} files is placed in a directory called @code{ns3} (under the
+build directory) to help avoid include file name collisions.
@verbatim
#include "ns3/core-module.h"
@@ -248,39 +250,43 @@
under the appropriate @code{build/debug} or @code{build/optimized} directory
depending on your configuration. Waf will also automatically generate a module
include file to load all of the public header files. Since you are following
-this tutorial perfectly, you will have done a
+this tutorial religiously, you will already have done a
@verbatim
./waf -d debug configure
@end verbatim
-to configure the project to perform debug builds. You will also have done a,
+to configure the project to perform debug builds. You will also have done a
@verbatim
./waf
@end verbatim
-to build the project. So if you look in the directory @code{build/debug/ns-3}
-you will find the four module includes shown above.
+to build the project. So now if you look in the directory
+@code{build/debug/ns-3} you will find the four module include files shown
+above. You can take a look at the contents to find that these files will
+include all of the public includes in the respective modules.
-@section Ns3 Namespace
-The next line in the @code{first.cc} script is a namespace statement:
+@subsection Ns3 Namespace
+The next line in the @code{first.cc} script is a namespace declaration.
@verbatim
using namespace ns3;
@end verbatim
-The ns-3 project is implemented in a C++ namespace called @code{ns3}. This
-groups all ns-3-related declarations in a scope outside the global namespace
-which we hope will help with integration with other code. The C++ @code{using}
-statement introduces the ns-3 namespace into the current (global) declarative
-region. This is a fancy way of saying that after this declaration, you will
-not have to type @code{ns3::} before all of the ns-3 code in order to use it.
-If you are unfamiliar with namespaces, please consult almost any C++ tutorial
-and compare the ns3 namespace and usage here with the std namespace and
-a @code{using namespace std;} statement.
+The @command{ns-3} project is implemented in a C++ namespace called
+@code{ns3}. This groups all @command{ns-3}-related declarations in a scope
+outside the global namespace, which we hope will help with integration with
+other code. The C++ @code{using} statement introduces the @code{ns-3}
+namespace into the current (global) declarative region. This is a fancy way
+of saying that after this declaration, you will not have to type @code{ns3::}
+scope resolution operator before all of the @code{ns-3} code in order to use
+it. If you are unfamiliar with namespaces, please consult almost any C++
+tutorial and compare the @code{ns3} namespace and usage here with instances of
+the @code{std} namespace and the @code{using namespace std;} statements you
+will often find in discussions of @code{cout} and streams.
-@section Logging
+@subsection Logging
The next line of the script is the following,
@verbatim
@@ -298,11 +304,12 @@
Along the left side, you will find a graphical representation of the structure
of the documentation. A good place to start is the @code{NS-3 Modules}
-``book.'' If you expand @code{Modules} you will see a list of ns-3 module
-documentation. The concept of module here ties directly into the module
-include files discussed above. It turns out that the ns-3 logging subsystem
-is part of the @code{core} module, so go ahead and expand that node. Now,
-open the @code{Debugging} book and then select the @code{Logging} page.
+``book.'' If you expand @code{Modules} you will see a list of @command{ns-3}
+module documentation. The concept of module here ties directly into the
+module include files discussed above. It turns out that the @command{ns-3}
+logging subsystem is part of the @code{core} module, so go ahead and expand
+that documentation node. Now, open the @code{Debugging} book and then select
+the @code{Logging} page.
You should now be looking at the Doxygen documentation for the Logging module.
In the list of @code{#define}s you will see @code{NS_LOG_COMPONENT_DEFINE}.
@@ -313,6 +320,7 @@
component called @code{FirstScriptExample} that allows you to enable and
disable console message logging by reference to the name.
+@subsection Main Function
The next lines of the script you will find are:
@verbatim
@@ -323,8 +331,8 @@
This is just the declaration of the main function of your program. Just as in
any C++ program, you need to define a main function that will be the first
-function run. There is nothing at all special here. Your ns-3 script is just
-a C++ program.
+function run. There is nothing at all special here. Your @command{ns-3}
+script is just a C++ program.
The next two lines of the script are used to enable two logging components that
are built into the Echo Client and Echo Server applications:
@@ -335,64 +343,66 @@
@end verbatim
If you have read over the Logging component documentation you will see that
-there are a number of levels of detail that you enable on each component.
+there are a number of levels of detail that you can enable on each component.
These two lines of code enable debug logging at the INFO level for echo
clients and servers. This will result in the application printing out
-a message as packets are sent and received.
+messages as packets are sent and received.
Now we will get directly to the business of creating a topology and running
a simulation. We will use the topology helper objects to make this job as
easy as possible.
-@section Topology Helpers
-@subsection NodeContainer
-The next two lines of code in our script will actually create the ns-3 objects
-that will represent the computers in the simulation.
+@subsection Topology Helpers
+@subsubsection NodeContainer
+The next two lines of code in our script will actually create the
+@command{ns-3} @code{Node} objects that will represent the computers in the
+simulation.
@verbatim
NodeContainer nodes;
nodes.Create (2);
@end verbatim
-Let's find the documentation for the first object before we continue. Another
-way to get into the documentation system is via the @code{Classes} tab in the
-HTML pages. If you still have the Doxygen handy, just scroll up to the top
-of the page and select the @code{Classes} tab. You should see a new set of
-tabs appear, one of which is @code{Class List}. Under that tab you will see
-a list of all of the ns-3 classes. Scroll down, looking for
-@code{ns3::NodeContainer}. When you find the class, go ahead and select it to
-go to the Doxygen.
+Let's find the documentation for the @code{NodeContainer} class before we
+continue. Another way to get into the documentation for a given class is via
+the @code{Classes} tab in the Doxygen pages. If you still have the Doxygen
+handy, just scroll up to the top of the page and select the @code{Classes}
+tab. You should see a new set of tabs appear, one of which is
+@code{Class List}. Under that tab you will see a list of all of the
+@command{ns-3} classes. Scroll down, looking for @code{ns3::NodeContainer}.
+When you find the class, go ahead and select it to go to the documentation for
+the class.
You may recall that one of our key abstractions is the @code{Node}. This
represents a computer to which we are going to add things like protocol stacks,
applications and peripheral cards. The @code{NodeContainer} topology helper
provides a convenient way to create, manage and access any @code{Node} objects
-that we create in order to run a simulation. The first line just declares a
-NodeContainer which we call @code{nodes}. The second line calls the
-@code{Create} method on the @code{nodes} object and asks the container to
+that we create in order to run a simulation. The first line above just
+declares a NodeContainer which we call @code{nodes}. The second line calls the
+@code{Create} method on the @code{nodes} object that asks the container to
create two nodes. As described in the Doxygen, the container calls down into
-the ns-3 system to create two @code{Node} objects and stores the pointers
-internally.
+the @command{ns-3} system proper to create two @code{Node} objects and stores
+pointers to those objects internally.
-The nodes as they stand at this point in the script do nothing. The next step
-in constructing a topology is to connect our nodes together into a network.
-The simplest form of network is a single point-to-point link between two nodes
-so we'll construct one here.
+The nodes as they stand in the script do nothing. The next step in
+constructing a topology is to connect our nodes together into a network.
+The simplest form of network we support is a single point-to-point link
+between two nodes. We'll construct one of those links here.
-@subsection PointToPointHelper
-We are constructing a point to point link, and in a pattern which will become
+@subsubsection PointToPointHelper
+We are constructing a point to point link, and, in a pattern which will become
quite familiar to you, we use a topology helper object to do the low-level
work required to put the link together. Recall that two of our key
abstractions are the @code{NetDevice} and the @code{Channel}. In the real
-world, this corresponds roughly to peripheral cards and network cables.
+world, these terms correspond roughly to peripheral cards and network cables.
Typically these two things are intimately tied together and one cannot expect
-to interchange Ethernet devices and wireless channels, for example. Our
+to interchange, for example, Ethernet devices and wireless channels. Our
Topology Helpers follow this intimate coupling and therefore you will use a
-single @code{PointToPointHelper} to configure and connect ns-3
+single @code{PointToPointHelper} to configure and connect @command{ns-3}
@code{PointToPointNetDevice} and @code{PointToPointChannel} objects in this
script.
-The next three lines in the @code{first.cc} script are
+The next three lines in the script are,
@verbatim
PointToPointHelper pointToPoint;
@@ -406,9 +416,8 @@
PointToPointHelper pointToPoint;
@end verbatim
-creates a @code{PointToPointHelper} object on the stack.
-
-From a high-level perspective the next line,
+creates a @code{PointToPointHelper} object on the stack. From a high-level
+perspective the next line,
@verbatim
pointToPoint.SetDeviceParameter ("DataRate", StringValue ("5Mbps"));
@@ -423,23 +432,23 @@
If you look at the Doxygen for class @code{ns3::PointToPointNetDevice} and
find the documentation for the @code{GetTypeId} method, you will find a list
of @code{Attributes} defined for the device. Among these is the ``DataRate''
-attribute. Most user-visible ns-3 objects have similar lists of attributes.
-We use this mechanism to easily configure simulations without recompiling
-as you will see in a following section.
+attribute. Most user-visible @command{ns-3} objects have similar lists of
+attributes. We use this mechanism to easily configure simulations without
+recompiling as you will see in a following section.
Similar to the ``DataRate'' on the @code{PointToPointNetDevice} we find a
-``Delay'' attribute associated with the @code{PointToPointChannel}. THe
+``Delay'' attribute associated with the @code{PointToPointChannel}. The
final line,
@verbatim
pointToPoint.SetChannelParameter ("Delay", StringValue ("2ms"));
@end verbatim
-Tells the @code{PointToPointHelper} to use the value ``2ms'' (two milliseconds)
+tells the @code{PointToPointHelper} to use the value ``2ms'' (two milliseconds)
as the value of the transmission delay of every point to point channel it
creates.
-@subsection NetDeviceContainer
+@subsubsection NetDeviceContainer
At this point in the script, we have a @code{NodeContainer} that contains
two nodes. We have a @code{PointToPointHelper} that is primed and ready to
make @code{PointToPointNetDevices} and wire @code{PoiintToPointChannel} objects
@@ -464,18 +473,18 @@
two for a point-to-point link) a @code{PointToPointNetDevice} is created and
saved in the device container. A @code{PointToPointChannel} is created and
the two @code{PointToPointNetDevices} are attached. When objects are created
-by the @code{PointToPointHelper} the attributes previously set in the helper
+by the @code{PointToPointHelper}, the attributes previously set in the helper
are used to initialize the corresponding attributes in the created objects.
After executing the the @code{pointToPoint.Install (nodes)} call we will have
two nodes, each with an installed point-to-point net device and a
-point-to-point channel between them. Both devices will send data at five
-megabits per second over the channel which has a two millisecond transmission
-delay.
+point-to-point channel between them. Both devices will be configured to
+transmit data at five megabits per second over the channel which has a two
+millisecond transmission delay.
-@subsection InternetStackHelper
-We have nodes and devices configured, but we don't have any protocol stacks
-installed on our nodes. The next two lines of code take care of that.
+@subsubsection InternetStackHelper
+We now have nodes and devices configured, but we don't have any protocol stacks
+installed on our nodes. The next two lines of code will take care of that.
@verbatim
InternetStackHelper stack;
@@ -488,12 +497,12 @@
executed, it will install an Internet Stack (TCP, UDP, IP, etc.) on each of
the nodes in the node container.
-@subsection Ipv4AddressHelper
+@subsubsection Ipv4AddressHelper
Next we need to associate the devices on our nodes with IP addresses. We
provide a topology helper to manage the allocation of IP addresses. The only
user-visible API is to set the base IP address and network mask to use when
-performing the actual address allocation (which is done at a lower level in the
-code).
+performing the actual address allocation (which is done at a lower level
+inside the helper).
The next two lines of code in our example script, @code{first.cc},
@@ -504,7 +513,12 @@
declare an address helper object and tell it that it should begin allocating IP
addresses from the network 10.1.1.0 using the mask 255.255.255.0 to define
-the allocatable bits.
+the allocatable bits. By default the addresses allocated will start at one
+and increase monotonically, so the first address allocated from this base will
+be 10.1.1.1, followed by 10.1.1.2, etc. The low level @command{ns-3} system
+actually remembers all of the IP addresses allocated and will generate a
+fatal error if you accidentally cause the same address to be generated twice
+(which is a very hard to find error, by the way).
The next line of code,
@@ -512,25 +526,26 @@
Ipv4InterfaceContainer interfaces = address.Assign (devices);
@end verbatim
-performs the actual address assignment. In ns-3 we make the association
-between an IP address and a device using an @code{Ipv4Interface} object.
-Just as we sometimes need a list of net devices created by a helper for future
-reference we sometimes need a list of @code{Ipv4Interface} objects. The
-@code{Ipv4InterfaceContainer} provides this functionality.
+performs the actual address assignment. In @command{ns-3} we make the
+association between an IP address and a device using an @code{Ipv4Interface}
+object. Just as we sometimes need a list of net devices created by a helper
+for future reference we sometimes need a list of @code{Ipv4Interface} objects.
+The @code{Ipv4InterfaceContainer} provides this functionality.
-Now we have a point-to-point network made with IP addresses assigned. What
-we need at this point are applications to generate traffic.
+Now we have a point-to-point network built, with stacks installed and IP
+addresses assigned. What we need at this point are applications to generate
+traffic.
-@section Applications
+@subsection Applications
Another one of the core abstractions of the ns-3 system is the
@code{Application}. In this script we use two specializations of the core
-ns-3 class @code{Application} called @code{UdpEchoServerApplication} and
-@code{UdpEchoClientApplication}. Just as in the previous instances of ns-3
-objects, we use helper objects to help configure and manage the underlying
-objects. Here, we use @code{UdpEchoServerHelper} and
+@command{ns-3} class @code{Application} called @code{UdpEchoServerApplication}
+and @code{UdpEchoClientApplication}. Just as we have in our previous
+explanations, we use helper objects to help configure and manage the
+underlying objects. Here, we use @code{UdpEchoServerHelper} and
@code{UdpEchoClientHelper} objects to make our lives easier.
-@subsection UdpEchoServerHelper
+@subsubsection UdpEchoServerHelper
The following lines of code in our example script, @code{first.cc}, are used
to set up a UDP echo server application on one of the nodes we have previously
created and connected using a point-to-point link.
@@ -546,7 +561,7 @@
The first line of code in the above snippet declares the
@code{UdpEchoServerHelper}. As usual, this isn't the application itself, it
-is an object to help us create the actual applications. The second line
+is an object used to help us create the actual applications. The second line
that has the @code{SetPort} call, is used to tell the helper to assign the
value nine to the ``Port'' attribute when creating
@code{UdpEchoServerApplication} objects.
@@ -557,103 +572,21 @@
to a node. Interestingly, the @code{Install} method takes a
@code{NodeContainter} as a parameter just as the other @code{Install} methods
we have seen. This is actually what is passed to the method even though it
-doesn't look so in this case. It will be worth a slight digression
-to undersand what is going on here.
-
-@subsubsection Implicit Conversions
-This is an example of a C++ @code{implicit conversion} at work. Many
-programmers use implicit conversions without even realizing it since they are
-sometimes so intuitive. For example, in the following code,
-
-@verbatim
- int i = 1;
- double d = 2.;
- if (n == d) ...
-@end verbatim
-
-@cindex standard conversion
-the integer (1) is implicitly converted to a double (1.) before the comparison
-takes place. This conversion is performed using what is known as a C++
-@emph{standard conversion}.
-
-C++ will try to determine a sequence of type conversions to use in order to
-convert an argument in a function call to the type of a corresponding paramter
-in a method declaration. The method call in this case is,
-
-@verbatim
- ApplicationContainer serverApps = echoServer.Install (nodes.Get (1));
-@end verbatim
-
-If you look at the declaration of the Install method in the source (or the
-Doxygen) you will see,
-
-@verbatim
- ApplicationContainer
- UdpEchoServerHelper::Install (NodeContainer c)
- {
- ...
- }
-@end verbatim
-
-Now, the @code{Get} method of the @code{NodeContainer} returns a smart pointer
-to a node object:
+doesn't look so in this case. There is a C++ @emph{implicit conversion} at
+work here.
-@verbatim
- Ptr<Node>
- NodeContainer::Get (uint32_t i) const
- {
- ...
- }
-@end verbatim
-
-C++ notices that it needs to convert a type @code{Ptr<Node>} into a type
-@code{NodeContainer}. It turns out that @code{NodeContainer} has a
-constructor that takes a @code{Ptr<Node>} as a parameter.
-
-@verbatim
- NodeContainer::NodeContainer (Ptr<Node> node)
- {
- ...
- }
-@end verbatim
-
-The C++ compiler implicitly provides the @code{Ptr<Node>} returned from the
-@code{NodeContainer::Get} to the above constructor for @code{NodeContainer} to
-make a new @code{NodeContainer} to pass to the @code{Install} method of the
-@code{UdpEchoServerHelper} object.
-
-Taking advantage of these implicit conversion sequences can allow you to
-avoid doing a lot of typing. The result is also fairly intuitive if you
-don't pay close attention to the called method signatures. If you are
-one of those folks that pays close attention, it does have the downside of
-sometimes being surprising when you, for example, look for the method
-in @code{UdpEchoServerHelper} named @code{Install} that takes a parameter
-@code{Ptr<Node>} and cannot find it.
-
-@subsection UdpEchoServerHelper Continued
-Returning to the example script, we are looking at the following code snippet.
-
-@verbatim
- UdpEchoServerHelper echoServer;
- echoServer.SetPort (9);
-
- ApplicationContainer serverApps = echoServer.Install (nodes.Get (1));
- serverApps.Start (Seconds (1.0));
- serverApps.Stop (Seconds (10.0));
-@end verbatim
-
-We now see that @code{echoServer.Install} is going to install an
+We now see that @code{echoServer.Install} is going to install a
@code{UdpEchoServerApplication} on the node found at index number one of the
-@code{NodeContainer} we use to manage our nodes. @code{Install} will return
+@code{NodeContainer} we used to manage our nodes. @code{Install} will return
a container that has all of the applications (one in this case since we passed
a @code{NodeContainer} containing one node) made by the helper.
Applications require a time to ``start'' generating traffic and a time to
``stop.'' These times are set using @code{ApplicationContainer} methods
@code{Start} and @code{Stop}. These methods take @code{Time} parameters.
-In this case, we use an explicit conversion sequence to take a c++ double
-1.0 and convert it to a @code{Time} object using a @code{Seconds ()} cast.
-The two lines,
+In this case, we use an explicit conversion sequence to take the C++ double
+1.0 and convert it to an @command{ns-3} @code{Time} object using a
+@code{Seconds ()} cast. The two lines,
@verbatim
serverApps.Start (Seconds (1.0));
@@ -666,11 +599,11 @@
a simulation event at ten seconds, the simulation will last at least ten
seconds.
-@subsection UdpEchoClientHelper
+@subsubsection UdpEchoClientHelper
-The echo client application is set up in a method similar to the server.
-There is an underlying @code{UdpEchoClientApplication} that is managed by an
-@code{UdpEchoClientHelper}.
+The echo client application is set up in a substantially method similar to the
+server. There is an underlying @code{UdpEchoClientApplication} that is
+managed by an @code{UdpEchoClientHelper}.
@verbatim
UdpEchoClientHelper echoClient;
@@ -684,32 +617,27 @@
clientApps.Stop (Seconds (10.0));
@end verbatim
-For the echo client, we need to set four different attributes. The first
-attribute is set using the @code{SetRemote} method. Here we refer back to
-the @code{Ipv4InterfaceContainer} we created to keep track of the IP addresses
-we assigned to our devices.
-
-@verbatim
- Ipv4InterfaceContainer interfaces = address.Assign (devices);
-@end verbatim
-
-In this case, the zeroth interface in the @code{interfaces} container
-cooresponds to the IP address of the zeroth node in the @code{nodes} container.
-The first interface in the @code{interfaces} container cooresponds to the IP
-address of the first node in the @code{nodes} container. So, in the following
-line of code, we are setting the remote address of the client to be the IP
-address assigned to the node on which the server resides. We tell it to send
-to port nine.
+For the echo client, however, we need to set four different attributes. The
+first attribute is set using the @code{SetRemote} method. Recall that
+we used an @code{Ipv4InterfaceContainer} to keep track of the IP addresses we
+assigned to our devices. As a result of the allocation, the zeroth interface
+in the @code{interfaces} container cooresponds to the IP address of the
+zeroth node in the @code{nodes} container. The first interface in the
+@code{interfaces} container cooresponds to the IP address of the first node in
+the @code{nodes} container. So, in the following line of code (reproduced
+from above), we are setting the remote address of the client to be the IP
+address assigned to the node on which the server resides, and we tell it to
+send packets to port nine.
@verbatim
echoClient.SetRemote (interfaces.GetAddress (1), 9);
@end verbatim
The ``MaxPackets'' attribute tells the client the maximum number of packets
-it can send. The ``Interval'' attribute tells the cleint how long to wait
-between packets and the ``PacketSize'' attribute tells the client how large
-its packets should be. In this case we are telling the client to send one
-1024-byte packet.
+it can send. The ``Interval'' attribute tells the client how long to wait
+between packets, and the ``PacketSize'' attribute tells the client how large
+its packets should be. With this combination of attributes, we are telling
+the client to send one 1024-byte packet.
Just as in the case of the echo server, we tell the echo client to @code{Start}
and @code{Stop}, but here we start the client one second after the server is
@@ -717,14 +645,13 @@
@subsection Simulator
What we need to do at this point is to actually run the simulation. This is
-done using the @code{Simulator} singleton which is accessed via the global
-function @code{Simulator::Run}
+done using the global function @code{Simulator::Run}.
@verbatim
Simulator::Run ();
@end verbatim
-When we called the methods,
+When we previously called the methods,
@verbatim
serverApps.Start (Seconds (1.0));
@@ -735,32 +662,34 @@
@end verbatim
we actually scheduled events in the simulator at 1.0 seconds, 2.0 seconds and
-10.0 seconds. When @code{Simulator::Run} is called, it will begin looking
-through the list of scheduled events and executing them. First it will run
-the event at 1.0 seconds, which will enable the echo server application. Then
-it will run the event scheduled for t=2.0 seconds which will start the echo
-client application. The start event implementation in the echo cleint will
-begin the data transfer phase of the simulation by sending a packet to the
-server.
+10.0 seconds. When @code{Simulator::Run} is called, the ssytem will begin
+looking through the list of scheduled events and executing them. First it
+will run the event at 1.0 seconds, which will enable the echo server
+application. Then it will run the event scheduled for t=2.0 seconds which
+will start the echo client application. The start event implementation in
+the echo client will begin the data transfer phase of the simulation by
+sending a packet to the server.
The act of sending the packet to the server will trigger a chain of events
-which will be automatically scheduled and which will perform the packet echo
-according to the various timing parameters that we have set in the script.
+which will be automatically scheduled and which will perform the mechanics of
+the packet echo according to the various timing parameters that we have set
+in the script.
-Eventually, since we only sent one packet, the chain of events triggered by
-the single client echo request will taper off and the simulation will go
-idle. Once this happens, the remaining events are the @code{Stop} events
+Eventually, since we only send one packet, the chain of events triggered by
+that single client echo request will taper off and the simulation will go
+idle. Once this happens, the remaining events will be the @code{Stop} events
for the server and the client. When these events are executed, there are
no further events to process and @code{Simulator::Run} returns. The simulation
is complete.
-All that remains is to clean up after ourselves. This is done by calling the
-global function @code{Simulator::Destroy}. As the helper functions (or low
-level ns-3 code) executed they arranged it so that hooks were inserted in the
-simulator to destruct all of the objects that were created. You do not have
-to keep track of all of these objects yourself --- all you have to do is to
-call @code{Simulator::Destroy} and exit. The remaining lines of our first
-ns-3 script, @code{first.cc}, do just that
+All that remains is to clean up. This is done by calling the global function
+@code{Simulator::Destroy}. As the helper functions (or low level
+@command{ns-3} code) executed, they arranged it so that hooks were inserted in
+the simulator to destroy all of the objects that were created. You did not
+have to keep track of any of these objects yourself --- all you had to do
+was to call @code{Simulator::Destroy} and exit. The @command{ns-3} system
+took care of the hard part for you. The remaining lines of our first
+@command{ns-3} script, @code{first.cc}, do just that:
@verbatim
Simulator::Destroy ();
@@ -768,12 +697,14 @@
}
@end verbatim
-@section Building Your Script
+@subsection Building Your Script
We have made it trivial to build your simple scripts. All you have to do is
-to drop your script into the scratch directory and it will automatically be built. Let's try it. Copy @code{examples/first.cc} into @code{scratch}:
+to drop your script into the scratch directory and it will automatically be
+built if you run Waf. Let's try it. Copy @code{examples/first.cc} into
+the @code{scratch} directory.
@verbatim
- ~/repos/ns-3-tutorial > cp examples/first.cc scratch
+ ~/repos/ns-3-tutorial > cp examples/first.cc scratch/
@end verbatim
and then build it using waf,
@@ -782,8 +713,7 @@
~/repos/ns-3-tutorial > ./waf
Entering directory `/home/craigdo/repos/ns-3-tutorial/build'
[432/477] cxx: scratch/first.cc -> build/debug/scratch/first_2.o
- [433/477] cxx: scratch/simple.cc -> build/debug/scratch/simple_3.o
- [475/477] cxx_link: build/debug/scratch/first_2.o -> build/debug/scratch/first
+ [475/477] cxx_link: build/debug/scratch/first_2.o ...
Compilation finished successfully
~/repos/ns-3-tutorial >
@end verbatim
@@ -803,7 +733,8 @@
Here you see that the build system checks to make sure that the file has been
build and then runs it. You see the logging component on the echo client
-note that it has sent one 1024 byte packet to the Echo Server on 10.1.1.2.
-You also see the logging component on the echo server receive the 1024 bytes
-from 10.1.1.1. The echo server silently echoes the packet and you see the
-echo client note that it has received its packet back from the server.
+indicate that it has sent one 1024 byte packet to the Echo Server on
+10.1.1.2. You also see the logging component on the echo server say that
+it has received the 1024 bytes from 10.1.1.1. The echo server silently
+echoes the packet and you see the echo client log that it has received its
+packet back from the server.
--- a/doc/tutorial/getting-started.texi Sun Jun 29 20:48:18 2008 -0700
+++ b/doc/tutorial/getting-started.texi Sun Jun 29 21:22:33 2008 -0700
@@ -16,18 +16,18 @@
@chapter Getting Started
@menu
-* Downloading and Compiling ns-3::
-* Downloading::
-* Building and Testing::
+* Downloading ns-3::
+* Building ns-3::
+* Testing ns-3::
* Running a Script::
@end menu
@c ========================================================================
-@c Downloading and Compiling ns-3
+@c Downloading ns-3
@c ========================================================================
-@node Downloading and Compiling ns-3
-@section Downloading and Compiling ns-3
+@node Downloading ns-3
+@section Downloading ns-3
@cindex Linux
@cindex Cygwin
@@ -41,30 +41,29 @@
@cindex Waf
We are 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
-ns-3 web site: @uref{http://www.nsnam.org/getting_started.html}.
+@command{ns-3} web site: @uref{http://www.nsnam.org/getting_started.html}.
-@node Downloading
-@section Downloading
@cindex tarball
-The ns-3 code is available in Mercurial repositories on the server
+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.
@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 ns-3 development team. The repositories of interest to you will be
-prefixed with ``ns-3''. The current development snapshot (unreleased)
-of ns-3 may be found at: @uref{http://code.nsnam.org/ns-3-dev/}. Official
-releases of ns-3 will be numbered as @code{ns-3.<release>} with any requred
-hotfixes added as minor release numbers. For example, a second hotfix to a
-hypothetical release nine of ns-3 would be numbered @code{ns-3.9.2}.
+the @comamnd{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 requred 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 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.
+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.
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
@@ -76,14 +75,14 @@
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 any of the development versions of ns-3
-by typing the following into your Linux shell (assuming you have installed
-Mercurial):
+that approach, you can get a copy of any of the development versions of
+@command{ns-3} by typing the following into your Linux shell (assuming you
+have installed Mercurial):
@verbatim
cd
mkdir repos
- cd !$
+ cd repos
hg clone http://code.nanam.org/ns-3-dev
@end verbatim
@@ -104,33 +103,38 @@
look something like the following:
@verbatim
- AUTHORS LICENSE regression/ scratch/ utils/ waf.bat*
- doc/ ns3/ RELEASE_NOTES src/ VERSION wscript
- examples/ README samples/ tutorial/ waf*
+ AUTHORS examples/ README samples/ utils/ waf.bat*
+ build/ LICENSE regression/ scratch/ VERSION wscript
+ doc/ ns3/ RELEASE_NOTES src/ waf*
@end verbatim
-You are now ready to build the ns-3 distribution.
+You are now ready to build the @command{ns-3} distribution.
-@node Building and Testing
-@section Building and Testing
+@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 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 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 the copy of Waf in 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,
+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
~/repos/ns-3-dev >./waf -d debug configure
@@ -162,7 +166,7 @@
@end verbatim
The build system is now configured and you can build the debug versions of
-the ns-3 programs by simply typing,
+the @command{ns-3} programs by simply typing,
@verbatim
./waf check
@@ -175,8 +179,15 @@
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 ns-3 distribution by running the ``check''
+You can run the unit tests of the @command{ns-3} distribution by running the ``check''
command,
@verbatim
@@ -203,8 +214,8 @@
@end verbatim
@cindex regression tests
-This command is typically run by @code{users} to quickly verify that an ns-3
-distribution has built correctly.
+This command is typically run by @code{users} to quickly verify that an
+@command{ns-3} distribution has built correctly.
You can also run @code{regression tests} to ensure that your distribution and
tool chain have produced binaries that generate trace files which are
@@ -215,14 +226,15 @@
./waf --regression
@end verbatim
-Waf will verify that the current files in the 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 @code{releases} section of @code{www.nsnam.org}. The particular name of
-the reference trace location is built from the ns-3 version located in the
-VERSION file, so don't change that string.
+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 @code{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.
Once the reference traces are downloaded to your local machine, Waf will run
a number of tests that generate trace files. The content of these trace
@@ -254,14 +266,18 @@
pointer to the offending trace file and its associated reference trace file
along with a suggestion on how to run diff in order to see what has gone awry.
+@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 ns-3 equivalent of the hello
-world program by typing the following:
+@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
--- a/doc/tutorial/introduction.texi Sun Jun 29 20:48:18 2008 -0700
+++ b/doc/tutorial/introduction.texi Sun Jun 29 21:22:33 2008 -0700
@@ -21,12 +21,13 @@
* Tutorial Organization::
@end menu
-The ns-3 simulator is a discrete-event network simulator targeted primarily
-for research and educational use. The
+The @command{ns-3} simulator is a discrete-event network simulator targeted
+primarily for research and educational use. The
@uref{http://www.nsnam.org,,ns-3 project},
started in 2006, is an open-source project developing ns-3.
-Primary documentation for the ns-3 project is available in four forms:
+Primary documentation for the @command{ns-3} project is available in four
+forms:
@itemize @bullet
@item @uref{http://www.nsnam.org/doxygen/index.html,,ns-3 Doxygen/Manual}:
Documentation of the public APIs of the simulator
@@ -35,7 +36,7 @@
@item @uref{http://www.nsnam.org/wiki/index.php,, ns-3 wiki}
@end itemize
-The purpose of this tutorial is to introduce new ns-3 users to the
+The purpose of this tutorial is to introduce new @command{ns-3} users to the
system in a structured way. It is sometimes difficult for new users to
glean essential information from detailed manuals and to convert this
information into working simulations. In this tutorial, we will build
@@ -48,52 +49,52 @@
A few key points are worth noting at the onset:
@itemize @bullet
-@item ns-3 is not an extension of @uref{http://www.isi.edu/nsnam/ns,,ns-2};
-it is a new simulator. The two simulators are both written in C++ but ns-3
-is a new simulator that does not support the ns-2 APIs. Some models from ns-2
-have already been ported from ns-2 to ns-3. The project will continue to
-maintain ns-2 while ns-3 is being built, and will study transition and
-integration mechanisms.
-@item ns-3 is open-source, and the project strives to maintain an open
-environment for researchers to contribute and share their software.
+@item Ns-3 is not an extension of @uref{http://www.isi.edu/nsnam/ns,,ns-2};
+it is a new simulator. The two simulators are both written in C++ but
+@command{ns-3} is a new simulator that does not support the ns-2 APIs. Some
+models from ns-2 have already been ported from ns-2 to ns-3. The project will
+continue to maintain ns-2 while ns-3 is being built, and will study transition
+and integration mechanisms.
+@item @command{Ns-3} is open-source, and the project strives to maintain an
+open environment for researchers to contribute and share their software.
@end itemize
@node For ns-2 Users
@section For ns-2 Users
For those familiar with ns-2, the most visible outward change when moving to
-ns-3 is the choice of scripting language. ns-2 is typically scripted in Tcl
-and results of simulations can be visualized using the Network Animator
-@command{nam}. In ns-3 there is currently no visualization module, and Python
-bindings have been developed (Tcl bindings have been prototyped
-using @uref{http://www.swig.org,,SWIG}, but are not supported by the
-current development team). In this tutorial, we will concentrate on
-scripting directly in C++ and interpreting results via trace files.
+@command{ns-3} is the choice of scripting language. Ns-2 is typically
+scripted in Tcl and results of simulations can be visualized using the
+Network Animator @command{nam}. In @command{ns-3} there is currently no
+visualization module, and Python bindings have been developed (Tcl bindings
+have been prototyped using @uref{http://www.swig.org,,SWIG}, but are not
+currently supported). In this tutorial, we will concentrate on scripting
+directly in C++ and interpreting results via trace files.
-But there are similarities as well (both, for example, are based
-on C++ objects, and some code from ns-2 has already been ported
-to ns-3). We will try to highlight differences between ns-2 and ns-3
+But there are similarities as well (both, for example, are based on C++
+objects, and some code from ns-2 has already been ported to @command{ns-3}).
+We will try to highlight differences between ns-2 and @command{ns-3}
as we proceed in this tutorial.
@node Contributing
@section Contributing
@cindex contributing
-ns-3 is a research and educational simulator, by and for the research
-community. It will rely on the ongoing contributions of the community to
-develop new models, debug or maintain existing ones, and share results. There
-are a few policies that we hope will encourage people to contribute to ns-3
-like they have for ns-2:
+@command{Ns-3} is a research and educational simulator, by and for the
+research community. It will rely on the ongoing contributions of the
+community to develop new models, debug or maintain existing ones, and share
+results. There are a few policies that we hope will encourage people to
+contribute to @command{ns-3} like they have for ns-2:
@itemize @bullet
-@item open source licensing based on GNU GPLv2 compatibility
-@item @uref{http://www.nsnam.org/wiki/index.php,,wiki}
+@item Open source licensing based on GNU GPLv2 compatibility;
+@item @uref{http://www.nsnam.org/wiki/index.php,,wiki};
@item @uref{http://www.nsnam.org/wiki/index.php/Contributed_Code,,Contributed Code} page, similar to ns-2's popular
@uref{http://nsnam.isi.edu/nsnam/index.php/Contributed_Code,,Contributed Code}
-page
-@item @code{src/contrib} directory (we will host your contributed code)
-@item open @uref{http://www.nsnam.org/bugzilla,,bug tracker}
-@item ns-3 developers will gladly help potential contributors to get
-started with the simulator (please contact @uref{http://www.nsnam.org/people.html,,one of us})
+page;
+@item @code{src/contrib} directory (we will host your contributed code);
+@item Open @uref{http://www.nsnam.org/bugzilla,,bug tracker};
+@item @command{Ns-3} developers will gladly help potential contributors to get
+started with the simulator (please contact @uref{http://www.nsnam.org/people.html,,one of us}).
@end itemize
If you are an ns-3 user, please consider providing your feedback, bug fixes, or
@@ -110,7 +111,7 @@
the simulator and what it might be like to use;
@item Try to download and build a copy;
@item Try to run a few sample programs, and perhaps change some configurations;
-@item Look at simulation output, and try to adjust it
+@item Look at simulation output, and try to adjust it.
@end itemize
As a result, we have tried to organize the tutorial along the above
@@ -138,7 +139,8 @@
these repositories, and links to the @emph{manifest}. From the manifest
links, one can browse the source tree.
-The top-level directory will look something like:
+The top-level directory for one of our @emph{repositories} will look
+something like:
@verbatim
drwxr-xr-x [up]
drwxr-xr-x doc manifest
@@ -185,7 +187,8 @@
@section Other Documentation
We provide a large amount of documentation regarding the various components
-of ns-3 on our website. See: @uref{http://www.nsnam.org/documents.html}.
+of @command{ns-3} on our website. See:
+@uref{http://www.nsnam.org/documents.html}.
@c ========================================================================
@c Resources
@@ -206,28 +209,26 @@
@section The Web
@cindex www.nsnam.org
-There are several important resources of which any ns-3 user must be
-aware. The main web site is located at @uref{http://www.nsnam.org}
-and provides access to basic information about the ns-3 system.
-Detailed documentation is available through the main web site at
+There are several important resources of which any @command{ns-3} user must be
+aware. The main web site is located at @uref{http://www.nsnam.org} and
+provides access to basic information about the ns-3 system. Detailed
+documentation is available through the main web site at
@uref{http://www.nsnam.org/documents.html}.
@cindex documentation
@cindex architecture
You can find documents relating to the system architecture from this page,
-and also gain access to the detailed software documentation. The software
-system is documented in great detail using
-@uref{http://www.stack.nl/~dimitri/doxygen/,,Doxygen}. There is a Wiki that
-complements the main ns-3 web site which you will find at
+and also gain access to the detailed software documentation. There is a Wiki
+that complements the main ns-3 web site which you will find at
@uref{http://www.nsnam.org/wiki/}.
-You will find user and developer FAQs there as well as troubleshooting guides,
-third-party contributed code, papers, etc. The source code may be found
-and browsed at @uref{http://code.nsnam.org/}.
+You will find user and developer FAQs there, as well as troubleshooting
+guides, third-party contributed code, papers, etc.
@cindex mercurial repository
@cindex ns-3-dev repository
@cindex release repository
+The source code may be found and browsed at @uref{http://code.nsnam.org/}.
There you will find the current development tree in the repository named
@code{ns-3-dev}. Past releases and experimental repositories of the core
developers may also be found there.
@@ -243,7 +244,7 @@
@cindex software configuration management
@cindex Mercurial
-The ns-3 project uses Mercurial as its source code management system.
+The @command{ns-3} project uses Mercurial as its source code management system.
Although you do not need to know much about Mercurial in order to complete
this tutorial, we recommend becoming familiar with Mercurial and using it
to access the source code. Mercurial has a web site at
@@ -255,8 +256,8 @@
and a QuickStart guide at
@uref{http://www.selenic.com/mercurial/wiki/index.cgi/QuickStart/}.
-You can also find vital information about using Mercurial and ns-3
-on the main ns-3 web site.
+You can also find vital information about using Mercurial and @command{ns-3}
+on the main @command{ns-3} web site.
@node Waf
@section Waf
@@ -273,7 +274,7 @@
alternatives have been developed. Recently these systems have been developed
using the Python language.
-The build system @code{Waf} is used on the ns-3 project. It is one
+The build system @code{Waf} is used on the @command{ns-3} project. It is one
of the new generation of Python-based build systems. You will not need to
understand any Python to build the existing ns-3 system, and will
only have to understand a tiny and intuitively obvious subset of Python in
@@ -303,15 +304,15 @@
@cindex toolchain
@cindex GNU
-The ns-3 system uses the GNU ``toolchain'' for development.
-A software toolchain is the set of programming tools available in the given
+The @command{ns-3} system uses 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}.
@cindex Linux
-Typically an ns-3 author will work in Linux or a Linux-like
+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 ns-3
+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
@@ -332,7 +333,7 @@
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.
+running. Beware of Logitech software.
@node Socket Programming
@section Socket Programming
@@ -352,5 +353,5 @@
the website above) you will be in good shape to understand the tutorial.
There is a similar book on Multicast Sockets,
@uref{http://www.elsevier.com/wps/product/cws_home/700736,,Multicast Sockets, Makofske and Almeroth}.
-that covers material you may need to understand for the multicast examples.
-
+that covers material you may need to understand for the multicast examples in
+the distribution.