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

editing pass through the tutorial

Browse Source
This commit is contained in:
Craig Dowell
2008-06-29 21:16:35 -07:00
parent 73e368454d
commit bdb123bbc4
4 changed files with 364 additions and 411 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -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 Overveiw
@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 @@ goal.
@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 @@ In the real world, one can connect a computer to a network. Often the media
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 @@ specialization may model something as simple as a wire. The specialized
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 @@ devices (NICs) are controlled using @emph{network device drivers}
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 @@ multiple @code{NetDevice}s.
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 @@ formatting conventions (coding style) we use in our source code.
@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 @@ distribution.
*/
@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 @@ include file that, in turn, includes all of the include files used in each
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 @@ you do a build, Waf will place public header files in an @code{ns3} directory
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 @@ that version.
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 @@ the documentation here, but to summarize, this line declares a logging
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 @@ The next lines of the script you will find are:
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 @@ are built into the Echo Client and Echo Server applications:
@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 @@ The first line
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 @@ to what we call an @code{Attribute} of the @code{PointToPointNetDevice}.
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 @@ is created. For each node in the @code{NodeContainer} (there must be exactly
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 @@ what the @code{PointToPointHelper} is to point-to-point net devices. The
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 @@ The next two lines of code in our example script, @code{first.cc},
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 @@ The next line of code,
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 @@ created and connected using a point-to-point link.
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 @@ causes the underlying echo server application to be instantiated and attached
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.
doesn't look so in this case. There is a C++ @emph{implicit conversion} at
work 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:
@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 @@ into the simulation. By virtue of the fact that we have implicilty declared
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 @@ There is an underlying @code{UdpEchoClientApplication} that is managed by an
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 @@ enabled (at two seconds into the simulation).
@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 @@ When we called the methods,
@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 @@ ns-3 script, @code{first.cc}, do just that
}
@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 @@ and then build it using waf,
~/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 @@ directory you must run it out of the scratch direcory):
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.

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

@@ -16,15 +16,18 @@
@chapter Getting Started
@menu
* Downloading and Compiling ns-3::
* 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
@@ -38,29 +41,29 @@ toolchain installed and verified.
@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}.
@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
@@ -72,14 +75,14 @@ for the latest release identifier.
One practice is to create a directory called @code{repos} in one's home
directory under which one can keep local Mercurial repositories.
@emph{Hint: we will assume you do this later in the tutorial.} If you adopt
that approach, you can get a copy of 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
@@ -100,32 +103,38 @@ ns-3-dev under your @code{~/repos} directory, the contents of which should
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.
@c ========================================================================
@c Building ns-3
@c ========================================================================
@node Building ns-3
@section Building ns-3
@section Building and Testing
@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
@@ -157,7 +166,7 @@ you should see output that looks similar to the following,
@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
@@ -170,8 +179,15 @@ most important is the last one,
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
@@ -198,8 +214,8 @@ test has passed.
@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
@@ -210,14 +226,15 @@ regression tests you run Waf with the regression flag.
./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
@@ -249,13 +266,17 @@ If a regression tests fails you will see a FAIL indication along with a
pointer to the offending trace file and its associated reference trace file
along with a suggestion on how to run diff in order to see what has gone awry.
@c ========================================================================
@c Testing ns-3
@c ========================================================================
@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

125
doc/tutorial/introduction.texi
View File

@@ -21,13 +21,14 @@
* 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. The goal of the project is to
build a new network simulator primarily for research and educational use.
Primary documentation for the ns-3 project is available in three forms:
Primary documentation for the @command{ns-3} project is available in three
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 @@ Documentation of the public APIs of the simulator
@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 @@ into the workings of the system.
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 user, please consider providing your feedback, bug fixes, or
@@ -110,7 +111,7 @@ following:
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 @@ repository names on the left of the page, you will see @emph{changelogs} for
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
@@ -175,9 +177,9 @@ Example scripts are in the @code{examples} directory. The @code{examples}
directory is a good place to start browsing the code.
For ns-2 users, who may be familiar with the @code{simple.tcl} example script
in the ns-2 documentation, an analogous script is found in
@code{examples/simple-point-to-point.cc} with a Python equivalent found
in @emph{(pending Python merge)}.
in the ns-2 documentation, a roughly analogous script is found in
@code{examples/first.cc} with a Python equivalent found in
@emph{(pending Python merge)}.
@node Doxygen
@section Doxygen
@@ -190,7 +192,8 @@ look.
@section Other Documentation
We provide a large amount of documentation regarding the various components
of ns-2 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
@@ -211,28 +214,26 @@ of ns-2 on our website. See: @uref{http://www.nsnam.org/documents.html}.
@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.
@@ -248,7 +249,7 @@ the most well known.
@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
@@ -260,8 +261,8 @@ also provides a tutorial at
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
@@ -278,7 +279,7 @@ use in a very large and highly configurable system. Because of this, many
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
@@ -308,15 +309,15 @@ before proceeding.
@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
@@ -337,7 +338,7 @@ crash creating a sh.exe.stackdump file when I try to compile my source code.''
Believe it or not, the @code{Logitech Process Monitor} insinuates itself into
every DLL in the system when it is running. It can cause your Cygwin or
MinGW DLLs to die in mysterious ways and often prevents debuggers from
running. Beware of Logitech.
running. Beware of Logitech software.
@node Socket Programming
@section Socket Programming
@@ -357,5 +358,5 @@ not have access to a copy of the book, the echo clients and servers shown in
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.

16
doc/tutorial/tutorial.texi
View File

@@ -14,10 +14,10 @@ three forms:
@item @uref{http://www.nsnam.org/wiki/index.php,, ns-3 wiki}
@end itemize
This document is written in GNU Texinfo and is to be maintained in
revision control on the @command{ns-3} code server. Both PDF and HTML versions
should be available on the server. Changes to
the document should be discussed on the ns-developers@@isi.edu mailing list.
This document is written in GNU Texinfo and is to be maintained in revision
control on the @command{ns-3} code server. Both PDF and HTML versions should
be available on the server. Changes to the document should be discussed on
the ns-developers@@isi.edu mailing list.
@end ifinfo
@copying
@@ -31,10 +31,10 @@ three forms:
@item @uref{http://www.nsnam.org/wiki/index.php,, ns-3 wiki}
@end itemize
This document is written in GNU Texinfo and is to be maintained in
revision control on the @command{ns-3} code server. Both PDF and HTML
versions should be available on the server. Changes to
the document should be discussed on the ns-developers@@isi.edu mailing list.
This document is written in GNU Texinfo and is to be maintained in revision
control on the @command{ns-3} code server. Both PDF and HTML versions should
be available on the server. Changes to the document should be discussed on
the ns-developers@@isi.edu mailing list.
This software is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by