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

Manual and Tutorial syntax coloring

Browse Source
This commit is contained in:
Peter D. Barnes, Jr.
2013-07-17 17:09:36 -07:00
parent 9659e95a7d
commit 9f77e699cb
27 changed files with 668 additions and 478 deletions
Download Patch File Download Diff File Expand all files Collapse all files

37
doc/manual/source/attributes.rst
View File

@@ -1,4 +1,6 @@
.. include:: replace.txt
.. highlight:: cpp
.. _Attributes:
@@ -405,7 +407,9 @@ Object Name Service-based access
Another way to get at the attribute is to use the object name service facility.
Here, this attribute is found using a name string. This approach is useful if
one doesn't have access to the underlying pointers and it is difficult to
determine the required concrete configuration namespaced path.::
determine the required concrete configuration namespaced path.
::
Names::Add ("server", serverNode);
Names::Add ("server/eth0", serverDevice);
@@ -414,7 +418,7 @@ determine the required concrete configuration namespaced path.::
Config::Set ("/Names/server/eth0/TxQueue/MaxPackets", UintegerValue (25));
:ref:`Object-names` for a fuller treatment of the |ns3| configuration namespace.
See :ref:`Object-names` for a fuller treatment of the |ns3| configuration namespace.
Setting through constructors helper classes
+++++++++++++++++++++++++++++++++++++++++++
@@ -737,7 +741,9 @@ The example shows:::
Simulator::Destroy ();
After running, you can open the output-attributes.txt file and see:::
After running, you can open the output-attributes.txt file and see:
.. sourcecode:: text
default ns3::RealtimeSimulatorImpl::SynchronizationMode "BestEffort"
default ns3::RealtimeSimulatorImpl::HardLimit "+100000000.0ns"
@@ -769,7 +775,9 @@ are recorded. Finally, the value of the instance of A that was rooted
in the configuration namespace is shown. In a real ns-3 program, many
more models, attributes, and defaults would be shown.
An XML version also exists in ``output-attributes.xml``:::
An XML version also exists in ``output-attributes.xml``:
.. sourcecode:: xml
<?xml version="1.0" encoding="UTF-8"?>
<ns3>
@@ -858,13 +866,17 @@ in the `|ns3| Overview <http://www.nsnam.org/docs/ns-3-overview.pdf>`_
presentation.
To use this feature, one must install libgtk and libgtk-dev; an example
Ubuntu installation command is:::
Ubuntu installation command is:
sudo apt-get install libgtk2.0-0 libgtk2.0-dev
.. sourcecode:: bash
To check whether it is configured or not, check the output of the step:::
$ sudo apt-get install libgtk2.0-0 libgtk2.0-dev
./waf configure --enable-examples --enable-tests
To check whether it is configured or not, check the output of the step:
.. sourcecode:: bash
$ ./waf configure --enable-examples --enable-tests
---- Summary of optional NS-3 features:
Python Bindings : enabled
@@ -873,10 +885,12 @@ To check whether it is configured or not, check the output of the step:::
GtkConfigStore : not enabled (library 'gtk+-2.0 >= 2.12' not found)
In the above example, it was not enabled, so it cannot be used until a suitable
version is installed and::
version is installed and:
./waf configure --enable-examples --enable-tests
./waf
.. sourcecode:: bash
$ ./waf configure --enable-examples --enable-tests
$ ./waf
is rerun.
@@ -895,6 +909,7 @@ when you are done.
Future work
+++++++++++
There are a couple of possible improvements:
* save a unique version number with date and time at start of file
* save rng initial seed somewhere.
* make each RandomVariable serialize its own initial seed and re-read it later

11
doc/manual/source/callbacks.rst
View File

@@ -1,4 +1,5 @@
.. include:: replace.txt
.. highlight:: cpp
Callbacks
---------
@@ -364,11 +365,11 @@ Now, we need to tie together this callback instance and the actual target functi
callback-- this is important. We can pass in any such properly-typed function
to this callback. Let's look at this more closely::
static double CbOne (double a, double b) {}
^ ^ ^
| ---| ------|
| | |
Callback<double, double, double> one;
static double CbOne (double a, double b) {}
^ ^ ^
| | |
| | |
Callback<double, double, double> one;
You can only bind a function to a callback if they have the matching signature.
The first template argument is the return type, and the additional template

71
doc/manual/source/enable-modules.rst
View File

@@ -1,4 +1,5 @@
.. include:: replace.txt
.. highlight:: bash
Enabling Subsets of |ns3| Modules
---------------------------------
@@ -10,11 +11,15 @@ This chapter discusses how to enable only the |ns3| modules that you are interst
How to enable a subset of |ns3|'s modules
*****************************************
If shared libraries are being built, then enabling a module will cause at least one library to be built: ::
If shared libraries are being built, then enabling a module will cause at least one library to be built:
.. sourcecode:: text
libns3-modulename.so
If the module has a test library and test libraries are being built, then ::
If the module has a test library and test libraries are being built, then
.. sourcecode:: text
libns3-modulename-test.so
@@ -31,29 +36,37 @@ Enable modules using waf's --enable-modules option
To enable only the core module with example and tests, for example,
try these commands: ::
./waf clean
./waf configure --enable-examples --enable-tests --enable-modules=core
./waf build
cd build/debug/
ls
$ ./waf clean
$ ./waf configure --enable-examples --enable-tests --enable-modules=core
$ ./waf build
$ cd build/debug/
$ ls
and the following libraries should be present: ::
and the following libraries should be present:
.. sourcecode:: text
bindings libns3-core.so ns3 scratch utils
examples libns3-core-test.so samples src
Note the ``./waf clean`` step is done here only to make it more obvious which module libraries were built. You don't have to do ``./waf clean`` in order to enable subsets of modules.
Running test.py will cause only those tests that depend on module core to be run: ::
Running test.py will cause only those tests that depend on module core to be run:
.. sourcecode:: text
24 of 24 tests passed (24 passed, 0 skipped, 0 failed, 0 crashed, 0 valgrind errors)
Repeat the above steps for the "network" module instead of the "core" module, and the following will be built, since network depends on core: ::
Repeat the above steps for the "network" module instead of the "core" module, and the following will be built, since network depends on core:
.. sourcecode:: text
bindings libns3-core.so libns3-network.so ns3 scratch utils
examples libns3-core-test.so libns3-network-test.so samples src
Running test.py will cause those tests that depend on only the core and network modules to be run: ::
Running test.py will cause those tests that depend on only the core and network modules to be run:
.. sourcecode:: text
31 of 31 tests passed (31 passed, 0 skipped, 0 failed, 0 crashed, 0 valgrind errors)
@@ -74,9 +87,11 @@ The maintained version of the .ns3rc file in the |ns3| source code repository re
Assuming that you are in the top level |ns3| directory, you can get a copy of the .ns3rc file that is in the ``utils`` directory as follows: ::
cp utils/.ns3rc .
$ cp utils/.ns3rc .
The .ns3rc file should now be in your top level |ns3| directory, and it contains the following: ::
The .ns3rc file should now be in your top level |ns3| directory, and it contains the following:
.. sourcecode:: python
#! /usr/bin/env python
@@ -92,7 +107,9 @@ The .ns3rc file should now be in your top level |ns3| directory, and it contains
# Set this equal to true if you want tests to be run.
tests_enabled = False
Use your favorite editor to modify the .ns3rc file to only enable the core module with examples and tests like this: ::
Use your favorite editor to modify the .ns3rc file to only enable the core module with examples and tests like this:
.. sourcecode:: python
#! /usr/bin/env python
@@ -110,28 +127,36 @@ Use your favorite editor to modify the .ns3rc file to only enable the core modul
Only the core module will be enabled now if you try these commands: ::
./waf clean
./waf configure
./waf build
cd build/debug/
ls
$ ./waf clean
$ ./waf configure
$ ./waf build
$ cd build/debug/
$ ls
and the following libraries should be present: ::
and the following libraries should be present:
.. sourcecode:: text
bindings libns3-core.so ns3 scratch utils
examples libns3-core-test.so samples src
Note the ``./waf clean`` step is done here only to make it more obvious which module libraries were built. You don't have to do ``./waf clean`` in order to enable subsets of modules.
Running test.py will cause only those tests that depend on module core to be run: ::
Running test.py will cause only those tests that depend on module core to be run:
.. sourcecode:: text
24 of 24 tests passed (24 passed, 0 skipped, 0 failed, 0 crashed, 0 valgrind errors)
Repeat the above steps for the "network" module instead of the "core" module, and the following will be built, since network depends on core: ::
Repeat the above steps for the "network" module instead of the "core" module, and the following will be built, since network depends on core:
.. sourcecode:: text
bindings libns3-core.so libns3-network.so ns3 scratch utils
examples libns3-core-test.so libns3-network-test.so samples src
Running test.py will cause those tests that depend on only the core and network modules to be run: ::
Running test.py will cause those tests that depend on only the core and network modules to be run:
.. sourcecode:: text
31 of 31 tests passed (31 passed, 0 skipped, 0 failed, 0 crashed, 0 valgrind errors)

56
doc/manual/source/enable-tests.rst
View File

@@ -1,4 +1,6 @@
.. include:: replace.txt
.. highlight:: bash
Enabling/disabling |ns3| Tests and Examples
-------------------------------------------
@@ -26,18 +28,22 @@ By default, examples and tests are not built in |ns3|.
From the ns-3-allinone directory, you can build |ns3| without any
examples or tests simply by doing: ::
./build.py
$ ./build.py
Running test.py in the top level |ns3| directory now will cause no examples or tests to be run: ::
Running test.py in the top level |ns3| directory now will cause no examples or tests to be run:
.. sourcecode:: text
0 of 0 tests passed (0 passed, 0 skipped, 0 failed, 0 crashed, 0 valgrind errors)
If you would like build |ns3| with examples and tests, then do the following from the ns-3-allinone directory: ::
./build.py --enable-examples --enable-tests
$ ./build.py --enable-examples --enable-tests
Running test.py in the top level |ns3| directory will cause all of the examples and tests to be run: ::
Running test.py in the top level |ns3| directory will cause all of the examples and tests to be run:
.. sourcecode:: text
170 of 170 tests passed (170 passed, 0 skipped, 0 failed, 0 crashed, 0 valgrind errors)
Enable/disable examples and tests using waf
@@ -50,20 +56,24 @@ By default, examples and tests are not built in |ns3|.
From the top level |ns3| directory, you can build |ns3| without any
examples or tests simply by doing: ::
./waf configure
./waf build
$ ./waf configure
$ ./waf build
Running test.py now will cause no examples or tests to be run: ::
Running test.py now will cause no examples or tests to be run:
.. sourcecode:: text
0 of 0 tests passed (0 passed, 0 skipped, 0 failed, 0 crashed, 0 valgrind errors)
If you would like build |ns3| with examples and tests, then do the following from the top level |ns3| directory: ::
./waf configure --enable-examples --enable-tests
./waf build
$ ./waf configure --enable-examples --enable-tests
$ ./waf build
Running test.py will cause all of the examples and tests to be run: ::
Running test.py will cause all of the examples and tests to be run:
.. sourcecode:: text
170 of 170 tests passed (170 passed, 0 skipped, 0 failed, 0 crashed, 0 valgrind errors)
Enable/disable examples and tests using the |ns3| configuration file
@@ -84,9 +94,11 @@ The maintained version of the .ns3rc file in the |ns3| source code repository re
Assuming that you are in the top level |ns3| directory, you can get a copy of the .ns3rc file that is in the ``utils`` directory as follows: ::
cp utils/.ns3rc .
$ cp utils/.ns3rc .
The .ns3rc file should now be in your top level |ns3| directory, and it contains the following: ::
The .ns3rc file should now be in your top level |ns3| directory, and it contains the following:
.. sourcecode:: python
#! /usr/bin/env python
@@ -105,16 +117,20 @@ The .ns3rc file should now be in your top level |ns3| directory, and it contains
From the top level |ns3| directory, you can build |ns3| without any
examples or tests simply by doing: ::
./waf configure
./waf build
$ ./waf configure
$ ./waf build
Running test.py now will cause no examples or tests to be run: ::
Running test.py now will cause no examples or tests to be run:
.. sourcecode:: text
0 of 0 tests passed (0 passed, 0 skipped, 0 failed, 0 crashed, 0 valgrind errors)
If you would like build |ns3| with examples and tests, use your
favorite editor to change the values in the .ns3rc file for
examples_enabled and tests_enabled file to be True: ::
examples_enabled and tests_enabled file to be True:
.. sourcecode:: python
#! /usr/bin/env python
@@ -133,9 +149,11 @@ examples_enabled and tests_enabled file to be True: ::
From the top level |ns3| directory, you can build |ns3| with examples
and tests simply by doing: ::
./waf configure
./waf build
$ ./waf configure
$ ./waf build
Running test.py will cause all of the examples and tests to be run: ::
Running test.py will cause all of the examples and tests to be run:
.. sourcecode:: text
170 of 170 tests passed (170 passed, 0 skipped, 0 failed, 0 crashed, 0 valgrind errors)

