--- a/doc/tutorial/building-topologies.texi Wed Jul 01 12:47:40 2009 +0200
+++ b/doc/tutorial/building-topologies.texi Wed Jul 01 23:08:07 2009 -0700
@@ -61,7 +61,6 @@
#include "ns3/simulator-module.h"
#include "ns3/node-module.h"
#include "ns3/helper-module.h"
- #include "ns3/global-routing-module.h"
@end verbatim
One thing that can be surprisingly useful is a small bit of ASCII art that
@@ -294,10 +293,11 @@
@end verbatim
Since we have actually built an internetwork here, we need some form of
-internetwork routing. @command{ns-3} provides what we call a global route
-manager to set up the routing tables on nodes. This route manager has a
-global function that runs through the nodes created for the simulation and does
-the hard work of setting up routing for you.
+internetwork routing. @command{ns-3} provides what we call global routing to
+help you out. Global routing takes advantage of the fact that the entire
+internetwork is accessible in the simulation and runs through the all of the
+nodes created for the simulation --- it does the hard work of setting up routing
+for you without having to configure routers.
Basically, what happens is that each node behaves as if it were an OSPF router
that communicates instantly and magically with all other routers behind the
@@ -307,7 +307,7 @@
is a one-liner:
@verbatim
- GlobalRouteManager::PopulateRoutingTables ();
+ Ipv4GlobalRoutingHelper::PopulateRoutingTables ();
@end verbatim
Next we enable pcap tracing. The first line of code to enable pcap tracing
@@ -329,8 +329,8 @@
one of the devices and place it in promiscuous mode. That single device
then ``sniffs'' the network for all packets and stores them in a single
pcap file. This is how @code{tcpdump}, for example, works. That final
-parameter tells the CSMA helper whether or not to capture packets in
-promiscuous mode.
+parameter tells the CSMA helper whether or not to arrange to capture
+packets in promiscuous mode.
In this example, we are going to select one of the devices on the CSMA
network and ask it to perform a promiscuous sniff of the network, thereby
@@ -350,10 +350,10 @@
}
@end verbatim
-In order to run this example, you have to copy the @code{second.cc} example
-script into the scratch directory and use waf to build just as you did with
+In order to run this example, copy the @code{second.cc} example script into
+the scratch directory and use waf to build just as you did with
the @code{first.cc} example. If you are in the top-level directory of the
-repository you would type,
+repository you just type,
@verbatim
cp examples/second.cc scratch/mysecond.cc
@@ -380,18 +380,19 @@
@code{first.cc}, you will see similar output when you run the script.
@verbatim
- Entering directory `repos/ns-3-allinone/ns-3-dev/build'
- Build finished successfully (00:00:00)
+ Waf: Entering directory `/home/craigdo/repos/ns-3-allinone-3.5-tutorial/ns-3-dev/build'
+ Waf: Leaving directory `/home/craigdo/repos/ns-3-allinone-3.5-tutorial/ns-3-dev/build'
+ 'build' finished successfully (0.415s)
Sent 1024 bytes to 10.1.2.4
Received 1024 bytes from 10.1.1.1
Received 1024 bytes from 10.1.2.4
@end verbatim
-Recall that the first message, @code{Sent 1024 bytes to 10.1.2.4} is the
+Recall that the first message, ``@code{Sent 1024 bytes to 10.1.2.4},'' is the
UDP echo client sending a packet to the server. In this case, the server
-is on a different network (10.1.2.0). The second message, @code{Received 1024
-bytes from 10.1.1.1}, is from the UDP echo server, generated when it receives
-the echo packet. The final message, @code{Received 1024 bytes from 10.1.2.4}
+is on a different network (10.1.2.0). The second message, ``@code{Received 1024
+bytes from 10.1.1.1},'' is from the UDP echo server, generated when it receives
+the echo packet. The final message, ``@code{Received 1024 bytes from 10.1.2.4},''
is from the echo client, indicating that it has received its echo back from
the server.
@@ -483,8 +484,8 @@
doesn't know the MAC address of the corresponding node. It broadcasts on the
CSMA network (ff:ff:ff:ff:ff:ff) asking for the device that has IP address
10.1.2.4. In this case, the rightmost node replies saying it is at MAC address
-00:00:00:00:00:06. (Note that node two is not directly involved in this
-exchange, but is sniffing the network and reporting all of the traffic it sees.)
+00:00:00:00:00:06. Note that node two is not directly involved in this
+exchange, but is sniffing the network and reporting all of the traffic it sees.
This exchange is seen in the following lines,
@@ -559,8 +560,9 @@
You should now see,
@verbatim
- Entering directory `repos/ns-3-allinone/ns-3-dev/build'
- Build finished successfully (00:00:00)
+ Waf: Entering directory `/home/craigdo/repos/ns-3-allinone-3.5-tutorial/ns-3-dev/build'
+ Waf: Leaving directory `/home/craigdo/repos/ns-3-allinone-3.5-tutorial/ns-3-dev/build'
+ 'build' finished successfully (0.405s)
Sent 1024 bytes to 10.1.2.5
Received 1024 bytes from 10.1.1.1
Received 1024 bytes from 10.1.2.5
@@ -572,7 +574,7 @@
It is possible that you may not be satisfied with a trace file generated by
a bystander in the CSMA network. You may really want to get a trace from
a single device and you may not be interested in any other traffic on the
-network. You can do this,
+network. You can do this fairly easily/
Let's take a look at @code{scratch/mysecond.cc} and add that code enabling us
to be more specific. @code{ns-3} helpers provide methods that take a node
@@ -615,6 +617,14 @@
documentation for the method. Using the @code{GetId} method can make
determining node numbers much easier in complex topologies.
+Let's clear the old trace files out of the top-level directory to avoid confusion
+about what is going on,
+
+@verbatim
+ rm *.pcap
+ rm *.tr
+@end verbatim
+
If you build the new script and run the simulation setting @code{nCsma} to 100,
@verbatim
@@ -624,8 +634,9 @@
you will see the following output:
@verbatim
- Entering directory `repos/ns-3-allinone/ns-3-dev/build'
- Build finished successfully (00:00:00)
+ Waf: Entering directory `/home/craigdo/repos/ns-3-allinone-3.5-tutorial/ns-3-dev/build'
+ Waf: Leaving directory `/home/craigdo/repos/ns-3-allinone-3.5-tutorial/ns-3-dev/build'
+ 'build' finished successfully (0.407s)
Sent 1024 bytes to 10.1.2.101
Received 1024 bytes from 10.1.1.1
Received 1024 bytes from 10.1.2.101
@@ -659,9 +670,27 @@
entire CSMA network.
@verbatim
-reading from file second-100-0.pcap, link-type EN10MB (Ethernet)
-2.003696 arp who-has 10.1.2.101 (ff:ff:ff:ff:ff:ff) tell 10.1.2.1
-2.003811 arp who-has 10.1.2.1 (ff:ff:ff:ff:ff:ff) tell 10.1.2.101
+ reading from file second-100-0.pcap, link-type EN10MB (Ethernet)
+ 2.003696 arp who-has 10.1.2.101 (ff:ff:ff:ff:ff:ff) tell 10.1.2.1
+ 2.003811 arp who-has 10.1.2.1 (ff:ff:ff:ff:ff:ff) tell 10.1.2.101
+@end verbatim
+
+Now take a look at the @code{tcpdump} for @code{second-101-0.pcap}.
+
+@verbatim
+ tcpdump -nn -tt -r second-101-0.pcap
+@end verbatim
+
+You can now see that node 101 is really the participant in the echo exchange.
+
+@verbatim
+ reading from file second-101-0.pcap, link-type EN10MB (Ethernet)
+ 2.003696 arp who-has 10.1.2.101 (ff:ff:ff:ff:ff:ff) tell 10.1.2.1
+ 2.003696 arp reply 10.1.2.101 is-at 00:00:00:00:00:67
+ 2.003801 IP 10.1.1.1.49153 > 10.1.2.101.9: UDP, length 1024
+ 2.003801 arp who-has 10.1.2.1 (ff:ff:ff:ff:ff:ff) tell 10.1.2.101
+ 2.003822 arp reply 10.1.2.1 is-at 00:00:00:00:00:03
+ 2.003822 IP 10.1.2.101.9 > 10.1.1.1.49153: UDP, length 1024
@end verbatim
@c ========================================================================
@@ -714,7 +743,6 @@
#include "ns3/simulator-module.h"
#include "ns3/node-module.h"
#include "ns3/helper-module.h"
-#include "ns3/global-routing-module.h"
#include "ns3/wifi-module.h"
#include "ns3/mobility-module.h"
@end verbatim
@@ -1035,14 +1063,15 @@
just as we did in the @code{second.cc} example script.
@verbatim
- GlobalRouteManager::PopulateRoutingTables ();
+ Ipv4GlobalRoutingHelper::PopulateRoutingTables ();
@end verbatim
One thing that can surprise some users is the fact that the simulation we just
created will never ``naturally'' stop. This is because we asked the wireless
-access point to generate beacons. It will generate beacons forever, so we must
-tell the simulator to stop even though it may have beacon generation events
-scheduled. The following line of code tells the simulator to stop so that
+access point to generate beacons. It will generate beacons forever, and this
+will result in simulator events being scheduled into the future indefinitely,
+so we must tell the simulator to stop even though it may have beacon generation
+events scheduled. The following line of code tells the simulator to stop so that
we don't simulate beacons forever and enter what is essentially an endless
loop.
@@ -1054,7 +1083,7 @@
@verbatim
PointToPointHelper::EnablePcapAll ("third");
- YansWifiPhyHelper::EnablePcap ("third", apDevices.Get (0));
+ phy.EnablePcap ("third", apDevices.Get (0));
CsmaHelper::EnablePcap ("third", csmaDevices.Get (0), true);
@end verbatim
@@ -1084,27 +1113,28 @@
./waf --run scratch/mythird
@end verbatim
-Since we have set up the UDP echo applications just as we did in the
+Again, since we have set up the UDP echo applications just as we did in the
@code{second.cc} script, you will see similar output.
@verbatim
- Entering directory `repos/ns-3-allinone-dev/ns-3-dev/build'
- Build finished successfully (00:00:00)
+ Waf: Entering directory `/home/craigdo/repos/ns-3-allinone-3.5-tutorial/ns-3-dev/build'
+ Waf: Leaving directory `/home/craigdo/repos/ns-3-allinone-3.5-tutorial/ns-3-dev/build'
+ 'build' finished successfully (0.407s)
Sent 1024 bytes to 10.1.2.4
Received 1024 bytes from 10.1.3.3
Received 1024 bytes from 10.1.2.4
@end verbatim
-Recall that the first message, @code{Sent 1024 bytes to 10.1.2.4} is the
+Recall that the first message, ``@code{Sent 1024 bytes to 10.1.2.4},'' is the
UDP echo client sending a packet to the server. In this case, the client
is on the wireless network (10.1.3.0). The second message,
-@code{Received 1024 bytes from 10.1.3.3}, is from the UDP echo server,
+``@code{Received 1024 bytes from 10.1.3.3},'' is from the UDP echo server,
generated when it receives the echo packet. The final message,
-@code{Received 1024 bytes from 10.1.2.4} is from the echo client, indicating
+``@code{Received 1024 bytes from 10.1.2.4},'' is from the echo client, indicating
that it has received its echo back from the server.
If you now go and look in the top level directory, you will find four trace
-files, two from node zero and two from node one:
+files from this simulation, two from node zero and two from node one:
@verbatim
third-0-0.pcap third-0-1.pcap third-1-0.pcap third-1-1.pcap
@@ -1223,8 +1253,8 @@
Now, we spent a lot of time setting up mobility models for the wireless network
and so it would be a shame to finish up without even showing that the STA
-nodes are actually moving around. Let's do this by hooking into the
-@code{MobilityModel} course change trace source. This is usually considered
+nodes are actually moving around during the simulation. Let's do this by hooking
+into the @code{MobilityModel} course change trace source. This is usually considered
a fairly advanced topic, but let's just go for it.
As mentioned in the ``Tweaking ns-3'' section, the @command{ns-3} tracing system
@@ -1273,8 +1303,8 @@
/NodeList/7/$ns3::MobilityModel/CourseChange
@end verbatim
-Based on the discussion in the tracing section, you can easily infer that
-this trace path references the seventh node in the NodeList. It specifies
+Based on the discussion in the tracing section, you may infer that this trace
+path references the seventh node in the global NodeList. It specifies
what is called an aggregated object of type @code{ns3::MobilityModel}. The
dollar sign prefix implies that the MobilityModel is aggregated to node seven.
The last component of the path means that we are hooking into the
@@ -1336,6 +1366,6 @@
discussed.
We have just scratched the surface of @command{ns-3} in this tutorial, but we
-hope we have covered enough to get you started doing useful work.
+hope we have hopefully covered enough to get you started doing useful work.
-- The @command{ns-3} development team.
--- a/doc/tutorial/conceptual-overview.texi Wed Jul 01 12:47:40 2009 +0200
+++ b/doc/tutorial/conceptual-overview.texi Wed Jul 01 23:08:07 2009 -0700
@@ -110,7 +110,7 @@
you had to buy a specific kind of network cable and a hardware device called
(in PC terminology) a @emph{peripheral card} that needed to be installed in
your computer. If the peripheral card implemented some networking function,
-theys were called Network Interface Cards, or @emph{NICs}. Today most
+they were called Network Interface Cards, or @emph{NICs}. Today most
computers come with the network interface hardware built in and users don't
see these building blocks.
@@ -174,9 +174,10 @@
directory structure something like the following:
@verbatim
- AUTHORS examples/ README samples/ utils/ waf.bat*
- build/ LICENSE regression/ scratch/ VERSION wscript
- doc/ ns3/ RELEASE_NOTES src/ waf*
+ AUTHORS doc/ README RELEASE_NOTES utils/ wscript
+ bindings/ examples/ regression/ samples/ VERSION wutils.py
+ build/ LICENSE regression.py scratch/ waf* wutils.pyc
+ CHANGES.html ns3/ regression.pyc src/ waf.bat*
@end verbatim
@cindex first.cc
@@ -276,7 +277,7 @@
@end verbatim
to build the project. So now if you look in the directory
-@code{build/debug/ns3} you will find the four module include files shown
+@code{../build/debug/ns3} you will find the four module include files shown
above. You can take a look at the contents of these files and find that they
do include all of the public include files in their respective modules.
@@ -310,16 +311,18 @@
documentation system. If you look at the project web site,
@uref{http://www.nsnam.org,,ns-3 project}, you will find a link to ``Doxygen
(ns-3-dev)'' in the navigation bar. If you select this link, you will be
-taken to our documentation page.
+taken to our documentation page for the current development release. There
+is also a link to ``Doxygen (stable)'' that will take you to the documentation
+for the latest stable release of @code{ns-3}.
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 @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, expand the @code{Debugging} book and then
-select the @code{Logging} page.
+``book'' in the @code{ns-3} navigation tree. 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, expand 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 at the top of the page you will see the entry
@@ -437,7 +440,7 @@
pointToPoint.SetDeviceAttribute ("DataRate", StringValue ("5Mbps"));
@end verbatim
-tells the @code{PointToPointHelper} object to use the value ``5mbps''
+tells the @code{PointToPointHelper} object to use the value ``5Mbps''
(five megabits per second) as the ``DataRate'' when it creates a
@code{PointToPointNetDevice} object.
@@ -492,7 +495,7 @@
created objects.
After executing the @code{pointToPoint.Install (nodes)} call we will have
-two nodes, each with an installed point-to-point net device and a
+two nodes, each with an installed point-to-point net device and a single
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.
@@ -576,13 +579,13 @@
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 used to help us create the actual applications. One of our
-conventions is to place required @code{Attributes} in the helper constructor.
+conventions is to place @emph{required} @code{Attributes} in the helper constructor.
In this case, the helper can't do anything useful unless it is provided with
a port number that the client also knows about. Rather than just picking one
and hoping it all works out, we require the port number as a parameter to the
constructor. The constructor, in turn, simply does a @code{SetAttribute}
-with the passed value. You can, if desired, set the ``Port'' @code{Attribute}
-to another value later.
+with the passed value. If you want, you can set the ``Port'' @code{Attribute}
+to another value later using @code{SetAttribute}.
Similar to many other helper objects, the @code{UdpEchoServerHelper} object
has an @code{Install} method. It is the execution of this method that actually
@@ -591,7 +594,11 @@
@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. There is a C++ @emph{implicit conversion} at
-work here.
+work here that takes the result of @code{nodes.Get (1)} (which returns a smart
+pointer to a node object --- @code{Ptr<Node>}) and uses that in a constructor
+for an unnamed @code{NodeContainer} that is then passed to @code{Install}.
+If you are ever at a loss to find a particular method signature in C++ code
+that compiles and runs just fine, look for these kinds of implicit conversions.
We now see that @code{echoServer.Install} is going to install a
@code{UdpEchoServerApplication} on the node found at index number one of the
@@ -603,9 +610,12 @@
Applications require a time to ``start'' generating traffic and may take an
optional time to ``stop''. We provide both. These times are set using the
@code{ApplicationContainer} methods @code{Start} and @code{Stop}. These
-methods take @code{Time} parameters. In this case, we use an explicit C++
-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,
+methods take @code{Time} parameters. In this case, we use an @emph{explicit}
+C++ 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. Be aware that
+the conversion rules may be controlled by the model author, and C++ has its
+own rules, so you can't always just assume that parameters will be happily
+converted for you. The two lines,
@verbatim
serverApps.Start (Seconds (1.0));
@@ -614,9 +624,9 @@
will cause the echo server application to @code{Start} (enable itself) at one
second into the simulation and to @code{Stop} (disable itself) at ten seconds
-into the simulation. By virtue of the fact that we have implicilty declared
-a simulation event (the application stop event) to be executed at ten seconds,
-the simulation will last at least ten seconds.
+into the simulation. By virtue of the fact that we have declared a simulation
+event (the application stop event) to be executed at ten seconds, the simulation
+will last @emph{at least} ten seconds.
@subsubsection UdpEchoClientHelper
@@ -682,25 +692,27 @@
@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, the system 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 application will begin the data transfer phase of the
-simulation by sending a packet to the server.
+two events at 10.0 seconds. When @code{Simulator::Run} is called, the system
+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 (this event may, in turn, schedule many other events). Then it
+will run the event scheduled for t=2.0 seconds which will start the echo client
+application. Again, this event may schedule many more events. The start event
+implementation in the echo client application 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
that will be automatically scheduled behind the scenes 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 send one packet, the chain of events triggered by
+Eventually, since we only send one packet (recall the @code{MaxPackets}
+@code{Attribute} was set to one), 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.
+is then complete.
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
@@ -721,10 +733,11 @@
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 if you run Waf. Let's try it. Copy @code{examples/first.cc} into
-the @code{scratch} directory.
+the @code{scratch} directory after changing back into the top level directory.
@verbatim
- ~/repos/ns-3-dev > cp examples/first.cc scratch/myfirst.cc
+ cd ..
+ cp examples/first.cc scratch/myfirst.cc
@end verbatim
Now build your first example script using waf:
@@ -737,10 +750,11 @@
successfully.
@verbatim
- Entering directory `repos/ns-3-allinone-dev/ns-3-dev/build'
- [563/648] cxx: scratch/myfirst.cc -> build/debug/scratch/myfirst_3.o
- [646/648] cxx_link: build/debug/scratch/myfirst_3.o -> build/debug/scratch/myfirst
- Build finished successfully (00:00:02)
+ Waf: Entering directory `/home/craigdo/repos/ns-3-allinone-3.5-tutorial/ns-3-dev/build'
+ [614/708] cxx: scratch/myfirst.cc -> build/debug/scratch/myfirst_3.o
+ [706/708] cxx_link: build/debug/scratch/myfirst_3.o -> build/debug/scratch/myfirst
+ Waf: Leaving directory `/home/craigdo/repos/ns-3-allinone-3.5-tutorial/ns-3-dev/build'
+ 'build' finished successfully (2.357s)
@end verbatim
You can now run the example (note that if you build your program in the scratch
@@ -753,8 +767,9 @@
You should see some output:
@verbatim
- Entering directory `repos/ns-3-allinone-dev/ns-3-dev/build'
- Build finished successfully (00:00:00)
+ Waf: Entering directory `/home/craigdo/repos/ns-3-allinone-3.5-tutorial/ns-3-dev/build'
+ Waf: Leaving directory `/home/craigdo/repos/ns-3-allinone-3.5-tutorial/ns-3-dev/build'
+ 'build' finished successfully (0.418s)
Sent 1024 bytes to 10.1.1.2
Received 1024 bytes from 10.1.1.1
Received 1024 bytes from 10.1.1.2
@@ -778,49 +793,57 @@
Now that you have used some of the @command{ns-3} helpers you may want to
have a look at some of the source code that implements that functionality.
The most recent code can be browsed on our web server at the following link:
-@uref{http://code.nsnam.org/?sort=lastchange}. If you click on the bold
-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.
+@uref{http://code.nsnam.org/ns-3-dev}. There, you will see the Mercurial
+summary page for our @command{ns-3} development tree.
+
+At the top of the page, you will see a number of links,
-The top-level directory for one of our @emph{repositories} will look
-something like:
+@verbatim
+ summary | shortlog | changelog | graph | tags | files
+@end verbatim
+
+Go ahead and select the @code{files} link. This is what the top-level of
+most of our @emph{repositories} will look:
@verbatim
-drwxr-xr-x [up]
-drwxr-xr-x bindings python files
-drwxr-xr-x doc files
-drwxr-xr-x examples files
-drwxr-xr-x ns3 files
-drwxr-xr-x regression files
-drwxr-xr-x samples files
-drwxr-xr-x scratch files
-drwxr-xr-x src files
-drwxr-xr-x utils files
--rw-r--r-- 2009-03-24 00:51 -0700 505 .hgignore file | revisions | annotate
--rw-r--r-- 2009-03-24 00:51 -0700 1682 .hgtags file | revisions | annotate
--rw-r--r-- 2009-03-24 00:51 -0700 686 AUTHORS file | revisions | annotate
--rw-r--r-- 2009-03-24 00:51 -0700 14893 CHANGES.html file | revisions | annotate
--rw-r--r-- 2009-03-24 00:51 -0700 17987 LICENSE file | revisions | annotate
--rw-r--r-- 2009-03-24 00:51 -0700 3742 README file | revisions | annotate
--rw-r--r-- 2009-03-24 00:51 -0700 13505 RELEASE_NOTES file | revisions | annotate
--rw-r--r-- 2009-03-24 00:51 -0700 6 VERSION file | revisions | annotate
--rw-r--r-- 2009-03-24 00:51 -0700 9257 regression.py file | revisions | annotate
--rwxr-xr-x 2009-03-24 00:51 -0700 81285 waf file | revisions | annotate
--rwxr-xr-x 2009-03-24 00:51 -0700 28 waf.bat file | revisions | annotate
--rw-r--r-- 2009-03-24 00:51 -0700 26270 wscript file | revisions | annotate
--rw-r--r-- 2009-03-24 00:51 -0700 6636 wutils.py file | revisions | annotate
+drwxr-xr-x [up]
+drwxr-xr-x bindings python files
+drwxr-xr-x doc files
+drwxr-xr-x examples files
+drwxr-xr-x ns3 files
+drwxr-xr-x regression files
+drwxr-xr-x samples files
+drwxr-xr-x scratch files
+drwxr-xr-x src files
+drwxr-xr-x utils files
+-rw-r--r-- 2009-07-01 12:47 +0200 560 .hgignore file | revisions | annotate
+-rw-r--r-- 2009-07-01 12:47 +0200 1886 .hgtags file | revisions | annotate
+-rw-r--r-- 2009-07-01 12:47 +0200 1276 AUTHORS file | revisions | annotate
+-rw-r--r-- 2009-07-01 12:47 +0200 30961 CHANGES.html file | revisions | annotate
+-rw-r--r-- 2009-07-01 12:47 +0200 17987 LICENSE file | revisions | annotate
+-rw-r--r-- 2009-07-01 12:47 +0200 3742 README file | revisions | annotate
+-rw-r--r-- 2009-07-01 12:47 +0200 16171 RELEASE_NOTES file | revisions | annotate
+-rw-r--r-- 2009-07-01 12:47 +0200 6 VERSION file | revisions | annotate
+-rw-r--r-- 2009-07-01 12:47 +0200 10946 regression.py file | revisions | annotate
+-rwxr-xr-x 2009-07-01 12:47 +0200 88110 waf file | revisions | annotate
+-rwxr-xr-x 2009-07-01 12:47 +0200 28 waf.bat file | revisions | annotate
+-rw-r--r-- 2009-07-01 12:47 +0200 35395 wscript file | revisions | annotate
+-rw-r--r-- 2009-07-01 12:47 +0200 7673 wutils.py file | revisions | annotate
@end verbatim
+Our example scripts are in the @code{examples} directory. If you click on @code{examples}
+you will see a list of files. One of the files in that directory is @code{first.cc}. If
+you click on @code{first.cc} you will find the code you just walked through.
+
The source code is mainly in the @code{src} directory. You can view source
code either by clicking on the directory name or by clicking on the @code{files}
link to the right of the directory name. If you click on the @code{src}
directory, you will be taken to the listing of the @code{src} subdirectories. If you
-click on @code{core} subdirectory, you will find a list of files. The first file
-you will find (as of this writing) is @code{abort.h}. If you
-click on @code{abort.h} link, you will be sent to the source file for @code{abort.h}.
+then click on @code{core} subdirectory, you will find a list of files. The first file
+you will find (as of this writing) is @code{abort.h}. If you click on the
+@code{abort.h} link, you will be sent to the source file for @code{abort.h} which
+contains useful macros for exiting scripts if abnormal conditions are detected.
-Our example scripts are in the @code{examples} directory. The source code for
-the helpers we have used in this chapter can be found in the
+The source code for the helpers we have used in this chapter can be found in the
@code{src/helper} directory. Feel free to poke around in the directory tree to
get a feel for what is there and the style of @command{ns-3} programs.
--- a/doc/tutorial/getting-started.texi Wed Jul 01 12:47:40 2009 +0200
+++ b/doc/tutorial/getting-started.texi Wed Jul 01 23:08:07 2009 -0700
@@ -80,7 +80,7 @@
adding changesets
adding manifests
adding file changes
- added 26 changesets with 40 changes to 7 files
+ added 31 changesets with 45 changes to 7 files
7 files updated, 0 files merged, 0 files removed, 0 files unresolved
@end verbatim
@@ -126,8 +126,8 @@
Since the release numbers are going to be changing, I will stick with
the more constant ns-3-dev here in the tutorial, but you can replace the
-string ``ns-3-dev'' with your choice of release (e.g., ns-3.4 and
-ns-3.4-ref-traces) in the text below. You can find the latest version of the
+string ``ns-3-dev'' with your choice of release (e.g., ns-3.5 and
+ns-3.5-ref-traces) in the text below. You can find the latest version of the
code either by inspection of the repository list or by going to the
@uref{http://www.nsnam.org/getting_started.html,,``Getting Started''}
web page and looking for the latest release identifier.
@@ -138,13 +138,23 @@
Go ahead and type the following into your shell (remember you can substitute
the name of your chosen release number instead of @code{ns-3-dev} -- like
-@code{"ns-3.4"} and @code{"ns-3.4-ref-traces"} if you want to work with a
+@code{"ns-3.5"} and @code{"ns-3.5-ref-traces"} if you want to work with a
stable release).
@verbatim
./download.py -n ns-3-dev -r ns-3-dev-ref-traces
@end verbatim
+Note that the default for the @code{-n} option is @code{ns-3-dev} and the
+default for the @code{-r} option is @code{ns-3-dev-ref-traces} and so the
+above is actually redundant. We provide this example to illustrate how to
+specify alternate repositories. In order to download @code{ns-3-dev} you
+can actually use the defaults and simply type,
+
+@verbatim
+ ./download.py
+@end verbatim
+
As the hg (Mercurial) command executes, you should see something like the
following,
@@ -152,15 +162,15 @@
#
# Get NS-3
#
-
+
Cloning ns-3 branch
=> hg clone http://code.nsnam.org/ns-3-dev ns-3-dev
requesting all changes
adding changesets
adding manifests
adding file changes
- added 4292 changesets with 15368 changes to 1671 files
- 823 files updated, 0 files merged, 0 files removed, 0 files unresolved
+ added 4634 changesets with 16500 changes to 1762 files
+ 870 files updated, 0 files merged, 0 files removed, 0 files unresolved
@end verbatim
This is output by the download script as it fetches the actual @code{ns-3}
@@ -177,8 +187,8 @@
adding changesets
adding manifests
adding file changes
- added 79 changesets with 1102 changes to 222 files
- 206 files updated, 0 files merged, 0 files removed, 0 files unresolved
+ added 86 changesets with 1178 changes to 259 files
+ 208 files updated, 0 files merged, 0 files removed, 0 files unresolved
@end verbatim
This is the download script fetching the reference trace files for you.
@@ -191,10 +201,10 @@
#
# Get PyBindGen
#
-
- Required pybindgen version: 0.10.0.630
+
+ Required pybindgen version: 0.10.0.640
Trying to fetch pybindgen; this will fail if no network connection is available. Hit Ctrl-C to skip.
- => bzr checkout -rrevno:630 https://launchpad.net/pybindgen pybindgen
+ => bzr checkout -rrevno:640 https://launchpad.net/pybindgen pybindgen
Fetch was successful.
@end verbatim
@@ -205,7 +215,7 @@
#
# Get NSC
#
-
+
Required NSC version: nsc-0.5.0
Retrieving nsc from https://secure.wand.net.nz/mercurial/nsc
=> hg clone https://secure.wand.net.nz/mercurial/nsc nsc
@@ -213,8 +223,8 @@
adding changesets
adding manifests
adding file changes
- added 270 changesets with 17375 changes to 14991 files
- 10614 files updated, 0 files merged, 0 files removed, 0 files unresolved
+ added 273 changesets with 17565 changes to 15175 files
+ 10622 files updated, 0 files merged, 0 files removed, 0 files unresolved
@end verbatim
This part of the process is the script downloading the Network Simulation
@@ -257,16 +267,16 @@
cd
mkdir tarballs
cd tarballs
- wget http://www.nsnam.org/releases/ns-allinone-3.4.tar.bz2
- tar xjf ns-allinone-3.4.tar.bz2
+ wget http://www.nsnam.org/releases/ns-allinone-3.5.tar.bz2
+ tar xjf ns-allinone-3.5.tar.bz2
@end verbatim
-If you change into the directory @code{ns-allinone-3.4} you should see a
+If you change into the directory @code{ns-allinone-3.5} you should see a
number of files:
@verbatim
-build.py* ns-3.4/ nsc-0.5.0/ README
-constants.py ns-3.4-ref-traces/ pybindgen-0.10.0.630/ util.py
+build.py* ns-3.5/ nsc-0.5.0/ README
+constants.py ns-3.5-ref-traces/ pybindgen-0.10.0.640/ util.py
@end verbatim
You are now ready to build the @command{ns-3} distribution.
@@ -288,7 +298,7 @@
downloaded using Mercurial you should have a directory called
@code{ns-3-allinone} under your @code{~/repos} directory. If you downloaded
using a tarball you should have a directory called something like
-@code{ns-3-allinone-3.4} under your @code{~/tarballs} directory. Take a deep
+@code{ns-allinone-3.5} under your @code{~/tarballs} directory. Take a deep
breath and type the following:
@verbatim
@@ -300,13 +310,13 @@
following magic words:
@verbatim
- Build finished successfully (00:02:37)
- Leaving directory `./ns-3-dev'
+ Waf: Leaving directory `/home/craigdo/repos/ns-3-allinone-3.5-tutorial/ns-3-dev/build'
+ 'build' finished successfully (2m30.586s)
@end verbatim
Once the project has built you can say goodbye to your old friends, the
@code{ns-3-allinone} scripts. You got what you needed from them and will now
-interact directly with Waf and we do it in the @code{ns-3-dev} directory and
+interact directly with Waf and we do it in the @code{ns-3-dev} directory,
not in the @code{ns-3-allinone} directory. Go ahead and change into the
@code{ns-3-dev} directory (or the directory for the appropriate release you
downloaded.
@@ -340,76 +350,72 @@
output that looks similar to the following,
@verbatim
-Checking for program g++ : ok /usr/bin/g++
-Checking for program cpp : ok /usr/bin/cpp
-Checking for program ar : ok /usr/bin/ar
-Checking for program ranlib : ok /usr/bin/ranlib
-Checking for g++ : ok
-Checking for program pkg-config : ok /usr/bin/pkg-config
-Checking for regression reference traces : ok ../ns-3-dev-ref-traces (guessed)
-Checking for -Wno-error=deprecated-declarations support : yes
-Checking for header stdlib.h : ok
-Checking for header signal.h : ok
-Checking for header pthread.h : ok
-Checking for high precision time implementation : 128-bit integer
-Checking for header stdint.h : ok
-Checking for header inttypes.h : ok
-Checking for header sys/inttypes.h : not found
-Checking for library rt : ok
-Checking for header netpacket/packet.h : ok
-Checking for header linux/if_tun.h : ok
-Checking for pkg-config flags for GTK_CONFIG_STORE : ok
-Package libxml-2.0 was not found in the pkg-config search path.
-Perhaps you should add the directory containing `libxml-2.0.pc'
-to the PKG_CONFIG_PATH environment variable
-No package 'libxml-2.0' found
-Checking for pkg-config flags for LIBXML2 : not found
-Checking for library sqlite3 : ok
-Checking for NSC location : ok ../nsc (guessed)
-Checking for library dl : ok
-Checking for NSC supported architecture x86_64 : ok
-Package goocanvas was not found in the pkg-config search path.
-Perhaps you should add the directory containing `goocanvas.pc'
-to the PKG_CONFIG_PATH environment variable
-No package 'goocanvas' found
-Checking for pkg-config flags for MOBILITY_VISUALIZER : not found
-Checking for program python : ok /usr/bin/python
-Checking for Python version >= 2.3 : ok 2.5.2
-Checking for library python2.5 : ok
-Checking for program python2.5-config : ok /usr/bin/python2.5-config
-Checking for header Python.h : ok
-Checking for -fvisibility=hidden support : yes
-Checking for pybindgen location : ok ../pybindgen (guessed)
-Checking for Python module pybindgen : ok
-Checking for pybindgen version : ok 0.10.0.630
-Checking for Python module pygccxml : ok
-Checking for pygccxml version : ok 0.9.5
-Checking for program gccxml : ok /usr/local/bin/gccxml
-Checking for gccxml version : ok 0.9.0
-Checking for program sudo : ok /usr/bin/sudo
-Checking for program hg : ok /usr/bin/hg
-Checking for program valgrind : ok /usr/bin/valgrind
----- Summary of optional NS-3 features:
-Threading Primitives : enabled
-Real Time Simulator : enabled
-Emulated Net Device : enabled
-Tap Bridge : enabled
-GtkConfigStore : enabled
-XmlIo : not enabled (library 'libxml-2.0 >= 2.7' not found)
-SQlite stats data output : enabled
-Network Simulation Cradle : enabled
-Python Bindings : enabled
-Python API Scanning Support : enabled
-Use sudo to set suid bit : not enabled (option --enable-sudo not selected)
-Configuration finished successfully (00:00:02); project is now ready to build.
+ Checking for program g++ : ok /usr/bin/g++
+ Checking for program cpp : ok /usr/bin/cpp
+ Checking for program ar : ok /usr/bin/ar
+ Checking for program ranlib : ok /usr/bin/ranlib
+ Checking for g++ : ok
+ Checking for program pkg-config : ok /usr/bin/pkg-config
+ Checking for regression reference traces : ok ../ns-3-dev-ref-traces (guessed)
+ Checking for -Wno-error=deprecated-declarations support : yes
+ Checking for -Wl,--soname=foo support : yes
+ Checking for header stdlib.h : ok
+ Checking for header signal.h : ok
+ Checking for header pthread.h : ok
+ Checking for high precision time implementation : 128-bit integer
+ Checking for header stdint.h : ok
+ Checking for header inttypes.h : ok
+ Checking for header sys/inttypes.h : not found
+ Checking for library rt : ok
+ Checking for header netpacket/packet.h : ok
+ Checking for pkg-config flags for GSL : ok
+ Checking for header linux/if_tun.h : ok
+ Checking for pkg-config flags for GTK_CONFIG_STORE : ok
+ Checking for pkg-config flags for LIBXML2 : ok
+ Checking for library sqlite3 : ok
+ Checking for NSC location : ok ../nsc (guessed)
+ Checking for library dl : ok
+ Checking for NSC supported architecture x86_64 : ok
+ Checking for program python : ok /usr/bin/python
+ Checking for Python version >= 2.3 : ok 2.5.2
+ Checking for library python2.5 : ok
+ Checking for program python2.5-config : ok /usr/bin/python2.5-config
+ Checking for header Python.h : ok
+ Checking for -fvisibility=hidden support : yes
+ Checking for pybindgen location : ok ../pybindgen (guessed)
+ Checking for Python module pybindgen : ok
+ Checking for pybindgen version : ok 0.10.0.640
+ Checking for Python module pygccxml : ok
+ Checking for pygccxml version : ok 0.9.5
+ Checking for program gccxml : ok /usr/local/bin/gccxml
+ Checking for gccxml version : ok 0.9.0
+ Checking for program sudo : ok /usr/bin/sudo
+ Checking for program hg : ok /usr/bin/hg
+ Checking for program valgrind : ok /usr/bin/valgrind
+ ---- Summary of optional NS-3 features:
+ Threading Primitives : enabled
+ Real Time Simulator : enabled
+ Emulated Net Device : enabled
+ GNU Scientific Library (GSL) : enabled
+ Tap Bridge : enabled
+ GtkConfigStore : enabled
+ XmlIo : enabled
+ SQlite stats data output : enabled
+ Network Simulation Cradle : enabled
+ Python Bindings : enabled
+ Python API Scanning Support : enabled
+ Use sudo to set suid bit : not enabled (option --enable-sudo not selected)
+ Static build : not enabled (option --enable-static not selected)
+ 'configure' finished successfully (2.870s)
@end verbatim
Note the last part of the above output. Some ns-3 options are not enabled by
default or require support from the underlying system to work properly.
For instance, to enable XmlTo, the library libxml-2.0 must be found on the
-system. in the example above, this library was not found and the corresponding
-feature was not enabled. There is a feature to use sudo to set the suid bit of
-certain programs. This was not enabled by default.
+system. If this library were not found, the corresponding @command{ns-3} feature
+would not be enabled and a message would be displayed. Note further that there is
+a feature to use the progarm @code{sudo} to set the suid bit of certain programs.
+This is not enabled by default and so this feature is reported as ``not enabled.''
Now go ahead and switch back to the debug build.
@@ -427,15 +433,15 @@
Some waf commands are meaningful during the build phase and some commands are valid
in the configuration phase. For example, if you wanted to use the emulation
features of @command{ns-3} you might want to enable setting the suid bit using
-sudo. This is a configuration command, and so you could have run the following
-command
+sudo as described above. This turns out to be a configuration-time command, and so
+you could reconfigure using the following command
@verbatim
./waf -d debug --enable-sudo configure
@end verbatim
-If you had done this, waf would have run sudo to change the socket creator
-programs to run as root. There are many other configure- and build-time options
+If you do this, waf will have run sudo to change the socket creator programs of the
+emulation code to run as root. There are many other configure- and build-time options
available in waf. To explore these options, type:
@verbatim
@@ -462,26 +468,45 @@
./waf --check
@end verbatim
-You should see a report from each unit test that executes indicating that the
-test has passed.
+These tests are run in parallel by waf, so the summary, ``Ran n tests'' will
+appear as soon as all of the tasks are launched, but you should eventually
+see a report saying that,
@verbatim
- Entering directory `repos/ns-3-allinone/ns-3-dev/build'
- Build finished successfully (00:00:00)
- -- Running NS-3 C++ core unit tests...
- PASS AddressHelper
- PASS Wifi
- PASS DcfManager
- ...
- PASS Object
- PASS Ptr
- PASS Callback
- -- Running NS-3 Python bindings unit tests...
+ C++ UNIT TESTS: all 33 tests passed.
+@end verbatim
+
+This is the important message.
+
+You will also see output from the test runner and waf task sequence numbers
+the output will actually look something like,
+
+@verbatim
+ Waf: Entering directory `/home/craigdo/repos/ns-3-allinone-3.5-tutorial/ns-3-dev/build'
+ [707/709] get-unit-tests-list
+ [708/709] run-python-unit-tests
+ [709/709] print-introspected-doxygen
+ [710/743] run-unit-test(AddressHelper)
+ [711/743] run-unit-test(Wifi)
...........
----------------------------------------------------------------------
Ran 11 tests in 0.003s
+
+ OK
+ [712/743] run-unit-test(DcfManager)
+ [713/743] run-unit-test(MacRxMiddle)
+ [714/743] run-unit-test(Ipv4ListRouting)
- OK
+ ...
+
+ [739/743] run-unit-test(RandomVariable)
+ [740/743] run-unit-test(Object)
+ [741/743] run-unit-test(Ptr)
+ [742/743] run-unit-test(Callback)
+ [743/743] collect-unit-tests-results
+ C++ UNIT TESTS: all 33 tests passed.
+ Waf: Leaving directory `/home/craigdo/repos/ns-3-allinone-3.5-tutorial/ns-3-dev/build'
+ 'build' finished successfully (1.799s)
@end verbatim
This command is typically run by @code{users} to quickly verify that an
@@ -491,10 +516,10 @@
You can also run our regression test suite to ensure that your distribution and
toolchain have produced binaries that generate output that is identical to
known-good reference output files. You downloaded these reference traces to
-your machine during the download process above. (Warning: The @code{ns-3.2}
-and @code{ns-3.3} releases do not use the @code{ns-3-allinone} environment
-and require you to be online when you run regression tests because they
-dynamically synchronize the reference traces directory with an online
+your machine during the @code{./download.py} process above. (Warning: The
+@code{ns-3.2} and @code{ns-3.3} releases do not use the @code{ns-3-allinone}
+environment and require you to be online when you run regression tests because
+hey dynamically synchronize the reference traces directory with an online
repository immediately prior to the run).
During regression testing Waf will run a number of tests that generate what we
@@ -509,6 +534,9 @@
Some regression tests may be SKIPped if the required support
is not present.
+Note that the regression tests are also run in parallel and so the messages
+may be interleaved.
+
To run the regression tests, you provide Waf with the regression flag.
@verbatim
@@ -530,7 +558,8 @@
...
Regression testing summary:
PASS: 22 of 22 tests passed
- Build finished successfully (00:00:23)
+ Waf: Leaving directory `/home/craigdo/repos/ns-3-allinone-3.5-tutorial/ns-3-dev/build'
+ 'build' finished successfully (25.826s)
@end verbatim
If you want to take a look at an example of what might be checked during
--- a/doc/tutorial/introduction.texi Wed Jul 01 12:47:40 2009 +0200
+++ b/doc/tutorial/introduction.texi Wed Jul 01 23:08:07 2009 -0700
@@ -75,7 +75,7 @@
generates pcap packet trace files, other utilities can be used to
analyze traces as well.
In this tutorial, we will first concentrate on scripting
-directly in C++ and interpreting results via ascii trace files.
+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 @command{ns-3}).
@@ -256,8 +256,8 @@
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}. @command{ns-3} uses gcc,
-GNU binutils, and gdb. However, we do not use the GNU build system,
-either make or autotools, using Waf instead.
+GNU binutils, and gdb. However, we do not use the GNU build system tools,
+neither make nor autotools. We use Waf for these functions.
@cindex Linux
Typically an @command{ns-3} author will work in Linux or a Linux-like
@@ -265,11 +265,11 @@
which simulate the Linux environment to various degrees. The @command{ns-3}
project supports development in the Cygwin environment for
these users. See @uref{http://www.cygwin.com/}
-for details on downloading (MinGW is presently not supported).
-Cygwin provides many of the popular Linux system commands.
-It can, however, sometimes be problematic due to the way it actually does its
-emulation, and sometimes interactions with other Windows software can cause
-problems.
+for details on downloading (MinGW is presently not officially supported,
+although some of the project maintainers to work with it). Cygwin provides
+many of the popular Linux system commands. It can, however, sometimes be
+problematic due to the way it actually does its emulation, and sometimes
+interactions with other Windows software can cause problems.
@cindex Cygwin
@cindex MinGW
--- a/doc/tutorial/tweaking.texi Wed Jul 01 12:47:40 2009 +0200
+++ b/doc/tutorial/tweaking.texi Wed Jul 01 23:08:07 2009 -0700
@@ -89,7 +89,8 @@
@subsection Enabling Logging
@cindex NS_LOG
Let's use the NS_LOG environment variable to turn on some more logging, but
-to get our bearings, go ahead and run the script just as you did previously,
+first, just to get our bearings, go ahead and run the last script just as you
+did previously,
@verbatim
./waf --run scratch/myfirst
@@ -99,8 +100,9 @@
program
@verbatim
- Entering directory `repos/ns-3-dev/build'
- Compilation finished successfully
+ Waf: Entering directory `/home/craigdo/repos/ns-3-allinone-3.5-tutorial/ns-3-dev/build'
+ Waf: Leaving directory `/home/craigdo/repos/ns-3-allinone-3.5-tutorial/ns-3-dev/build'
+ 'build' finished successfully (0.413s)
Sent 1024 bytes to 10.1.1.2
Received 1024 bytes from 10.1.1.1
Received 1024 bytes from 10.1.1.2
@@ -148,15 +150,17 @@
system will pick up the change and you should see the following output:
@verbatim
- Entering directory `repos/ns-3-allinone/ns-3-dev/build'
- Build finished successfully (00:00:00)
+ Waf: Entering directory `/home/craigdo/repos/ns-3-allinone-3.5-tutorial/ns-3-dev/build
+ Waf: Leaving directory `/home/craigdo/repos/ns-3-allinone-3.5-tutorial/ns-3-dev/build'
+ 'build' finished successfully (0.404s)
UdpEchoClientApplication:UdpEchoClient()
+ UdpEchoClientApplication:SetDataSize(1024)
UdpEchoClientApplication:StartApplication()
UdpEchoClientApplication:ScheduleTransmit()
UdpEchoClientApplication:Send()
Sent 1024 bytes to 10.1.1.2
Received 1024 bytes from 10.1.1.1
- UdpEchoClientApplication:HandleRead(0x638180, 0x6389b0)
+ UdpEchoClientApplication:HandleRead(0x6241e0, 0x624a20)
Received 1024 bytes from 10.1.1.2
UdpEchoClientApplication:StopApplication()
UdpEchoClientApplication:DoDispose()
@@ -186,7 +190,7 @@
It turns out that in some cases, it can be hard to determine which method
actually generates a log message. If you look in the text above, you may
wonder where the string ``@code{Received 1024 bytes from 10.1.1.2}'' comes
-from. You can resolve this by ORing the @code{prefix_func} level into the
+from. You can resolve this by OR'ing the @code{prefix_func} level into the
@code{NS_LOG} environment variable. Try doing the following,
@verbatim
@@ -201,15 +205,17 @@
name.
@verbatim
- Entering directory `repos/ns-3-allinone/ns-3-dev/build'
- Build finished successfully (00:00:00)
+ Waf: Entering directory `/home/craigdo/repos/ns-3-allinone-3.5-tutorial/ns-3-dev/build'
+ Waf: Leaving directory `/home/craigdo/repos/ns-3-allinone-3.5-tutorial/ns-3-dev/build'
+ 'build' finished successfully (0.417s)
UdpEchoClientApplication:UdpEchoClient()
+ UdpEchoClientApplication:SetDataSize(1024)
UdpEchoClientApplication:StartApplication()
UdpEchoClientApplication:ScheduleTransmit()
UdpEchoClientApplication:Send()
UdpEchoClientApplication:Send(): Sent 1024 bytes to 10.1.1.2
Received 1024 bytes from 10.1.1.1
- UdpEchoClientApplication:HandleRead(0x638180, 0x6389b0)
+ UdpEchoClientApplication:HandleRead(0x6241e0, 0x624a20)
UdpEchoClientApplication:HandleRead(): Received 1024 bytes from 10.1.1.2
UdpEchoClientApplication:StopApplication()
UdpEchoClientApplication:DoDispose()
@@ -236,10 +242,12 @@
in debugging problems.
@verbatim
- Entering directory `repos/ns-3-allinone/ns-3-dev/build'
- Build finished successfully (00:00:00)
+ Waf: Entering directory `/home/craigdo/repos/ns-3-allinone-3.5-tutorial/ns-3-dev/build'
+ Waf: Leaving directory `/home/craigdo/repos/ns-3-allinone-3.5-tutorial/ns-3-dev/build'
+ 'build' finished successfully (0.406s)
UdpEchoServerApplication:UdpEchoServer()
UdpEchoClientApplication:UdpEchoClient()
+ UdpEchoClientApplication:SetDataSize(1024)
UdpEchoServerApplication:StartApplication()
UdpEchoClientApplication:StartApplication()
UdpEchoClientApplication:ScheduleTransmit()
@@ -247,7 +255,7 @@
UdpEchoClientApplication:Send(): Sent 1024 bytes to 10.1.1.2
UdpEchoServerApplication:HandleRead(): Received 1024 bytes from 10.1.1.1
UdpEchoServerApplication:HandleRead(): Echoing packet
- UdpEchoClientApplication:HandleRead(0x638320, 0x638b50)
+ UdpEchoClientApplication:HandleRead(0x624920, 0x625160)
UdpEchoClientApplication:HandleRead(): Received 1024 bytes from 10.1.1.2
UdpEchoServerApplication:StopApplication()
UdpEchoClientApplication:StopApplication()
@@ -269,10 +277,12 @@
you should see the following output:
@verbatim
- Entering directory `repos/ns-3-allinone/ns-3-dev/build'
- Build finished successfully (00:00:00)
+ Waf: Entering directory `/home/craigdo/repos/ns-3-allinone-3.5-tutorial/ns-3-dev/build'
+ Waf: Leaving directory `/home/craigdo/repos/ns-3-allinone-3.5-tutorial/ns-3-dev/build'
+ 'build' finished successfully (0.418s)
0s UdpEchoServerApplication:UdpEchoServer()
0s UdpEchoClientApplication:UdpEchoClient()
+ 0s UdpEchoClientApplication:SetDataSize(1024)
1s UdpEchoServerApplication:StartApplication()
2s UdpEchoClientApplication:StartApplication()
2s UdpEchoClientApplication:ScheduleTransmit()
@@ -280,7 +290,7 @@
2s UdpEchoClientApplication:Send(): Sent 1024 bytes to 10.1.1.2
2.00369s UdpEchoServerApplication:HandleRead(): Received 1024 bytes from 10.1.1.1
2.00369s UdpEchoServerApplication:HandleRead(): Echoing packet
- 2.00737s UdpEchoClientApplication:HandleRead(0x638490, 0x638cc0)
+ 2.00737s UdpEchoClientApplication:HandleRead(0x624290, 0x624ad0)
2.00737s UdpEchoClientApplication:HandleRead(): Received 1024 bytes from 10.1.1.2
10s UdpEchoServerApplication:StopApplication()
10s UdpEchoClientApplication:StopApplication()
@@ -292,22 +302,22 @@
You can see that the constructor for the UdpEchoServer was called at a
simulation time of 0 seconds. This is actually happening before the
-simulation starts. The same for the UdpEchoClient constructor.
+simulation starts, but the time is displayed as zero seconds. The same is true
+for the UdpEchoClient constructor message.
Recall that the @code{scratch/first.cc} script started the echo server
application at one second into the simulation. You can now see that the
-@code{StartApplication} method of the server is, in fact, called at one second
-(or one billion nanoseconds). You can also see that the echo client
-application is started at a simulation time of two seconds as we requested in
-the script.
+@code{StartApplication} method of the server is, in fact, called at one second.
+You can also see that the echo client application is started at a simulation
+time of two seconds as we requested in the script.
You can now follow the progress of the simulation from the
@code{ScheduleTransmit} call in the client that calls @code{Send} to the
@code{HandleRead} callback in the echo server application. Note that the
-elapsed time as the packet is sent across the point-to-point link is 3.6864
+elapsed time for the packet to be sent across the point-to-point link is 3.69
milliseconds. You see the echo server logging a message telling you that it
-has echoed the packet and then, after a delay, you see the echo client receive
-the echoed packet in its @code{HandleRead} method.
+has echoed the packet and then, after another channel delay, you see the echo
+client receive the echoed packet in its @code{HandleRead} method.
There is a lot that is happening under the covers in this simulation that you
are not seeing as well. You can very easily follow the entire process by
@@ -320,7 +330,7 @@
The asterisk above is the logging component wildcard. This will turn on all
of the logging in all of the components used in the simulation. I won't
-reproduce the output here (as of this writing it produces 974 lines of output
+reproduce the output here (as of this writing it produces 1265 lines of output
for the single packet echo) but you can redirect this information into a file
and look through it with your favorite editor if you like,
@@ -328,15 +338,16 @@
./waf --run scratch/myfirst > log.out 2>&1
@end verbatim
-I personally use this volume of logging quite a bit when I am presented with
-a problem and I have no idea where things are going wrong. I can follow the
+I personally use this extremely verbose version of logging when I am presented
+with a problem and I have no idea where things are going wrong. I can follow the
progress of the code quite easily without having to set breakpoints and step
-through code in a debugger. When I have a general idea about what is going
-wrong, I transition into a debugger for fine-grained examination of the
-problem. This kind of output can be especially useful when your script does
-something completely unexpected. If you are stepping using a debugger you
-may miss an unexpected excursion completely. Logging the excursion makes it
-quickly visible.
+through code in a debugger. I can just edit up the output in my favorite editor
+and search around for things I expect, and see things happening that I don't
+expect. When I have a general idea about what is going wrong, I transition into
+a debugger for a fine-grained examination of the problem. This kind of output
+can be especially useful when your script does something completely unexpected.
+If you are stepping using a debugger you may miss an unexpected excursion
+completely. Logging the excursion makes it quickly visible.
@node Adding Logging to your Code
@subsection Adding Logging to your Code
@@ -399,8 +410,9 @@
message,
@verbatim
- Entering directory `repos/ns-3-allinone/ns-3-dev/build'
- Build finished successfully (00:00:00)
+ Waf: Entering directory `/home/craigdo/repos/ns-3-allinone-3.5-tutorial/ns-3-dev/build'
+ Waf: Leaving directory `/home/craigdo/repos/ns-3-allinone-3.5-tutorial/ns-3-dev/build'
+ 'build' finished successfully (0.404s)
Creating Topology
Sent 1024 bytes to 10.1.1.2
Received 1024 bytes from 10.1.1.1
@@ -453,8 +465,11 @@
now see the @code{--PrintHelp} argument and respond with,
@verbatim
- Entering directory `repos/ns-3-allinone/ns-3-dev/build'
- Build finished successfully (00:00:00)
+ Waf: Entering directory `/home/craigdo/repos/ns-3-allinone-3.5-tutorial/ns-3-dev/build'
+ Waf: Leaving directory `/home/craigdo/repos/ns-3-allinone-3.5-tutorial/ns-3-dev/build'
+ 'build' finished successfully (0.413s)
+ TcpL4Protocol:TcpStateMachine()
+ CommandLine:HandleArgument(): Handle arg name=PrintHelp value=
--PrintHelp: Print this help message.
--PrintGroups: Print the list of groups.
--PrintTypeIds: Print all TypeIds.
@@ -527,7 +542,9 @@
If you run the script, you should now see the following output,
@verbatim
- Build finished successfully (00:00:00)
+ Waf: Entering directory `/home/craigdo/repos/ns-3-allinone-3.5-tutorial/ns-3-dev/build'
+ Waf: Leaving directory `/home/craigdo/repos/ns-3-allinone-3.5-tutorial/ns-3-dev/build'
+ 'build' finished successfully (0.405s)
0s UdpEchoServerApplication:UdpEchoServer()
1s UdpEchoServerApplication:StartApplication()
Sent 1024 bytes to 10.1.1.2
@@ -589,8 +606,9 @@
@code{DataRate} and @code{Delay} in the script:
@verbatim
- Entering directory `repos/ns-3-allinone/ns-3-dev/build'
- Build finished successfully (00:00:00)
+ Waf: Entering directory `/home/craigdo/repos/ns-3-allinone-3.5-tutorial/ns-3-dev/bu
+ Waf: Leaving directory `/home/craigdo/repos/ns-3-allinone-3.5-tutorial/ns-3-dev/bui
+ 'build' finished successfully (0.417s)
0s UdpEchoServerApplication:UdpEchoServer()
1s UdpEchoServerApplication:StartApplication()
Sent 1024 bytes to 10.1.1.2
@@ -608,13 +626,13 @@
to some other value than one.
How would you go about that? Give it a try. Remember you have to comment
-out the place we override the default @code{Attribute} in the script. Then you
-have to rebuild the script using the default. You will also have to find the
-syntax for actually setting the new default atribute value using the command
-line help facility. Once you have this figured out you should be able to
-control the number of packets echoed from the command line. Since we're nice
-folks, we'll tell you that your command line should end up looking something
-like,
+out the place we override the default @code{Attribute} and explicitly set
+@code{MaxPackets} in the script. Then you have to rebuild the script. You
+will also have to find the syntax for actually setting the new default atribute
+value using the command line help facility. Once you have this figured out
+you should be able to control the number of packets echoed from the command
+line. Since we're nice folks, we'll tell you that your command line should
+end up looking something like,
@verbatim
./waf --run "scratch/myfirst
@@ -666,8 +684,9 @@
@end verbatim
@verbatim
- Entering directory `repos/ns-3-allinone/ns-3-dev/build'
- Build finished successfully (00:00:00)
+ Waf: Entering directory `/home/craigdo/repos/ns-3-allinone-3.5-tutorial/ns-3-dev/build'
+ Waf: Leaving directory `/home/craigdo/repos/ns-3-allinone-3.5-tutorial/ns-3-dev/build'
+ 'build' finished successfully (0.403s)
--PrintHelp: Print this help message.
--PrintGroups: Print the list of groups.
--PrintTypeIds: Print all TypeIds.
@@ -688,8 +707,9 @@
You should now see
@verbatim
- Entering directory `repos/ns-3-allinone/ns-3-dev/build'
- Build finished successfully (00:00:00)
+ Waf: Entering directory `/home/craigdo/repos/ns-3-allinone-3.5-tutorial/ns-3-dev/build'
+ Waf: Leaving directory `/home/craigdo/repos/ns-3-allinone-3.5-tutorial/ns-3-dev/build'
+ 'build' finished successfully (0.404s)
0s UdpEchoServerApplication:UdpEchoServer()
1s UdpEchoServerApplication:StartApplication()
Sent 1024 bytes to 10.1.1.2
@@ -705,7 +725,7 @@
UdpEchoServerApplication:~UdpEchoServer()
@end verbatim
-You have now echoed two packets.
+You have now echoed two packets. Pretty easy, isn't it?
You can see that if you are an @command{ns-3} user, you can use the command
line argument system to control global values and @code{Attributes}. If you are
@@ -827,7 +847,7 @@
@cindex myfirst.tr
Just as you have seen many times before, you will see some messages from Waf and then
-the ``Build finished successfully'' with some number of messages from
+``'build' finished successfully'' with some number of messages from
the running program.
When it ran, the program will have created a file named @code{myfirst.tr}.