6
doc/manual/source/events.rst
View File

@@ -1,4 +1,6 @@
.. include:: replace.txt
.. highlight:: cpp
.. heading hierarchy:
------------- Chapter
@@ -42,7 +44,7 @@ Simulator
The Simulator class is the public entry point to access event scheduling
facilities. Once a couple of events have been scheduled to start the
simulation, the user can start to execute them by entering the simulator
main loop (call Simulator::Run). Once the main loop starts running, it
main loop (call ``Simulator::Run``). Once the main loop starts running, it
will sequentially execute all scheduled events in order from oldest to
most recent until there are either no more events left in the event
queue or Simulator::Stop has been called.
@@ -70,7 +72,7 @@ might write this:
Which will output:
::
.. sourcecode:: text
handler called with argument arg0=10 and arg1=5

45
doc/manual/source/gnuplot.rst
View File

@@ -1,5 +1,6 @@
.. include:: replace.txt
.. highlight:: cpp
Making Plots using the Gnuplot Class
------------------------------------
@@ -25,39 +26,51 @@ See the code from the example plots that are discussed below for details on step
An Example Program that Uses the Gnuplot Class
**********************************************
An example program that uses |ns3|'s Gnuplot class can be found here: ::
An example program that uses |ns3|'s Gnuplot class can be found here:
.. sourcecode:: bash
src/stats/examples/gnuplot-example.cc
In order to run this example, do the following: ::
In order to run this example, do the following:
./waf shell
cd build/debug/src/stats/examples
./gnuplot-example
.. sourcecode:: bash
This should produce the following gnuplot control files in the directory where the example is located: ::
$ ./waf shell
$ cd build/debug/src/stats/examples
$ ./gnuplot-example
This should produce the following gnuplot control files in the directory where the example is located:
.. sourcecode:: text
plot-2d.plt
plot-2d-with-error-bars.plt
plot-3d.plt
In order to process these gnuplot control files, do the following: ::
In order to process these gnuplot control files, do the following:
gnuplot plot-2d.plt
gnuplot plot-2d-with-error-bars.plt
gnuplot plot-3d.plt
.. sourcecode:: bash
This should produce the following graphics files in the directory where the example is located: ::
$ gnuplot plot-2d.plt
$ gnuplot plot-2d-with-error-bars.plt
$ gnuplot plot-3d.plt
This should produce the following graphics files in the directory where the example is located:
.. sourcecode:: text
plot-2d.png
plot-2d-with-error-bars.png
plot-3d.png
You can view these graphics files in your favorite graphics viewer. If you have gimp installed on your machine, for example, you can do this: ::
You can view these graphics files in your favorite graphics viewer. If you have gimp installed on your machine, for example, you can do this:
gimp plot-2d.png
gimp plot-2d-with-error-bars.png
gimp plot-3d.png
.. sourcecode:: bash
$ gimp plot-2d.png
$ gimp plot-2d-with-error-bars.png
$ gimp plot-3d.png
An Example 2-Dimensional Plot
*****************************

1
doc/manual/source/hash-functions.rst
View File

@@ -1,4 +1,5 @@
.. include:: replace.txt
.. highlight:: cpp
Hash Functions
----------------

1
doc/manual/source/helpers.rst
View File

@@ -1,4 +1,5 @@
.. include:: replace.txt
.. highlight:: cpp
Helpers
-------

9
doc/manual/source/how-to-write-tests.rst
View File

@@ -1,4 +1,5 @@
.. include:: replace.txt
.. highlight:: cpp
How to write tests
------------------
@@ -46,7 +47,7 @@ more descriptive test case name.
You also need to add a block into your wscript to get this test to
compile:
::
.. sourcecode:: python
module_test.source = [
'test/router-test-suite.cc',
@@ -64,13 +65,13 @@ is called "router" such as here:
Try this command:
::
.. sourcecode:: bash
./test.py -s router
$ ./test.py -s router
Output such as below should be produced:
::
.. sourcecode:: text
PASS: TestSuite router
1 of 1 tests passed (1 passed, 0 skipped, 0 failed, 0 crashed, 0 valgrind errors)

11
doc/manual/source/logging.rst
View File

@@ -1,4 +1,5 @@
.. include:: replace.txt
.. highlight:: cpp
.. heading hierarchy:
------------- Chapter
@@ -71,7 +72,7 @@ Logging prefixes
This section still needs documentation; bug 1496 is open on this:
::
.. sourcecode:: bash
$ NS_LOG="*=all|prefix_all" ./waf --run scratch-simulator
Scratch Simulator
@@ -88,16 +89,16 @@ Enabling logging output
There are two ways that users typically control logging output. The
first is by setting an ``NS_LOG`` environment variable; e.g.:
::
.. sourcecode:: bash
NS_LOG="*" ./waf --run first
$ NS_LOG="*" ./waf --run first
will run the first tutorial program with all logging output. This can
be made more granular by selecting individual components:
::
.. sourcecode:: bash
NS_LOG="Ipv4L3Protocol" ./waf --run first
$ NS_LOG="Ipv4L3Protocol" ./waf --run first
The second way to enable this is to use explicit statements in your
program, such as in the first tutorial program:

5
doc/manual/source/new-models.rst
View File

@@ -1,4 +1,5 @@
.. include:: replace.txt
.. highlight:: cpp
Creating a new ns-3 model
-------------------------
@@ -408,7 +409,7 @@ Add basic support in the class
::
point-to-point-net-device.h
/* point-to-point-net-device.h */
class ErrorModel;
/**
@@ -473,7 +474,7 @@ Create null functional script
::
simple-error-model.cc
/* simple-error-model.cc */
// Error model
// We want to add an error model to node 3's NetDevice

121
doc/manual/source/new-modules.rst
View File

@@ -1,4 +1,5 @@
.. include:: replace.txt
.. highlight:: cpp
Adding a New Module to |ns3|
----------------------------
@@ -20,7 +21,9 @@ example, the spectrum module can be found here: ::
src/spectrum
A prototypical module has the following directory structure and
required files: ::
required files:
.. sourcecode:: text
src/
module-name/
@@ -39,29 +42,39 @@ Not all directories will be present in each module.
Step 2 - Create your new module based on the template module
************************************************************
A python program is provided in the source directory that will create a skeleton for a new module ::
A python program is provided in the source directory that will create a skeleton for a new module
src/create-module.py
.. sourcecode:: bash
For the purposes of this discussion we will assume that your new module is called "new-module". From the ``src`` directory, do the following to create the new module: ::
$ src/create-module.py
./create-module.py new-module
For the purposes of this discussion we will assume that your new module is called "new-module". From the ``src`` directory, do the following to create the new module:
Next, cd into ``new-module``; you will find this directory layout: ::
.. sourcecode:: bash
examples helper model test wscript
$ ./create-module.py new-module
Next, cd into ``new-module``; you will find this directory layout:
.. sourcecode:: text
$ examples helper model test wscript
We next walk through how to customize this module. All |ns3| modules
depend on the 'core' module and usually on other modules. This
dependency is specified in the wscript file.
Let's assume that 'new-module' depends on the internet,
mobility, and aodv modules. Then the call to the function that will
create this module should look like this before editing: ::
create this module should look like this before editing:
.. sourcecode:: python
def build(bld):
module = bld.create_ns3_module('new-module', ['core'])
and after editing: ::
and after editing:
.. sourcecode:: python
def build(bld):
module = bld.create_ns3_module('new-module', ['internet', 'mobility', 'aodv'])
@@ -82,18 +95,24 @@ Step 3 - Adding to your module's source files
*********************************************
If your new module has model and/or helper source files, then they
must be specified in your ::
must be specified in your
.. sourcecode:: text
src/new-module/wscript
file by modifying it with your text editor.
As an example, the source files for the spectrum module are specified
in ::
in
.. sourcecode:: text
src/spectrum/wscript
with the following list of source files: ::
with the following list of source files:
.. sourcecode:: python
module.source = [
'model/spectrum-model.cc',
@@ -112,20 +131,26 @@ Step 4 - Specify your module's header files
*******************************************
If your new module has model and/or helper header files, then they
must be specified in your ::
must be specified in your
.. sourcecode:: text
src/new-module/wscript
file by modifying it with your text editor.
As an example, the header files for the spectrum module are specified
in ::
in
.. sourcecode:: text
src/spectrum/wscript
with the following function call, module name, and list of header
files. Note that the argument for the function new_task_gen() tells
waf to install this module's headers with the other |ns3| headers: ::
waf to install this module's headers with the other |ns3| headers:
.. sourcecode:: python
headers = bld.new_task_gen(features=['ns3header'])
@@ -147,17 +172,23 @@ waf to install this module's headers with the other |ns3| headers: ::
Step 5 - Specify your module's tests
************************************
If your new module has tests, then they must be specified in your ::
If your new module has tests, then they must be specified in your
.. sourcecode:: text
src/new-module/wscript
file by modifying it with your text editor.
As an example, the tests for the spectrum module are specified in ::
As an example, the tests for the spectrum module are specified in
.. sourcecode:: text
src/spectrum/wscript
with the following function call and list of test suites: ::
with the following function call and list of test suites:
.. sourcecode:: python
module_test = bld.create_ns3_module_test_library('spectrum')
@@ -170,20 +201,26 @@ with the following function call and list of test suites: ::
Step 6 - Specify your module's examples
***************************************
If your new module has examples, then they must be specified in your ::
If your new module has examples, then they must be specified in your
.. sourcecode:: text
src/new-module/examples/wscript
file by modifying it with your text editor.
As an example, the examples for the core module are specified in ::
As an example, the examples for the core module are specified in
.. sourcecode:: text
src/core/examples/wscript
The core module's C++ examples are specified using the following
function calls and source file names. Note that the second argument
for the function ``create_ns3_program()`` is the list of modules that the
program being created depends on: ::
program being created depends on:
.. sourcecode:: python
obj = bld.create_ns3_program('main-callback', ['core'])
obj.source = 'main-callback.cc'
@@ -194,7 +231,9 @@ program being created depends on: ::
The core module's Python examples are specified using the following
function call. Note that the second argument for the function
register_ns3_script() is the list of modules that the Python example
depends on: ::
depends on:
.. sourcecode:: python
bld.register_ns3_script('sample-simulator.py', ['core'])
@@ -207,11 +246,15 @@ are suitable for regression tests. A file called ``examples-to-run.py``
that exists in each module's test directory can control the invocation
of the examples when the test framework runs.
As an example, the examples that are run by ``test.py`` for the core module are specified in ::
As an example, the examples that are run by ``test.py`` for the core module are specified in
.. sourcecode:: text
src/core/test/examples-to-run.py
using the following two lists of C++ and Python examples: ::
using the following two lists of C++ and Python examples:
.. sourcecode:: python
# A list of C++ examples to run in order to ensure that they remain
# buildable and runnable over time. Each tuple in the list contains
@@ -238,7 +281,9 @@ using the following two lists of C++ and Python examples: ::
("sample-simulator.py", "True"),
]
Each tuple in the C++ list of examples to run contains ::
Each tuple in the C++ list of examples to run contains
.. sourcecode:: python
(example_name, do_run, do_valgrind_run)
@@ -249,11 +294,15 @@ is needed because NSC causes illegal instruction crashes with
some tests when they are run under valgrind.
Note that the two conditions are Python statements that
can depend on waf configuration variables. For example, ::
can depend on waf configuration variables. For example,
.. sourcecode:: python
("tcp-nsc-lfn", "NSC_ENABLED == True", "NSC_ENABLED == False"),
Each tuple in the Python list of examples to run contains ::
Each tuple in the Python list of examples to run contains
.. sourcecode:: python
(example_name, do_run)
@@ -261,12 +310,16 @@ where example_name is the Python script to be run and
do_run is a condition under which to run the example.
Note that the condition is a Python statement that can
depend on waf configuration variables. For example, ::
depend on waf configuration variables. For example,
.. sourcecode:: python
("realtime-udp-echo.py", "ENABLE_REAL_TIME == False"),
If your new module has examples, then you must specify which of them
should be run in your ::
should be run in your
.. sourcecode:: text
src/new-module/test/examples-to-run.py
@@ -276,10 +329,12 @@ test.py.
Step 8 - Build and test your new module
***************************************
You can now build and test your module as normal: ::
You can now build and test your module as normal:
./waf configure --enable-examples --enable-tests
./waf build
./test.py
.. sourcecode:: bash
$ ./waf configure --enable-examples --enable-tests
$ ./waf build
$ ./test.py
and look for your new module's test suite (and example programs, if enabled) in the test output.

1
doc/manual/source/object-model.rst
View File

@@ -1,4 +1,5 @@
.. include:: replace.txt
.. highlight:: cpp
.. _Object-model:

1
doc/manual/source/object-names.rst
View File

@@ -1,4 +1,5 @@
.. include:: replace.txt
.. highlight:: cpp
.. _Object-names:

1
doc/manual/source/organization.rst
View File

@@ -1,4 +1,5 @@
.. include:: replace.txt
.. highlight:: cpp
Organization

50
doc/manual/source/python.rst
View File

@@ -1,4 +1,5 @@
.. include:: replace.txt
.. highlight:: python
Using Python to Run |ns3|
-------------------------
@@ -74,30 +75,30 @@ Running Python Scripts
waf contains some options that automatically update the python path to find the ns3 module. To run example programs, there are two ways to use waf to take care of this. One is to run a waf shell; e.g.:
::
.. sourcecode:: bash
./waf --shell
python examples/wireless/mixed-wireless.py
$ ./waf --shell
$ python examples/wireless/mixed-wireless.py
and the other is to use the --pyrun option to waf:
::
.. sourcecode:: bash
./waf --pyrun examples/wireless/mixed-wireless.py
$ ./waf --pyrun examples/wireless/mixed-wireless.py
To run a python script under the C debugger:
::
.. sourcecode:: bash
./waf --shell
gdb --args python examples/wireless/mixed-wireless.py
$ ./waf --shell
$ gdb --args python examples/wireless/mixed-wireless.py
To run your own Python script that calls |ns3| and that has this path, ``/path/to/your/example/my-script.py``, do the following:
::
.. sourcecode:: bash
./waf --shell
python /path/to/your/example/my-script.py
$ ./waf --shell
$ python /path/to/your/example/my-script.py
Caveats
*******
@@ -118,9 +119,9 @@ Most of the missing APIs can be wrapped, given enough time, patience, and expert
Conversion Constructors
+++++++++++++++++++++++
Conversion constructors (http://publib.boulder.ibm.com/infocenter/compbgpl/v9v111/topic/com.ibm.xlcpp9.bg.doc/language_ref/cplr384.htm) are not fully supported yet by PyBindGen, and they always act as explicit constructors when translating an API into Python. For example, in C++ you can do this:
`Conversion constructors <http://publib.boulder.ibm.com/infocenter/compbgpl/v9v111/topic/com.ibm.xlcpp9.bg.doc/language_ref/cplr384.htm>`_ are not fully supported yet by PyBindGen, and they always act as explicit constructors when translating an API into Python. For example, in C++ you can do this:
::
.. sourcecode:: cpp
Ipv4AddressHelper ipAddrs;
ipAddrs.SetBase ("192.168.0.0", "255.255.255.0");
@@ -188,9 +189,9 @@ will probably have to be that we disable python bindings in CygWin.
If you really care about Python bindings on Windows, try building with mingw and native
python instead. Or else, to build without python bindings, disable python bindings in the configuration stage:
::
.. sourcecode:: bash
./waf configure --disable-python
$ ./waf configure --disable-python
Working with Python Bindings
****************************
@@ -211,9 +212,9 @@ The process by which Python bindings are handled is the following:
If something goes wrong with compiling Python bindings and you just want to ignore them and move on with C++, you can disable Python with:
::
.. sourcecode:: bash
./waf --disable-python
$ ./waf --disable-python
Instructions for Handling New Files or Changed API's
****************************************************
@@ -230,9 +231,9 @@ Scanning the Monolithic Python Bindings
To scan the monolithic Python bindings do the following:
::
.. sourcecode:: bash
./waf --python-scan
$ ./waf --python-scan
Organization of the Monolithic Python Bindings
++++++++++++++++++++++++++++++++++++++++++++++
@@ -269,15 +270,15 @@ Scanning the Modular Python Bindings
To scan the modular Python bindings for the core module, for example, do the following:
::
.. sourcecode:: bash
./waf --apiscan=core
$ ./waf --apiscan=core
To scan the modular Python bindings for all of the modules, do the following:
::
.. sourcecode:: bash
./waf --apiscan=all
$ ./waf --apiscan=all
Creating a New Module
+++++++++++++++++++++
@@ -311,5 +312,4 @@ The ``src/<module>/bindings`` directory may contain the following files, some of
More Information for Developers
*******************************
If you are a developer and need more information on |ns3|'s Python bindings, please see the Python Bindings wiki page at
`<http://www.nsnam.org/wiki/index.php/NS-3_Python_Bindings>`_.
If you are a developer and need more information on |ns3|'s Python bindings, please see the `Python Bindings wiki page <http://www.nsnam.org/wiki/index.php/NS-3_Python_Bindings>`_.

43
doc/manual/source/random-variables.rst
View File

@@ -1,4 +1,5 @@
.. include:: replace.txt
.. highlight:: cpp
Random Variables
----------------
@@ -125,7 +126,7 @@ run number behavior. This seeding and substream state setting must be called
before any random variables are created; e.g::
RngSeedManager::SetSeed (3); // Changes seed from default of 1 to 3
RngSeedManager::SetRun (7); // Changes run number from default of 1 to 7
RngSeedManager::SetRun (7); // Changes run number from default of 1 to 7
// Now, create random variables
Ptr<UniformRandomVariable> x = CreateObject<UniformRandomVariable> ();
Ptr<ExponentialRandomVariable> y = CreateObject<ExponentialRandomVarlable> ();
@@ -143,18 +144,24 @@ independent replications using the substreams.
For ease of use, it is not necessary to control the seed and run number from
within the program; the user can set the ``NS_GLOBAL_VALUE`` environment
variable as follows::
variable as follows:
NS_GLOBAL_VALUE="RngRun=3" ./waf --run program-name
.. sourcecode:: bash
$ NS_GLOBAL_VALUE="RngRun=3" ./waf --run program-name
Another way to control this is by passing a command-line argument; since this is
an |ns3| GlobalValue instance, it is equivalently done such as follows::
an |ns3| GlobalValue instance, it is equivalently done such as follows:
./waf --command-template="%s --RngRun=3" --run program-name
.. sourcecode:: bash
or, if you are running programs directly outside of waf::
$ ./waf --command-template="%s --RngRun=3" --run program-name
./build/optimized/scratch/program-name --RngRun=3
or, if you are running programs directly outside of waf:
.. sourcecode:: bash
$ ./build/optimized/scratch/program-name --RngRun=3
The above command-line variants make it easy to run lots of different
runs from a shell script by just passing a different RngRun index.
@@ -177,7 +184,9 @@ Base class public API
*********************
Below are excerpted a few public methods of class :cpp:class:`RandomVariableStream`
that access the next value in the substream.::
that access the next value in the substream.
::
/**
* \brief Returns a random double from the underlying distribution
@@ -226,7 +235,7 @@ handled by smart pointers.
RandomVariableStream instances can also be used in |ns3| attributes, which means
that values can be set for them through the |ns3| attribute system.
An example is in the propagation models for WifiNetDevice:::
An example is in the propagation models for WifiNetDevice::
TypeId
RandomPropagationDelayModel::GetTypeId (void)
@@ -278,20 +287,20 @@ of the base class RandomVariableStream.
By partitioning the existing sequence of streams from before:
::
.. sourcecode:: text
<-------------------------------------------------------------------------->
stream 0 stream (2^64 - 1)
stream 0 stream (2^64 - 1)
into two equal-sized sets:
::
.. sourcecode:: text
<--------------------------------------------------------------------------->
^ ^^ ^
| || |
stream 0 stream (2^63 - 1) stream 2^63 stream (2^64 - 1)
<- automatically assigned -----><-------- assigned by user----------->
<-------------------------------------------------------------------------->
^ ^^ ^
| || |
stream 0 stream (2^63 - 1) stream 2^63 stream (2^64 - 1)
<- automatically assigned -----------><- assigned by user ----------------->
The first 2^63 streams continue to be automatically assigned, while
the last 2^63 are given stream indices starting with zero up to

7
doc/manual/source/realtime.rst
View File

@@ -1,4 +1,5 @@
.. include:: replace.txt
.. highlight:: cpp
RealTime
--------
@@ -61,9 +62,11 @@ perspective. Users just need to set the attribute
StringValue ("ns3::RealtimeSimulatorImpl"));
There is a script in ``examples/realtime/realtime-udp-echo.cc`` that
has an example of how to configure the realtime behavior. Try: ::
has an example of how to configure the realtime behavior. Try:
./waf --run realtime-udp-echo
.. sourcecode:: bash
$ ./waf --run realtime-udp-echo
Whether the simulator will work in a best effort or hard limit policy fashion is
governed by the attributes explained in the previous section.

106
doc/manual/source/test-framework.rst
View File

@@ -1,4 +1,5 @@
.. include:: replace.txt
.. highlight:: bash
Testing framework
-----------------
@@ -27,7 +28,9 @@ properly on all of its supported systems.
Users (and developers) typically will not interact with the buildbot system other
than to read its messages regarding test results. If a failure is detected in
one of the automated build and test jobs, the buildbot will send an email to the
*ns-developers* mailing list. This email will look something like::
*ns-developers* mailing list. This email will look something like
.. sourcecode: text
The Buildbot has detected a new failure of osx-ppc-g++-4.2 on NsNam.
Full details are available at:
@@ -69,20 +72,20 @@ have been built by doing the following
::
./waf configure --enable-examples --enable-tests
./waf
$ ./waf configure --enable-examples --enable-tests
$ ./waf
By default, ``test.py`` will run all available tests and report status
back in a very concise form. Running the command
::
./test.py
$ ./test.py
will result in a number of ``PASS``, ``FAIL``, ``CRASH`` or ``SKIP``
indications followed by the kind of test that was run and its display name.
::
.. sourcecode:: text
Waf: Entering directory `/home/craigdo/repos/ns-3-allinone-test/ns-3-dev/build'
Waf: Leaving directory `/home/craigdo/repos/ns-3-allinone-test/ns-3-dev/build'
@@ -103,7 +106,7 @@ in determining if changes they have made have caused any regressions.
There are a number of options available to control the behavior of ``test.py``.
if you run ``test.py --help`` you should see a command summary like:
::
.. sourcecode:: text
Usage: test.py [options]
@@ -145,7 +148,7 @@ nightly builds using
::
./test.py --html=nightly.html
$ ./test.py --html=nightly.html
In this case, an HTML file named ''nightly.html'' would be created with a pretty
summary of the testing done. A ''human readable'' format is available for users
@@ -153,7 +156,7 @@ interested in the details.
::
./test.py --text=results.txt
$ ./test.py --text=results.txt
In the example above, the test suite checking the |ns3| wireless
device propagation loss models failed. By default no further information is
@@ -164,17 +167,17 @@ to be specified. Running the command
::
./test.py --suite=ns3-wifi-propagation-loss-models
$ ./test.py --suite=ns3-wifi-propagation-loss-models
or equivalently
::
./test.py -s ns3-wifi-propagation-loss-models
$ ./test.py -s ns3-wifi-propagation-loss-models
results in that single test suite being run.
::
.. sourcecode:: text
FAIL: TestSuite ns3-wifi-propagation-loss-models
@@ -182,13 +185,14 @@ To find detailed information regarding the failure, one must specify the kind
of output desired. For example, most people will probably be interested in
a text file::
./test.py --suite=ns3-wifi-propagation-loss-models --text=results.txt
$ ./test.py --suite=ns3-wifi-propagation-loss-models --text=results.txt
This will result in that single test suite being run with the test status written to
the file ''results.txt''.
You should find something similar to the following in that file::
You should find something similar to the following in that file
.. sourcecode:: text
FAIL: Test Suite ''ns3-wifi-propagation-loss-models'' (real 0.02 user 0.01 system 0.00)
PASS: Test Case "Check ... Friis ... model ..." (real 0.01 user 0.00 system 0.00)
@@ -222,21 +226,23 @@ changes to a repository. In this case, ``test.py`` can be told to constrain
the types of tests being run to a particular class of tests. The following
command will result in only the unit tests being run::
./test.py --constrain=unit
$ ./test.py --constrain=unit
Similarly, the following command will result in only the example smoke tests
being run::
./test.py --constrain=unit
$ ./test.py --constrain=unit
To see a quick list of the legal kinds of constraints, you can ask for them
to be listed. The following command
::
./test.py --kinds
$ ./test.py --kinds
will result in the following list being displayed::
will result in the following list being displayed:
.. sourcecode:: text
Waf: Entering directory `/home/craigdo/repos/ns-3-allinone-test/ns-3-dev/build'
Waf: Leaving directory `/home/craigdo/repos/ns-3-allinone-test/ns-3-dev/build'
@@ -256,9 +262,11 @@ to be listed. The following command,
::
./test.py --list
$ ./test.py --list
will result in a list of the test suite being displayed, similar to::
will result in a list of the test suite being displayed, similar to
.. sourcecode:: text
Waf: Entering directory `/home/craigdo/repos/ns-3-allinone-test/ns-3-dev/build'
Waf: Leaving directory `/home/craigdo/repos/ns-3-allinone-test/ns-3-dev/build'
@@ -291,11 +299,11 @@ for C++ examples do not have extensions. Entering
::
./test.py --example=udp-echo
$ ./test.py --example=udp-echo
results in that single example being run.
::
.. sourcecode:: text
PASS: Example examples/udp/udp-echo
@@ -304,7 +312,7 @@ You can specify the directory where ns-3 was built using the
::
./test.py --buildpath=/home/craigdo/repos/ns-3-allinone-test/ns-3-dev/build/debug --example=wifi-simple-adhoc
$ ./test.py --buildpath=/home/craigdo/repos/ns-3-allinone-test/ns-3-dev/build/debug --example=wifi-simple-adhoc
One can run a single Python example program using the ``--pyexample``
option. Note that the relative path for the example must be included
@@ -312,11 +320,11 @@ and that Python examples do need their extensions. Entering
::
./test.py --pyexample=examples/tutorial/first.py
$ ./test.py --pyexample=examples/tutorial/first.py
results in that single example being run.
::
.. sourcecode:: text
PASS: Example examples/tutorial/first.py
@@ -344,9 +352,11 @@ option.
::
./test.py --list --nowaf
$ ./test.py --list --nowaf
will result in a list of the currently built test suites being displayed, similar to::
will result in a list of the currently built test suites being displayed, similar to:
.. sourcecode:: text
ns3-wifi-propagation-loss-models
ns3-tcp-cwnd
@@ -366,7 +376,7 @@ leaks. This can be selected by using the ``--grind`` option.
::
./test.py --grind
$ ./test.py --grind
As it runs, ``test.py`` and the programs that it runs indirectly, generate large
numbers of temporary files. Usually, the content of these files is not interesting,
@@ -378,7 +388,7 @@ Universal Time (also known as Greenwich Mean Time).
::
./test.py --retain
$ ./test.py --retain
Finally, ``test.py`` provides a ``--verbose`` option which will print
large amounts of information about its progress. It is not expected that this
@@ -386,13 +396,13 @@ will be terribly useful unless there is an error. In this case, you can get
access to the standard output and standard error reported by running test suites
and examples. Select verbose in the following way::
./test.py --verbose
$ ./test.py --verbose
All of these options can be mixed and matched. For example, to run all of the
ns-3 core test suites under valgrind, in verbose mode, while generating an HTML
output file, one would do::
./test.py --verbose --grind --constrain=core --html=results.html
$ ./test.py --verbose --grind --constrain=core --html=results.html
TestTaxonomy
************
@@ -480,7 +490,7 @@ stage, and also (optionally) examples if examples are to be checked:
::
./waf --configure --enable-examples --enable-tests
$ ./waf --configure --enable-examples --enable-tests
Then, build ns-3, and after it is built, just run ``test.py``. ``test.py -h``
will show a number of configuration options that modify the behavior
@@ -501,9 +511,11 @@ The main reason why ``test.py`` is not suitable for debugging is that it is not
In order to execute the test-runner, you run it like any other ns-3 executable
-- using ``waf``. To get a list of available options, you can type::
./waf --run "test-runner --help"
$ ./waf --run "test-runner --help"
You should see something like the following::
You should see something like the following
.. sourcecode:: text
Waf: Entering directory `/home/craigdo/repos/ns-3-allinone-test/ns-3-dev/build'
Waf: Leaving directory `/home/craigdo/repos/ns-3-allinone-test/ns-3-dev/build'
@@ -537,10 +549,10 @@ option something like,
::
./waf shell
cd build/debug/utils
gdb test-runner
run --suite=global-value --assert
$ ./waf shell
$ cd build/debug/utils
$ gdb test-runner
$ run --suite=global-value --assert
If an error is then found in the global-value test suite, a segfault would be
generated and the (source level) debugger would stop at the ``NS_TEST_ASSERT_MSG``
@@ -556,7 +568,7 @@ option for you. To run one of the tests directly from the test-runner
using ``waf``, you will need to specify the test suite to run along with
the base directory. So you could use the shell and do::
./waf --run "test-runner --basedir=`pwd` --suite=pcap-file-object"
$ ./waf --run "test-runner --basedir=`pwd` --suite=pcap-file-object"
Note the ''backward'' quotation marks on the ``pwd`` command.
@@ -601,7 +613,7 @@ output, run ``test.py`` with the "retain" option:
::
./test.py -r
$ ./test.py -r
and test output can be found in the ``testpy-output/`` directory.
@@ -619,11 +631,11 @@ Try,
::
./waf --run "test-runner --basedir=`pwd` --suite=pcap-file-object --out=myfile.xml"
$ ./waf --run "test-runner --basedir=`pwd` --suite=pcap-file-object --out=myfile.xml"
If you look at the file ``myfile.xml`` you should see something like,
::
.. sourcecode:: xml
<TestSuite>
<SuiteName>pcap-file-object</SuiteName>
@@ -669,7 +681,9 @@ section.
Debugging test suite failures
+++++++++++++++++++++++++++++
To debug test crashes, such as::
To debug test crashes, such as
.. sourcecode:: text
CRASH: TestSuite ns3-wifi-interference
@@ -677,7 +691,7 @@ You can access the underlying test-runner program via gdb as follows, and
then pass the "--basedir=`pwd`" argument to run (you can also pass other
arguments as needed, but basedir is the minimum needed)::
./waf --command-template="gdb %s" --run "test-runner"
$ ./waf --command-template="gdb %s" --run "test-runner"
Waf: Entering directory `/home/tomh/hg/sep09/ns-3-allinone/ns-3-dev-678/build'
Waf: Leaving directory `/home/tomh/hg/sep09/ns-3-allinone/ns-3-dev-678/build'
'build' finished successfully (0.380s)
@@ -699,7 +713,7 @@ such as::
VALGR: TestSuite devices-mesh-dot11s-regression
./waf --command-template="valgrind %s --basedir=`pwd` --suite=devices-mesh-dot11s-regression" --run test-runner
$ ./waf --command-template="valgrind %s --basedir=`pwd` --suite=devices-mesh-dot11s-regression" --run test-runner
Class TestRunner
****************
@@ -736,7 +750,7 @@ and perform these two duties.
The following code will define a new class that can be run by ``test.py``
as a ''unit'' test with the display name, ``my-test-suite-name``.
::
.. sourcecode:: cpp
class MySuite : public TestSuite
{
@@ -766,7 +780,7 @@ In order to create a new test case in the system, all one has to do is to inheri
from the ``TestCase`` base class, override the constructor to give the test
case a name and override the ``DoRun`` method to run the test.
::
.. sourcecode:: cpp
class MyTestCase : public TestCase
{

35
doc/manual/source/tracing.rst
View File

@@ -1,4 +1,7 @@
.. include:: replace.txt
.. highlight:: cpp
.. role:: raw-role(raw)
:format: html latex
Tracing
-------
@@ -269,7 +272,7 @@ aggregation model. The next path segment begins with the "$" character which
indicates a ``GetObject`` call should be made looking for the type that follows.
When a node is initialized by an ``InternetStackHelper`` a number of interfaces
are aggregated to the node. One of these is the TCP level four protocol. The
runtime type of this protocol object is "ns3::TcpL4Protocol". When the
runtime type of this protocol object is ``ns3::TcpL4Protocol''. When the
``GetObject`` is executed, it returns a pointer to the object of this type.
The ``TcpL4Protocol`` class defines an Attribute called "SocketList" which is a
@@ -342,14 +345,15 @@ stack helpers. Naturally, the trace files should follow a
The trace helpers therefore fall naturally into a two-dimensional taxonomy.
There are subtleties that prevent all four classes from behaving identically,
but we do strive to make them all work as similarly as possible; and whenever
possible there are analogs for all methods in all classes.::
possible there are analogs for all methods in all classes.
| pcap | ascii |
-----------------+------+-------|
Device Helper | | |
-----------------+------+-------|
Protocol Helper | | |
-----------------+------+-------|
+-----------------+----------------------+----------------------+
| \ | pcap | ascii |
+=================+======================+======================+
| Device Helper | :raw-role:`&#x2713;` | :raw-role:`&#x2713;` |
+-----------------+----------------------+----------------------+
| Protocol Helper | :raw-role:`&#x2713;` | :raw-role:`&#x2713;` |
+-----------------+----------------------+----------------------+
We use an approach called a ``mixin`` to add tracing functionality to our helper
classes. A ``mixin`` is a class that provides functionality to that is
@@ -393,11 +397,16 @@ Pcap Tracing Device Helper Methods
::
void EnablePcap (std::string prefix, Ptr<NetDevice> nd, bool promiscuous = false, bool explicitFilename = false);
void EnablePcap (std::string prefix, std::string ndName, bool promiscuous = false, bool explicitFilename = false);
void EnablePcap (std::string prefix, NetDeviceContainer d, bool promiscuous = false);
void EnablePcap (std::string prefix, NodeContainer n, bool promiscuous = false);
void EnablePcap (std::string prefix, uint32_t nodeid, uint32_t deviceid, bool promiscuous = false);
void EnablePcap (std::string prefix, Ptr<NetDevice> nd,
bool promiscuous = false, bool explicitFilename = false);
void EnablePcap (std::string prefix, std::string ndName,
bool promiscuous = false, bool explicitFilename = false);
void EnablePcap (std::string prefix, NetDeviceContainer d,
bool promiscuous = false);
void EnablePcap (std::string prefix, NodeContainer n,
bool promiscuous = false);
void EnablePcap (std::string prefix, uint32_t nodeid, uint32_t deviceid,
bool promiscuous = false);
void EnablePcapAll (std::string prefix, bool promiscuous = false);
In each of the methods shown above, there is a default parameter called

21
doc/manual/source/troubleshoot.rst
View File

@@ -1,4 +1,5 @@
.. include:: replace.txt
.. highlight:: bash
Troubleshooting
---------------
@@ -22,18 +23,20 @@ values are unexpectedly null.
Here is an example of what might occur:::
ns-old:~/ns-3-nsc$ ./waf --run tcp-point-to-point
Entering directory `/home/tomh/ns-3-nsc/build'
$ ./waf --run tcp-point-to-point
Entering directory '/home/tomh/ns-3-nsc/build'
Compilation finished successfully
Command ['/home/tomh/ns-3-nsc/build/debug/examples/tcp-point-to-point'] exited with code -11
The error message says that the program terminated unsuccessfully, but it is
not clear from this information what might be wrong. To examine more
closely, try running it under the `gdb debugger
<http://sources.redhat.com/gdb/>`_:::
<http://sources.redhat.com/gdb/>`_:
ns-old:~/ns-3-nsc$ ./waf --run tcp-point-to-point --command-template="gdb %s"
Entering directory `/home/tomh/ns-3-nsc/build'
.. sourcecode:: bash
$ ./waf --run tcp-point-to-point --command-template="gdb %s"
Entering directory '/home/tomh/ns-3-nsc/build'
Compilation finished successfully
GNU gdb Red Hat Linux (6.3.0.0-1.134.fc5rh)
Copyright 2004 Free Software Foundation, Inc.
@@ -66,7 +69,9 @@ argument to the command template "gdb %s".
This tells us that there was an attempt to dereference a null pointer
socketFactory.
Let's look around line 136 of tcp-point-to-point, as gdb suggests:::
Let's look around line 136 of tcp-point-to-point, as gdb suggests:
.. sourcecode:: cpp
Ptr<SocketFactory> socketFactory = n2->GetObject<SocketFactory> (Tcp::iid);
Ptr<Socket> localSocket = socketFactory->CreateSocket ();
@@ -77,6 +82,6 @@ may be null.
Sometimes you may need to use the `valgrind memory checker
<http://valgrind.org>`_ for more subtle errors. Again, you invoke the use of
valgrind similarly:::
valgrind similarly::
ns-old:~/ns-3-nsc$ ./waf --run tcp-point-to-point --command-template="valgrind %s"
$ ./waf --run tcp-point-to-point --command-template="valgrind %s"

5
doc/ns3_html_theme/static/ns3_stylesheet.css
View File

@@ -25,6 +25,11 @@ div.body h6 {
background-image: url('nav_f.png');
}
/* Sphinx figure captions */
p.caption {
font-weight: bold;
}
/* Doxygen side bar */
#nav-tree {
font-size: 12px;

127
doc/tutorial/source/building-topologies.rst
View File

@@ -1,5 +1,5 @@
.. include:: replace.txt
.. highlight:: cpp
Building Topologies
-------------------
@@ -337,10 +337,10 @@ the scratch directory and use waf to build just as you did with
the ``first.cc`` example. If you are in the top-level directory of the
repository you just type,
::
.. sourcecode:: bash
cp examples/tutorial/second.cc scratch/mysecond.cc
./waf
$ cp examples/tutorial/second.cc scratch/mysecond.cc
$ ./waf
Warning: We use the file ``second.cc`` as one of our regression tests to
verify that it works exactly as we think it should in order to make your
@@ -353,15 +353,15 @@ If you are following the tutorial religiously (you are, aren't you) you will
still have the NS_LOG variable set, so go ahead and clear that variable and
run the program.
::
.. sourcecode:: bash
export NS_LOG=
./waf --run scratch/mysecond
$ export NS_LOG=
$ ./waf --run scratch/mysecond
Since we have set up the UDP echo applications to log just as we did in
``first.cc``, you will see similar output when you run the script.
::
.. sourcecode:: text
Waf: Entering directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build'
Waf: Leaving directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build'
@@ -381,7 +381,7 @@ the server.
If you now go and look in the top level directory, you will find three trace
files:
::
.. sourcecode:: text
second-0-0.pcap second-1-0.pcap second-2-0.pcap
@@ -403,13 +403,13 @@ promiscuous-mode trace.
Now, let's follow the echo packet through the internetwork. First, do a
tcpdump of the trace file for the leftmost point-to-point node --- node zero.
::
.. sourcecode:: bash
tcpdump -nn -tt -r second-0-0.pcap
$ tcpdump -nn -tt -r second-0-0.pcap
You should see the contents of the pcap file displayed:
::
.. sourcecode:: text
reading from file second-0-0.pcap, link-type PPP (PPP)
2.000000 IP 10.1.1.1.49153 > 10.1.2.4.9: UDP, length 1024
@@ -422,14 +422,14 @@ device associated with IP address 10.1.1.1 headed for IP address
point-to-point link and be received by the point-to-point net device on node
one. Let's take a look:
::
.. sourcecode:: bash
tcpdump -nn -tt -r second-1-0.pcap
$ tcpdump -nn -tt -r second-1-0.pcap
You should now see the pcap trace output of the other side of the point-to-point
link:
::
.. sourcecode:: text
reading from file second-1-0.pcap, link-type PPP (PPP)
2.003686 IP 10.1.1.1.49153 > 10.1.2.4.9: UDP, length 1024
@@ -444,13 +444,13 @@ pop out on that device headed for its ultimate destination.
Remember that we selected node 2 as the promiscuous sniffer node for the CSMA
network so let's then look at second-2-0.pcap and see if its there.
::
.. sourcecode:: bash
tcpdump -nn -tt -r second-2-0.pcap
$ tcpdump -nn -tt -r second-2-0.pcap
You should now see the promiscuous dump of node two, device zero:
::
.. sourcecode:: text
reading from file second-2-0.pcap, link-type EN10MB (Ethernet)
2.003696 arp who-has 10.1.2.4 (ff:ff:ff:ff:ff:ff) tell 10.1.2.1
@@ -471,7 +471,7 @@ exchange, but is sniffing the network and reporting all of the traffic it sees.
This exchange is seen in the following lines,
::
.. sourcecode:: text
2.003696 arp who-has 10.1.2.4 (ff:ff:ff:ff:ff:ff) tell 10.1.2.1
2.003707 arp reply 10.1.2.4 is-at 00:00:00:00:00:06
@@ -479,7 +479,7 @@ This exchange is seen in the following lines,
Then node one, device one goes ahead and sends the echo packet to the UDP echo
server at IP address 10.1.2.4.
::
.. sourcecode:: text
2.003801 IP 10.1.1.1.49153 > 10.1.2.4.9: UDP, length 1024
@@ -490,40 +490,41 @@ routing and it has figured all of this out for us. But, the echo server node
doesn't know the MAC address of the first CSMA node, so it has to ARP for it
just like the first CSMA node had to do.
::
.. sourcecode:: text
2.003811 arp who-has 10.1.2.1 (ff:ff:ff:ff:ff:ff) tell 10.1.2.4
2.003822 arp reply 10.1.2.1 is-at 00:00:00:00:00:03
The server then sends the echo back to the forwarding node.
::
.. sourcecode:: text
2.003915 IP 10.1.2.4.9 > 10.1.1.1.49153: UDP, length 1024
Looking back at the rightmost node of the point-to-point link,
::
.. sourcecode:: bash
tcpdump -nn -tt -r second-1-0.pcap
$ tcpdump -nn -tt -r second-1-0.pcap
You can now see the echoed packet coming back onto the point-to-point link as
the last line of the trace dump.
::
.. sourcecode:: text
reading from file second-1-0.pcap, link-type PPP (PPP)
2.003686 IP 10.1.1.1.49153 > 10.1.2.4.9: UDP, length 1024
2.003915 IP 10.1.2.4.9 > 10.1.1.1.49153: UDP, length 1024
Lastly, you can look back at the node that originated the echo
::
tcpdump -nn -tt -r second-0-0.pcap
.. sourcecode:: bash
$ tcpdump -nn -tt -r second-0-0.pcap
and see that the echoed packet arrives back at the source at 2.007602 seconds,
::
.. sourcecode:: text
reading from file second-0-0.pcap, link-type PPP (PPP)
2.000000 IP 10.1.1.1.49153 > 10.1.2.4.9: UDP, length 1024
@@ -535,13 +536,13 @@ the same way as when we looked at changing the number of packets echoed in the
``first.cc`` example. Try running the program with the number of "extra"
devices set to four:
::
.. sourcecode:: bash
./waf --run "scratch/mysecond --nCsma=4"
$ ./waf --run "scratch/mysecond --nCsma=4"
You should now see,
::
.. sourcecode:: text
Waf: Entering directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build'
Waf: Leaving directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build'
@@ -602,20 +603,20 @@ 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,
::
.. sourcecode:: bash
rm *.pcap
rm *.tr
$ rm *.pcap
$ rm *.tr
If you build the new script and run the simulation setting ``nCsma`` to 100,
::
.. sourcecode:: bash
./waf --run "scratch/mysecond --nCsma=100"
$ ./waf --run "scratch/mysecond --nCsma=100"
you will see the following output:
::
.. sourcecode:: text
Waf: Entering directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build'
Waf: Leaving directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build'
@@ -628,7 +629,7 @@ Note that the echo server is now located at 10.1.2.101 which corresponds to
having 100 "extra" CSMA nodes with the echo server on the last one. If you
list the pcap files in the top level directory you will see,
::
.. sourcecode:: text
second-0-0.pcap second-100-0.pcap second-101-0.pcap
@@ -643,15 +644,15 @@ To illustrate the difference between promiscuous and non-promiscuous traces, we
also requested a non-promiscuous trace for the next-to-last node. Go ahead and
take a look at the ``tcpdump`` for ``second-100-0.pcap``.
::
.. sourcecode:: bash
tcpdump -nn -tt -r second-100-0.pcap
$ tcpdump -nn -tt -r second-100-0.pcap
You can now see that node 100 is really a bystander in the echo exchange. The
only packets that it receives are the ARP requests which are broadcast to the
entire CSMA network.
::
.. sourcecode:: text
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
@@ -659,13 +660,13 @@ entire CSMA network.
Now take a look at the ``tcpdump`` for ``second-101-0.pcap``.
::
.. sourcecode:: bash
tcpdump -nn -tt -r second-101-0.pcap
$ tcpdump -nn -tt -r second-101-0.pcap
You can now see that node 101 is really the participant in the echo exchange.
::
.. sourcecode:: text
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
@@ -1180,16 +1181,16 @@ script into the scratch directory and use Waf to build just as you did with
the ``second.cc`` example. If you are in the top-level directory of the
repository you would type,
::
.. sourcecode:: bash
cp examples/third.cc scratch/mythird.cc
./waf
./waf --run scratch/mythird
$ cp examples/third.cc scratch/mythird.cc
$ ./waf
$ ./waf --run scratch/mythird
Again, since we have set up the UDP echo applications just as we did in the
``second.cc`` script, you will see similar output.
::
.. sourcecode:: text
Waf: Entering directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build'
Waf: Leaving directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build'
@@ -1209,7 +1210,7 @@ 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 from this simulation, two from node zero and two from node one:
::
.. sourcecode:: text
third-0-0.pcap third-0-1.pcap third-1-0.pcap third-1-1.pcap
@@ -1224,13 +1225,13 @@ the code?
Since the echo client is on the Wifi network, let's start there. Let's take
a look at the promiscuous (monitor mode) trace we captured on that network.
::
.. sourcecode:: bash
tcpdump -nn -tt -r third-0-1.pcap
$ tcpdump -nn -tt -r third-0-1.pcap
You should see some wifi-looking contents you haven't seen here before:
::
.. sourcecode:: text
reading from file third-0-1.pcap, link-type IEEE802_11 (802.11)
0.000025 Beacon (ns-3-ssid) [6.0* 9.0 12.0 18.0 24.0 36.0 48.0 54.0 Mbit] IBSS
@@ -1258,13 +1259,13 @@ trace dump.
Now, look at the pcap file of the right side of the point-to-point link,
::
.. sourcecode:: bash
tcpdump -nn -tt -r third-0-0.pcap
$ tcpdump -nn -tt -r third-0-0.pcap
Again, you should see some familiar looking contents:
::
.. sourcecode:: text
reading from file third-0-0.pcap, link-type PPP (PPP)
2.002160 IP 10.1.3.3.49153 > 10.1.2.4.9: UDP, length 1024
@@ -1275,13 +1276,13 @@ again across the point-to-point link.
Now, look at the pcap file of the right side of the point-to-point link,
::
.. sourcecode:: bash
tcpdump -nn -tt -r third-1-0.pcap
$ tcpdump -nn -tt -r third-1-0.pcap
Again, you should see some familiar looking contents:
::
.. sourcecode:: text
reading from file third-1-0.pcap, link-type PPP (PPP)
2.005846 IP 10.1.3.3.49153 > 10.1.2.4.9: UDP, length 1024
@@ -1294,13 +1295,13 @@ as you might expect.
The echo server is on the CSMA network, let's look at the promiscuous trace
there:
::
.. sourcecode:: bash
tcpdump -nn -tt -r third-1-1.pcap
$ tcpdump -nn -tt -r third-1-1.pcap
You should see some familiar looking contents:
::
.. sourcecode:: text
reading from file third-1-1.pcap, link-type EN10MB (Ethernet)
2.005846 ARP, Request who-has 10.1.2.4 (ff:ff:ff:ff:ff:ff) tell 10.1.2.1, length 50
@@ -1382,7 +1383,7 @@ trace sink, which will in turn print out the new position.
If you now run the simulation, you will see the course changes displayed as
they happen.
::
.. sourcecode:: text
Build finished successfully (00:00:01)
/NodeList/7/$ns3::MobilityModel/CourseChange x = 10, y = 0

34
doc/tutorial/source/conceptual-overview.rst
View File

@@ -1,5 +1,5 @@
.. include:: replace.txt
.. highlight:: cpp
Conceptual Overview
-------------------
@@ -153,7 +153,7 @@ of |ns3| in a directory called ``repos`` under your home
directory. Change into that release directory, and you should find a
directory structure something like the following:
::
.. sourcecode:: bash
AUTHORS examples scratch utils waf.bat*
bindings LICENSE src utils.py waf-tools
@@ -250,16 +250,16 @@ load all of the public header files.
Since you are, of course, following this tutorial religiously, you will
already have done a
::
.. sourcecode:: bash
./waf -d debug --enable-examples --enable-tests configure
$ ./waf -d debug --enable-examples --enable-tests configure
in order to configure the project to perform debug builds that include
examples and tests. You will also have done a
::
.. sourcecode:: bash
./waf
$ ./waf
to build the project. So now if you look in the directory
``../../build/debug/ns3`` you will find the four module include files shown
@@ -735,21 +735,21 @@ to drop your script into the scratch directory and it will automatically be
built if you run Waf. Let's try it. Copy ``examples/tutorial/first.cc`` into
the ``scratch`` directory after changing back into the top level directory.
::
.. sourcecode:: bash
cd ../..
cp examples/tutorial/first.cc scratch/myfirst.cc
$ cd ../..
$ cp examples/tutorial/first.cc scratch/myfirst.cc
Now build your first example script using waf:
::
.. sourcecode:: bash
./waf
$ ./waf
You should see messages reporting that your ``myfirst`` example was built
successfully.
::
.. sourcecode:: bash
Waf: Entering directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build'
[614/708] cxx: scratch/myfirst.cc -> build/debug/scratch/myfirst_3.o
@@ -760,13 +760,13 @@ successfully.
You can now run the example (note that if you build your program in the scratch
directory you must run it out of the scratch directory):
::
.. sourcecode:: bash
./waf --run scratch/myfirst
$ ./waf --run scratch/myfirst
You should see some output:
::
.. sourcecode:: bash
Waf: Entering directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build'
Waf: Leaving directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build'
@@ -794,14 +794,14 @@ summary page for our |ns3| development tree.
At the top of the page, you will see a number of links,
::
.. sourcecode:: text
summary | shortlog | changelog | graph | tags | files
Go ahead and select the ``files`` link. This is what the top-level of
most of our *repositories* will look:
::
.. sourcecode:: text
drwxr-xr-x [up]
drwxr-xr-x bindings python files

76
doc/tutorial/source/getting-started.rst
View File

@@ -1,5 +1,5 @@
.. include:: replace.txt
.. include:: replace.txt
.. highlight:: bash
Getting Started
---------------
@@ -89,11 +89,11 @@ get a copy of a release by typing the following into your Linux shell
::
cd
mkdir workspace
cd workspace
wget http://www.nsnam.org/releases/ns-allinone-3.17.tar.bz2
tar xjf ns-allinone-3.17.tar.bz2
$ cd
$ mkdir workspace
$ cd workspace
$ wget http://www.nsnam.org/releases/ns-allinone-3.17.tar.bz2
$ tar xjf ns-allinone-3.17.tar.bz2
If you change into the directory ``ns-allinone-3.17`` you should see a
number of files:
@@ -123,10 +123,10 @@ following into your Linux shell (assuming you have installed Mercurial):
::
cd
mkdir workspace
cd workspace
hg clone http://code.nsnam.org/bake
$ cd
$ mkdir workspace
$ cd workspace
$ hg clone http://code.nsnam.org/bake
As the hg (Mercurial) command executes, you should see something like the
following displayed,
@@ -191,9 +191,9 @@ to put bake into your path, such as follows (Linux bash shell example):
::
export BAKE_HOME=`pwd`/bake
export PATH=$PATH:$BAKE_HOME
export PYTHONPATH=$PYTHONPATH:$BAKE_HOME
$ export BAKE_HOME=`pwd`/bake
$ export PATH=$PATH:$BAKE_HOME
$ export PYTHONPATH=$PYTHONPATH:$BAKE_HOME
However, setting environment variables is not strictly necessary to
complete this tutorial, so we'll call bake directly by specifying the path
@@ -203,14 +203,14 @@ Step into the workspace directory and type the following into your shell:
::
./bake.py configure -e ns-3-dev
$ ./bake.py configure -e ns-3-dev
Next, we'l ask bake to check whether we have enough tools to download
various components. Type:
::
./bake.py check
$ ./bake.py check
You should see something like the following,
@@ -232,7 +232,9 @@ You should see something like the following,
> patch tool - OK
> autoreconf tool - OK
> Path searched for tools: /usr/lib64/qt-3.3/bin /usr/lib64/ccache /usr/local/bin /bin /usr/bin /usr/local/sbin /usr/sbin /sbin /home/tomh/bin bin
> Path searched for tools: /usr/lib64/qt-3.3/bin /usr/lib64/ccache
/usr/local/bin /bin /usr/bin /usr/local/sbin /usr/sbin /sbin
/home/tomh/bin bin
In particular, download tools such as Mercurial, CVS, GIT, and Bazaar
are our principal concerns at this point, since they allow us to fetch
@@ -286,7 +288,7 @@ Type the following:
::
./build.py --enable-examples --enable-tests
$ ./build.py --enable-examples --enable-tests
Because we are working with examples and tests in this tutorial, and
because they are not built by default in |ns3|, the arguments for
@@ -323,7 +325,7 @@ following magic words:
brite click openflow
visualizer
Leaving directory `./ns-3.17`
Leaving directory `./ns-3.17'
Regarding the portion about modules not built:
@@ -347,7 +349,7 @@ may continue to use it to build |ns3|. Type
::
./bake.py build
$ ./bake.py build
and you should see something like:
@@ -364,7 +366,7 @@ command tells you; it may give a hint as to a missing dependency:
::
./bake.py show
$ ./bake.py show
This will list out the various dependencies of the packages you are
trying to build.
@@ -392,8 +394,8 @@ following commands,
::
./waf clean
./waf -d optimized --enable-examples --enable-tests configure
$ ./waf clean
$ ./waf -d optimized --enable-examples --enable-tests configure
This runs Waf out of the local directory (which is provided as a convenience
for you). The first command to clean out the previous build is not
@@ -476,15 +478,15 @@ Now go ahead and switch back to the debug build that includes the examples and t
::
./waf clean
./waf -d debug --enable-examples --enable-tests configure
$ ./waf clean
$ ./waf -d debug --enable-examples --enable-tests configure
The build system is now configured and you can build the debug versions of
the |ns3| programs by simply typing
::
./waf
$ ./waf
Okay, sorry, I made you build the |ns3| part of the system twice,
but now you know how to change the configuration and build optimized code.
@@ -498,7 +500,7 @@ you could reconfigure using the following command that also includes the example
::
./waf configure -d debug --enable-sudo --enable-examples --enable-tests
$ ./waf configure -d debug --enable-sudo --enable-examples --enable-tests
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
@@ -506,7 +508,7 @@ available in waf. To explore these options, type:
::
./waf --help
$ ./waf --help
We'll use some of the testing-related commands in the next section.
@@ -517,7 +519,7 @@ the ``-o`` option to configure; e.g.
::
./waf configure -d debug -o build/debug --enable-examples --enable-tests
$ ./waf configure -d debug -o build/debug --enable-examples --enable-tests
This allows users to work with multiple builds rather than always
overwriting the last build.
@@ -528,16 +530,16 @@ Say one wants to use Clang C++ compiler, command ``clang++``; it's done by
::
CXX="clang++" ./waf configure
./waf build
$ CXX="clang++" ./waf configure
$ ./waf build
One can also set up waf to do distributed compilation with ``distcc`` in
a similar way:
::
CXX="distcc g++" ./waf configure
./waf build
$ CXX="distcc g++" ./waf configure
$ ./waf build
More info on distcc and distributed compilation can be found on it's
`project page
@@ -552,7 +554,7 @@ You can run the unit tests of the |ns3| distribution by running the
::
./test.py -c core
$ ./test.py -c core
These tests are run in parallel by waf. You should eventually
see a report saying that,
@@ -617,7 +619,7 @@ ubiquitous hello world program by typing the following:
::
./waf --run hello-simulator
$ ./waf --run hello-simulator
Waf first checks to make sure that the program is built correctly and
executes a build if required. Waf then executes the program, which
@@ -644,7 +646,7 @@ type the following,
::
./waf configure -d debug --enable-examples --enable-tests
$ ./waf configure -d debug --enable-examples --enable-tests
to tell ``waf`` to build the debug versions of the |ns3|
programs that includes the examples and tests. You must still build
@@ -652,7 +654,7 @@ the actual debug version of the code by typing,
::
./waf
$ ./waf
Now, if you run the ``hello-simulator`` program, you should see the
expected output.

80
doc/tutorial/source/tracing.rst
View File

@@ -1,5 +1,7 @@
.. include:: replace.txt
.. highlight:: cpp
.. role:: raw-role(raw)
:format: html latex
Tracing
-------
@@ -426,14 +428,14 @@ called with the parameters provided by the source.
If you now build and run this example,
::
.. sourcecode:: bash
./waf --run fourth
$ ./waf --run fourth
you will see the output from the ``IntTrace`` function execute as soon as the
trace source is hit:
::
.. sourcecode:: bash
Traced 0 to 1234
@@ -679,9 +681,9 @@ The easiest way to do this is to grep around in the |ns3| codebase for someone
who has already figured it out, You should always try to copy someone else's
working code before you start to write your own. Try something like:
::
.. sourcecode:: bash
find . -name '*.cc' | xargs grep CourseChange | grep Connect
$ find . -name '*.cc' | xargs grep CourseChange | grep Connect
and you may find your answer along with working code. For example, in this
case, ``./ns-3-dev/examples/wireless/mixed-wireless.cc`` has something
@@ -732,7 +734,7 @@ connect.
You are looking at the same information for the RandomWalk2dMobilityModel; and
the information you want is now right there in front of you in the Doxygen:
::
.. sourcecode:: bash
This object is accessible through the following paths with Config::Set and Config::Connect:
@@ -756,7 +758,7 @@ going to be looking for is found in the base class as we have seen.
Look further down in the ``GetTypeId`` doxygen. You will find,
::
.. sourcecode:: bash
No TraceSources defined for this type.
TraceSources defined in parent class ns3::MobilityModel:
@@ -788,9 +790,9 @@ The easiest way to do this is to grep around in the |ns3| codebase for someone
who has already figured it out, You should always try to copy someone else's
working code. Try something like:
::
.. sourcecode:: bash
find . -name '*.cc' | xargs grep CourseChange | grep Connect
$ find . -name '*.cc' | xargs grep CourseChange | grep Connect
and you may find your answer along with working code. For example, in this
case, ``./ns-3-dev/examples/wireless/mixed-wireless.cc`` has something
@@ -812,7 +814,7 @@ there is a callback function there which you can use. Sure enough, there is:
...
}
Take my Word for It
Take My Word for It
~~~~~~~~~~~~~~~~~~~
If there are no examples to work from, this can be, well, challenging to
@@ -899,9 +901,9 @@ We are probably going to be interested in some kind of declaration in the
we know this declaration is going to have to be in some kind of header file,
so just grep for it using:
::
.. sourcecode:: bash
find . -name '*.h' | xargs grep TracedCallback
$ find . -name '*.h' | xargs grep TracedCallback
You'll see 124 lines fly by (I piped this through wc to see how bad it was).
Although that may seem like it, that's not really a lot. Just pipe the output
@@ -943,7 +945,7 @@ in your favorite editor to see what is happening.
You will see a comment at the top of the file that should be comforting:
::
.. sourcecode:: text
An ns3::TracedCallback has almost exactly the same API as a normal ns3::Callback but
instead of forwarding calls to a single function (as an ns3::Callback normally does),
@@ -1019,7 +1021,7 @@ If you look down through the file, you will see a lot of probably almost
incomprehensible template code. You will eventually come to some Doxygen for
the Callback template class, though. Fortunately, there is some English:
::
.. sourcecode:: text
This class template implements the Functor Design Pattern.
It is used to declare the type of a Callback:
@@ -1179,7 +1181,7 @@ trace sources" to see what we have to work with. Recall that this is found
in the |ns3| Doxygen in the "C++ Constructs Used by All Modules" Module section. If you scroll
through the list, you will eventually find:
::
.. sourcecode:: bash
ns3::TcpNewReno
CongestionWindow: The TCP connection's congestion window
@@ -1189,9 +1191,9 @@ file ``src/internet/model/tcp-socket-base.cc`` while congestion control
variants are in files such as ``src/internet/model/tcp-newreno.cc``.
If you don't know this a priori, you can use the recursive grep trick:
::
.. sourcecode:: bash
find . -name '*.cc' | xargs grep -i tcp
$ find . -name '*.cc' | xargs grep -i tcp
You will find page after page of instances of tcp pointing you to that file.
@@ -1247,9 +1249,9 @@ modify, rather than starting from scratch. So the first order of business now
is to find some code that already hooks the "CongestionWindow" trace source
and see if we can modify it. As usual, grep is your friend:
::
.. sourcecode:: bash
find . -name '*.cc' | xargs grep CongestionWindow
$ find . -name '*.cc' | xargs grep CongestionWindow
This will point out a couple of promising candidates:
``examples/tcp/tcp-large-transfer.cc`` and
@@ -1954,10 +1956,10 @@ Since we have provided the file ``fifth.cc`` for you, if you have built
your distribution (in debug mode since it uses NS_LOG -- recall that optimized
builds optimize out NS_LOGs) it will be waiting for you to run.
::
.. sourcecode:: bash
./waf --run fifth
Waf: Entering directory `/home/craigdo/repos/ns-3-allinone-dev/ns-3-dev/build
$ ./waf --run fifth
Waf: Entering directory `/home/craigdo/repos/ns-3-allinone-dev/ns-3-dev/build'
Waf: Leaving directory `/home/craigdo/repos/ns-3-allinone-dev/ns-3-dev/build'
'build' finished successfully (0.684s)
1.20919 1072
@@ -1976,9 +1978,9 @@ information along with those RxDrop messages. We will remedy that soon, but I'm
sure you can't wait to see the results of all of this work. Let's redirect that
output to a file called ``cwnd.dat``:
::
.. sourcecode:: bash
./waf --run fifth > cwnd.dat 2>&1
$ ./waf --run fifth > cwnd.dat 2>&1
Now edit up "cwnd.dat" in your favorite editor and remove the waf build status
and drop lines, leaving only the traced data (you could also comment out the
@@ -1988,8 +1990,9 @@ script to get rid of the drop prints just as easily.
You can now run gnuplot (if you have it installed) and tell it to generate some
pretty pictures:
::
.. sourcecode:: bash
$ gnuplot
gnuplot> set terminal png size 640,480
gnuplot> set output "cwnd.png"
gnuplot> plot "cwnd.dat" using 1:2 title 'Congestion Window' with linespoints
@@ -2187,21 +2190,21 @@ mean that "something" is an |ns3| Object on which you can hang |ns3|
Now, back to the example. If you now build and run this example,
::
.. sourcecode:: bash
./waf --run sixth
$ ./waf --run sixth
you will see the same messages appear as when you ran "fifth", but two new
files will appear in the top-level directory of your |ns3| distribution.
::
.. sourcecode:: bash
sixth.cwnd sixth.pcap
Since "sixth.cwnd" is an ASCII text file, you can view it with ``cat``
or your favorite file viewer.
::
.. sourcecode:: bash
1.20919 536 1072
1.21511 1072 1608
@@ -2215,7 +2218,7 @@ There are no extraneous prints in the file, no parsing or editing is required.
Since "sixth.pcap" is a pcap file, you can fiew it with ``tcpdump``.
::
.. sourcecode:: bash
reading from file ../../sixth.pcap, link-type PPP (PPP)
1.251507 IP 10.1.1.1.49153 > 10.1.1.2.8080: . 17689:18225(536) ack 1 win 65535
@@ -2305,14 +2308,13 @@ There are subtleties that prevent all four classes from behaving identically,
but we do strive to make them all work as similarly as possible; and whenever
possible there are analogs for all methods in all classes.
::
| pcap | ascii |
-----------------+------+-------|
Device Helper | | |
-----------------+------+-------|
Protocol Helper | | |
-----------------+------+-------|
+-----------------+----------------------+----------------------+
| \ | pcap | ascii |
+=================+======================+======================+
| Device Helper | :raw-role:`&#x2713;` | :raw-role:`&#x2713;` |
+-----------------+----------------------+----------------------+
| Protocol Helper | :raw-role:`&#x2713;` | :raw-role:`&#x2713;` |
+-----------------+----------------------+----------------------+
We use an approach called a ``mixin`` to add tracing functionality to our
helper classes. A ``mixin`` is a class that provides functionality to that

185
doc/tutorial/source/tweaking.rst
View File

@@ -1,4 +1,5 @@
.. include:: replace.txt
.. highlight:: cpp
Tweaking
@@ -80,16 +81,16 @@ Let's use the NS_LOG environment variable to turn on some more logging, but
first, just to get our bearings, go ahead and run the last script just as you
did previously,
::
.. sourcecode:: bash
./waf --run scratch/myfirst
$ ./waf --run scratch/myfirst
You should see the now familiar output of the first |ns3| example
program
::
.. sourcecode:: bash
Waf: Entering directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build'
$ Waf: Entering directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build'
Waf: Leaving directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build'
'build' finished successfully (0.413s)
Sent 1024 bytes to 10.1.1.2
@@ -121,13 +122,13 @@ all lower levels. In this case, we have enabled ``NS_LOG_INFO``,
increase the logging level and get more information without changing the
script and recompiling by setting the NS_LOG environment variable like this:
::
.. sourcecode:: bash
export NS_LOG=UdpEchoClientApplication=level_all
$ export NS_LOG=UdpEchoClientApplication=level_all
This sets the shell environment variable ``NS_LOG`` to the string,
::
.. sourcecode:: bash
UdpEchoClientApplication=level_all
@@ -137,9 +138,9 @@ we are going to turn on all of the debugging levels for the application. If
you run the script with NS_LOG set this way, the |ns3| logging
system will pick up the change and you should see the following output:
::
.. sourcecode:: bash
Waf: Entering directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build
Waf: Entering directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build'
Waf: Leaving directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build'
'build' finished successfully (0.404s)
UdpEchoClientApplication:UdpEchoClient()
@@ -183,9 +184,9 @@ wonder where the string "``Received 1024 bytes from 10.1.1.2``" comes
from. You can resolve this by OR'ing the ``prefix_func`` level into the
``NS_LOG`` environment variable. Try doing the following,
::
.. sourcecode:: bash
export 'NS_LOG=UdpEchoClientApplication=level_all|prefix_func'
$ export 'NS_LOG=UdpEchoClientApplication=level_all|prefix_func'
Note that the quotes are required since the vertical bar we use to indicate an
OR operation is also a Unix pipe connector.
@@ -194,7 +195,7 @@ Now, if you run the script you will see that the logging system makes sure
that every message from the given log component is prefixed with the component
name.
::
.. sourcecode:: bash
Waf: Entering directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build'
Waf: Leaving directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build'
@@ -219,9 +220,9 @@ remaining message must be coming from the UDP echo server application. We
can enable that component by entering a colon separated list of components in
the NS_LOG environment variable.
::
.. sourcecode:: bash
export 'NS_LOG=UdpEchoClientApplication=level_all|prefix_func:
$ export 'NS_LOG=UdpEchoClientApplication=level_all|prefix_func:
UdpEchoServerApplication=level_all|prefix_func'
Warning: You will need to remove the newline after the ``:`` in the
@@ -231,7 +232,7 @@ Now, if you run the script you will see all of the log messages from both the
echo client and server applications. You may see that this can be very useful
in debugging problems.
::
.. sourcecode:: bash
Waf: Entering directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build'
Waf: Leaving directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build'
@@ -258,15 +259,15 @@ in debugging problems.
It is also sometimes useful to be able to see the simulation time at which a
log message is generated. You can do this by ORing in the prefix_time bit.
::
.. sourcecode:: bash
export 'NS_LOG=UdpEchoClientApplication=level_all|prefix_func|prefix_time:
$ export 'NS_LOG=UdpEchoClientApplication=level_all|prefix_func|prefix_time:
UdpEchoServerApplication=level_all|prefix_func|prefix_time'
Again, you will have to remove the newline above. If you run the script now,
you should see the following output:
::
.. sourcecode:: bash
Waf: Entering directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build'
Waf: Leaving directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build'
@@ -314,9 +315,9 @@ are not seeing as well. You can very easily follow the entire process by
turning on all of the logging components in the system. Try setting the
``NS_LOG`` variable to the following,
::
.. sourcecode:: bash
export 'NS_LOG=*=level_all|prefix_func|prefix_time'
$ export 'NS_LOG=*=level_all|prefix_func|prefix_time'
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
@@ -324,9 +325,9 @@ 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,
::
.. sourcecode:: bash
./waf --run scratch/myfirst > log.out 2>&1
$ ./waf --run scratch/myfirst > log.out 2>&1
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
@@ -374,16 +375,16 @@ right before the lines,
Now build the script using waf and clear the ``NS_LOG`` variable to turn
off the torrent of logging we previously enabled:
::
.. sourcecode:: bash
./waf
export NS_LOG=
$ ./waf
$ export NS_LOG=
Now, if you run the script,
::
.. sourcecode:: bash
./waf --run scratch/myfirst
$ ./waf --run scratch/myfirst
you will ``not`` see your new message since its associated logging
component (``FirstScriptExample``) has not been enabled. In order to see your
@@ -391,14 +392,14 @@ message you will have to enable the ``FirstScriptExample`` logging component
with a level greater than or equal to ``NS_LOG_INFO``. If you just want to
see this particular level of logging, you can enable it by,
::
.. sourcecode:: bash
export NS_LOG=FirstScriptExample=info
$ export NS_LOG=FirstScriptExample=info
If you now run the script you will see your new "Creating Topology" log
message,
::
.. sourcecode:: bash
Waf: Entering directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build'
Waf: Leaving directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build'
@@ -441,16 +442,16 @@ ahead and add that two lines of code to the ``scratch/myfirst.cc`` script at
the start of ``main``. Go ahead and build the script and run it, but ask
the script for help in the following way,
::
.. sourcecode:: bash
./waf --run "scratch/myfirst --PrintHelp"
$ ./waf --run "scratch/myfirst --PrintHelp"
This will ask Waf to run the ``scratch/myfirst`` script and pass the command
line argument ``--PrintHelp`` to the script. The quotes are required to
sort out which program gets which argument. The command line parser will
now see the ``--PrintHelp`` argument and respond with,
::
.. sourcecode:: bash
Waf: Entering directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build'
Waf: Leaving directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build'
@@ -481,14 +482,14 @@ listing says that we should provide a ``TypeId``. This corresponds to the
class name of the class to which the ``Attributes`` belong. In this case it
will be ``ns3::PointToPointNetDevice``. Let's go ahead and type in,
::
.. sourcecode:: bash
./waf --run "scratch/myfirst --PrintAttributes=ns3::PointToPointNetDevice"
$ ./waf --run "scratch/myfirst --PrintAttributes=ns3::PointToPointNetDevice"
The system will print out all of the ``Attributes`` of this kind of net device.
Among the ``Attributes`` you will see listed is,
::
.. sourcecode:: bash
--ns3::PointToPointNetDevice::DataRate=[32768bps]:
The default data rate for point to point links
@@ -521,13 +522,13 @@ Go ahead and build the new script with Waf (``./waf``) and let's go back
and enable some logging from the UDP echo server application and turn on the
time prefix.
::
.. sourcecode:: bash
export 'NS_LOG=UdpEchoServerApplication=level_all|prefix_time'
$ export 'NS_LOG=UdpEchoServerApplication=level_all|prefix_time'
If you run the script, you should now see the following output,
::
.. sourcecode:: bash
Waf: Entering directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build'
Waf: Leaving directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build'
@@ -545,7 +546,7 @@ If you run the script, you should now see the following output,
Recall that the last time we looked at the simulation time at which the packet
was received by the echo server, it was at 2.00369 seconds.
::
.. sourcecode:: bash
2.00369s UdpEchoServerApplication:HandleRead(): Received 1024 bytes from 10.1.1.1
@@ -557,9 +558,9 @@ If we were to provide a new ``DataRate`` using the command line, we could
speed our simulation up again. We do this in the following way, according to
the formula implied by the help item:
::
.. sourcecode:: bash
./waf --run "scratch/myfirst --ns3::PointToPointNetDevice::DataRate=5Mbps"
$ ./waf --run "scratch/myfirst --ns3::PointToPointNetDevice::DataRate=5Mbps"
This will set the default value of the ``DataRate`` ``Attribute`` back to
five megabits per second. Are you surprised by the result? It turns out that
@@ -568,30 +569,30 @@ the speed-of-light delay of the channel as well. We can ask the command line
system to print out the ``Attributes`` of the channel just like we did for
the net device:
::
.. sourcecode:: bash
./waf --run "scratch/myfirst --PrintAttributes=ns3::PointToPointChannel"
$ ./waf --run "scratch/myfirst --PrintAttributes=ns3::PointToPointChannel"
We discover the ``Delay`` ``Attribute`` of the channel is set in the following
way:
::
.. sourcecode:: bash
--ns3::PointToPointChannel::Delay=[0ns]:
Transmission delay through the channel
We can then set both of these default values through the command line system,
::
.. sourcecode:: bash
./waf --run "scratch/myfirst
$ ./waf --run "scratch/myfirst
--ns3::PointToPointNetDevice::DataRate=5Mbps
--ns3::PointToPointChannel::Delay=2ms"
in which case we recover the timing we had when we explicitly set the
``DataRate`` and ``Delay`` in the script:
::
.. sourcecode:: bash
Waf: Entering directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build'
Waf: Leaving directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build'
@@ -620,9 +621,9 @@ 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,
::
.. sourcecode:: bash
./waf --run "scratch/myfirst
$ ./waf --run "scratch/myfirst
--ns3::PointToPointNetDevice::DataRate=5Mbps
--ns3::PointToPointChannel::Delay=2ms
--ns3::UdpEchoClient::MaxPackets=2"
@@ -666,11 +667,11 @@ should see your new ``User Argument`` listed in the help display.
Try,
::
.. sourcecode:: bash
./waf --run "scratch/myfirst --PrintHelp"
$ ./waf --run "scratch/myfirst --PrintHelp"
::
.. sourcecode:: bash
Waf: Entering directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build'
Waf: Leaving directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build'
@@ -687,13 +688,13 @@ Try,
If you want to specify the number of packets to echo, you can now do so by
setting the ``--nPackets`` argument in the command line,
::
.. sourcecode:: bash
./waf --run "scratch/myfirst --nPackets=2"
$ ./waf --run "scratch/myfirst --nPackets=2"
You should now see
::
.. sourcecode:: bash
Waf: Entering directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build'
Waf: Leaving directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build'
@@ -821,9 +822,9 @@ the popular trace points that log "+", "-", "d", and "r" events.
You can now build the script and run it from the command line:
::
.. sourcecode:: bash
./waf --run scratch/myfirst
$ ./waf --run scratch/myfirst
Just as you have seen many times before, you will see some messages from Waf and then
"'build' finished successfully" with some number of messages from
@@ -856,31 +857,32 @@ space after it). This character will have the following meaning:
* ``r``: A packet was received by the net device.
Let's take a more detailed view of the first line in the trace file. I'll
break it down into sections (indented for clarity) with a two digit reference
break it down into sections (indented for clarity) with a reference
number on the left side:
::
.. sourcecode:: text
:linenos:
00 +
01 2
02 /NodeList/0/DeviceList/0/$ns3::PointToPointNetDevice/TxQueue/Enqueue
03 ns3::PppHeader (
04 Point-to-Point Protocol: IP (0x0021))
05 ns3::Ipv4Header (
06 tos 0x0 ttl 64 id 0 protocol 17 offset 0 flags [none]
07 length: 1052 10.1.1.1 > 10.1.1.2)
08 ns3::UdpHeader (
09 length: 1032 49153 > 9)
10 Payload (size=1024)
+
2
/NodeList/0/DeviceList/0/$ns3::PointToPointNetDevice/TxQueue/Enqueue
ns3::PppHeader (
Point-to-Point Protocol: IP (0x0021))
ns3::Ipv4Header (
tos 0x0 ttl 64 id 0 protocol 17 offset 0 flags [none]
length: 1052 10.1.1.1 > 10.1.1.2)
ns3::UdpHeader (
length: 1032 49153 > 9)
Payload (size=1024)
The first line of this expanded trace event (reference number 00) is the
The first section of this expanded trace event (reference number 0) is the
operation. We have a ``+`` character, so this corresponds to an
*enqueue* operation on the transmit queue. The second line (reference 01)
*enqueue* operation on the transmit queue. The second section (reference 1)
is the simulation time expressed in seconds. You may recall that we asked the
``UdpEchoClientApplication`` to start sending packets at two seconds. Here
we see confirmation that this is, indeed, happening.
The next line of the example trace (reference 02) tell us which trace source
The next section of the example trace (reference 2) tell us which trace source
originated this event (expressed in the tracing namespace). You can think
of the tracing namespace somewhat like you would a filesystem namespace. The
root of the namespace is the ``NodeList``. This corresponds to a container
@@ -899,11 +901,11 @@ Recall that the operation ``+`` found at reference 00 meant that an enqueue
operation happened on the transmit queue of the device. This is reflected in
the final segments of the "trace path" which are ``TxQueue/Enqueue``.
The remaining lines in the trace should be fairly intuitive. References 03-04
The remaining sections in the trace should be fairly intuitive. References 3-4
indicate that the packet is encapsulated in the point-to-point protocol.
References 05-07 show that the packet has an IP version four header and has
References 5-7 show that the packet has an IP version four header and has
originated from IP address 10.1.1.1 and is destined for 10.1.1.2. References
08-09 show that this packet has a UDP header and, finally, reference 10 shows
8-9 show that this packet has a UDP header and, finally, reference 10 shows
that the payload is the expected 1024 bytes.
The next line in the trace file shows the same packet being dequeued from the
@@ -912,17 +914,18 @@ transmit queue on the same node.
The Third line in the trace file shows the packet being received by the net
device on the node with the echo server. I have reproduced that event below.
::
.. sourcecode:: text
:linenos:
00 r
01 2.25732
02 /NodeList/1/DeviceList/0/$ns3::PointToPointNetDevice/MacRx
03 ns3::Ipv4Header (
04 tos 0x0 ttl 64 id 0 protocol 17 offset 0 flags [none]
05 length: 1052 10.1.1.1 > 10.1.1.2)
06 ns3::UdpHeader (
07 length: 1032 49153 > 9)
08 Payload (size=1024)
r
2.25732
/NodeList/1/DeviceList/0/$ns3::PointToPointNetDevice/MacRx
ns3::Ipv4Header (
tos 0x0 ttl 64 id 0 protocol 17 offset 0 flags [none]
length: 1052 10.1.1.1 > 10.1.1.2)
ns3::UdpHeader (
length: 1032 49153 > 9)
Payload (size=1024)
Notice that the trace operation is now ``r`` and the simulation time has
increased to 2.25732 seconds. If you have been following the tutorial steps
@@ -968,9 +971,9 @@ node 1-device 0, respectively.
Once you have added the line of code to enable pcap tracing, you can run the
script in the usual way:
::
.. sourcecode:: bash
./waf --run scratch/myfirst
$ ./waf --run scratch/myfirst
If you look at the top level directory of your distribution, you should now
see three log files: ``myfirst.tr`` is the ASCII trace file we have
@@ -982,9 +985,9 @@ Reading output with tcpdump
The easiest thing to do at this point will be to use ``tcpdump`` to look
at the ``pcap`` files.
::
.. sourcecode:: bash
tcpdump -nn -tt -r myfirst-0-0.pcap
$ tcpdump -nn -tt -r myfirst-0-0.pcap
reading from file myfirst-0-0.pcap, link-type PPP (PPP)
2.000000 IP 10.1.1.1.49153 > 10.1.1.2.9: UDP, length 1024
2.514648 IP 10.1.1.2.9 > 10.1.1.1.49153: UDP, length 1024