--- a/doc/manual/source/attributes.rst Thu Jul 18 14:07:56 2013 +0200
+++ b/doc/manual/source/attributes.rst Thu Jul 18 12:04:27 2013 -0700
@@ -1,4 +1,6 @@
.. include:: replace.txt
+.. highlight:: cpp
+
.. _Attributes:
@@ -405,7 +407,9 @@
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 @@
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 @@
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 @@
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 @@
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
+
+ $ sudo apt-get install libgtk2.0-0 libgtk2.0-dev
-To check whether it is configured or not, check the output of the step:::
+To check whether it is configured or not, check the output of the step:
- ./waf configure --enable-examples --enable-tests
+.. sourcecode:: bash
+
+ $ ./waf configure --enable-examples --enable-tests
---- Summary of optional NS-3 features:
Python Bindings : enabled
@@ -873,10 +885,12 @@
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 @@
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
--- a/doc/manual/source/callbacks.rst Thu Jul 18 14:07:56 2013 +0200
+++ b/doc/manual/source/callbacks.rst Thu Jul 18 12:04:27 2013 -0700
@@ -1,4 +1,5 @@
.. include:: replace.txt
+.. highlight:: cpp
Callbacks
---------
@@ -364,11 +365,11 @@
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
--- a/doc/manual/source/enable-modules.rst Thu Jul 18 14:07:56 2013 +0200
+++ b/doc/manual/source/enable-modules.rst Thu Jul 18 12:04:27 2013 -0700
@@ -1,4 +1,5 @@
.. include:: replace.txt
+.. highlight:: bash
Enabling Subsets of |ns3| Modules
---------------------------------
@@ -10,11 +11,15 @@
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 @@
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 @@
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 @@
# 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 @@
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)
--- a/doc/manual/source/enable-tests.rst Thu Jul 18 14:07:56 2013 +0200
+++ b/doc/manual/source/enable-tests.rst Thu Jul 18 12:04:27 2013 -0700
@@ -1,4 +1,6 @@
.. include:: replace.txt
+.. highlight:: bash
+
Enabling/disabling |ns3| Tests and Examples
-------------------------------------------
@@ -26,18 +28,22 @@
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 @@
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 @@
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 @@
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 @@
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)
--- a/doc/manual/source/events.rst Thu Jul 18 14:07:56 2013 +0200
+++ b/doc/manual/source/events.rst Thu Jul 18 12:04:27 2013 -0700
@@ -1,4 +1,6 @@
.. include:: replace.txt
+.. highlight:: cpp
+
.. heading hierarchy:
------------- Chapter
@@ -42,7 +44,7 @@
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 @@
Which will output:
-::
+.. sourcecode:: text
handler called with argument arg0=10 and arg1=5
--- a/doc/manual/source/gnuplot.rst Thu Jul 18 14:07:56 2013 +0200
+++ b/doc/manual/source/gnuplot.rst Thu Jul 18 12:04:27 2013 -0700
@@ -1,5 +1,6 @@
.. include:: replace.txt
-
+.. highlight:: cpp
+
Making Plots using the Gnuplot Class
------------------------------------
@@ -25,39 +26,51 @@
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:
+
+.. sourcecode:: bash
- ./waf shell
- cd build/debug/src/stats/examples
- ./gnuplot-example
+ $ ./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: ::
+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:
+
+.. sourcecode:: bash
- gnuplot plot-2d.plt
- gnuplot plot-2d-with-error-bars.plt
- gnuplot plot-3d.plt
+ $ 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: ::
+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:
+
+.. sourcecode:: bash
- gimp plot-2d.png
- gimp plot-2d-with-error-bars.png
- gimp plot-3d.png
+ $ gimp plot-2d.png
+ $ gimp plot-2d-with-error-bars.png
+ $ gimp plot-3d.png
An Example 2-Dimensional Plot
*****************************
--- a/doc/manual/source/hash-functions.rst Thu Jul 18 14:07:56 2013 +0200
+++ b/doc/manual/source/hash-functions.rst Thu Jul 18 12:04:27 2013 -0700
@@ -1,4 +1,5 @@
.. include:: replace.txt
+.. highlight:: cpp
Hash Functions
----------------
--- a/doc/manual/source/helpers.rst Thu Jul 18 14:07:56 2013 +0200
+++ b/doc/manual/source/helpers.rst Thu Jul 18 12:04:27 2013 -0700
@@ -1,4 +1,5 @@
.. include:: replace.txt
+.. highlight:: cpp
Helpers
-------
--- a/doc/manual/source/how-to-write-tests.rst Thu Jul 18 14:07:56 2013 +0200
+++ b/doc/manual/source/how-to-write-tests.rst Thu Jul 18 12:04:27 2013 -0700
@@ -1,4 +1,5 @@
.. include:: replace.txt
+.. highlight:: cpp
How to write tests
------------------
@@ -46,7 +47,7 @@
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 @@
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)
--- a/doc/manual/source/logging.rst Thu Jul 18 14:07:56 2013 +0200
+++ b/doc/manual/source/logging.rst Thu Jul 18 12:04:27 2013 -0700
@@ -1,4 +1,5 @@
.. include:: replace.txt
+.. highlight:: cpp
.. heading hierarchy:
------------- Chapter
@@ -71,7 +72,7 @@
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 @@
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:
--- a/doc/manual/source/new-models.rst Thu Jul 18 14:07:56 2013 +0200
+++ b/doc/manual/source/new-models.rst Thu Jul 18 12:04:27 2013 -0700
@@ -1,4 +1,5 @@
.. include:: replace.txt
+.. highlight:: cpp
Creating a new ns-3 model
-------------------------
@@ -408,7 +409,7 @@
::
- point-to-point-net-device.h
+ /* point-to-point-net-device.h */
class ErrorModel;
/**
@@ -473,7 +474,7 @@
::
- simple-error-model.cc
+ /* simple-error-model.cc */
// Error model
// We want to add an error model to node 3's NetDevice
--- a/doc/manual/source/new-modules.rst Thu Jul 18 14:07:56 2013 +0200
+++ b/doc/manual/source/new-modules.rst Thu Jul 18 12:04:27 2013 -0700
@@ -1,4 +1,5 @@
.. include:: replace.txt
+.. highlight:: cpp
Adding a New Module to |ns3|
----------------------------
@@ -20,7 +21,9 @@
src/spectrum
A prototypical module has the following directory structure and
-required files: ::
+required files:
+
+.. sourcecode:: text
src/
module-name/
@@ -39,29 +42,39 @@
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
+
+.. sourcecode:: bash
- src/create-module.py
+ $ src/create-module.py
-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: ::
+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:
- ./create-module.py new-module
+.. sourcecode:: bash
+
+ $ ./create-module.py new-module
-Next, cd into ``new-module``; you will find this directory layout: ::
+Next, cd into ``new-module``; you will find this directory layout:
- examples helper model test wscript
+.. 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 @@
*********************************************
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 @@
*******************************************
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 @@
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 @@
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 @@
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 @@
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 @@
("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 @@
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 @@
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 @@
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:
+
+.. sourcecode:: bash
- ./waf configure --enable-examples --enable-tests
- ./waf build
- ./test.py
+ $ ./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.
--- a/doc/manual/source/object-model.rst Thu Jul 18 14:07:56 2013 +0200
+++ b/doc/manual/source/object-model.rst Thu Jul 18 12:04:27 2013 -0700
@@ -1,4 +1,5 @@
.. include:: replace.txt
+.. highlight:: cpp
.. _Object-model:
--- a/doc/manual/source/object-names.rst Thu Jul 18 14:07:56 2013 +0200
+++ b/doc/manual/source/object-names.rst Thu Jul 18 12:04:27 2013 -0700
@@ -1,4 +1,5 @@
.. include:: replace.txt
+.. highlight:: cpp
.. _Object-names:
--- a/doc/manual/source/organization.rst Thu Jul 18 14:07:56 2013 +0200
+++ b/doc/manual/source/organization.rst Thu Jul 18 12:04:27 2013 -0700
@@ -1,4 +1,5 @@
.. include:: replace.txt
+.. highlight:: cpp
Organization
--- a/doc/manual/source/python.rst Thu Jul 18 14:07:56 2013 +0200
+++ b/doc/manual/source/python.rst Thu Jul 18 12:04:27 2013 -0700
@@ -1,4 +1,5 @@
.. include:: replace.txt
+.. highlight:: python
Using Python to Run |ns3|
-------------------------
@@ -74,30 +75,30 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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>`_.
--- a/doc/manual/source/random-variables.rst Thu Jul 18 14:07:56 2013 +0200
+++ b/doc/manual/source/random-variables.rst Thu Jul 18 12:04:27 2013 -0700
@@ -1,4 +1,5 @@
.. include:: replace.txt
+.. highlight:: cpp
Random Variables
----------------
@@ -125,7 +126,7 @@
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 @@
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
+
+ $ ./waf --command-template="%s --RngRun=3" --run program-name
-or, if you are running programs directly outside of waf::
+or, if you are running programs directly outside of waf:
- ./build/optimized/scratch/program-name --RngRun=3
+.. 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 @@
*********************
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 @@
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 @@
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
--- a/doc/manual/source/realtime.rst Thu Jul 18 14:07:56 2013 +0200
+++ b/doc/manual/source/realtime.rst Thu Jul 18 12:04:27 2013 -0700
@@ -1,4 +1,5 @@
.. include:: replace.txt
+.. highlight:: cpp
RealTime
--------
@@ -61,9 +62,11 @@
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.
--- a/doc/manual/source/test-framework.rst Thu Jul 18 14:07:56 2013 +0200
+++ b/doc/manual/source/test-framework.rst Thu Jul 18 12:04:27 2013 -0700
@@ -1,4 +1,5 @@
.. include:: replace.txt
+.. highlight:: bash
Testing framework
-----------------
@@ -27,7 +28,9 @@
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 @@
::
- ./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 @@
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 @@
::
- ./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 @@
::
- ./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 @@
::
- ./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 @@
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 @@
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 @@
::
- ./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 @@
::
- ./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 @@
::
- ./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 @@
::
- ./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 @@
::
- ./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 @@
::
- ./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 @@
::
- ./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 @@
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 @@
::
- ./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 @@
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 @@
::
- ./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 @@
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 @@
::
- ./test.py -r
+ $ ./test.py -r
and test output can be found in the ``testpy-output/`` directory.
@@ -619,11 +631,11 @@
::
- ./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 @@
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 @@
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 @@
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 @@
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 @@
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
{
--- a/doc/manual/source/tracing.rst Thu Jul 18 14:07:56 2013 +0200
+++ b/doc/manual/source/tracing.rst Thu Jul 18 12:04:27 2013 -0700
@@ -1,4 +1,7 @@
.. include:: replace.txt
+.. highlight:: cpp
+.. role:: raw-role(raw)
+ :format: html latex
Tracing
-------
@@ -269,7 +272,7 @@
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 @@
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:`✓` | :raw-role:`✓` |
+ +-----------------+----------------------+----------------------+
+ | Protocol Helper | :raw-role:`✓` | :raw-role:`✓` |
+ +-----------------+----------------------+----------------------+
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 @@
::
- 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
--- a/doc/manual/source/troubleshoot.rst Thu Jul 18 14:07:56 2013 +0200
+++ b/doc/manual/source/troubleshoot.rst Thu Jul 18 12:04:27 2013 -0700
@@ -1,4 +1,5 @@
.. include:: replace.txt
+.. highlight:: bash
Troubleshooting
---------------
@@ -22,18 +23,20 @@
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 @@
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 @@
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"
--- a/doc/ns3_html_theme/static/ns3_stylesheet.css Thu Jul 18 14:07:56 2013 +0200
+++ b/doc/ns3_html_theme/static/ns3_stylesheet.css Thu Jul 18 12:04:27 2013 -0700
@@ -25,6 +25,11 @@
background-image: url('nav_f.png');
}
+/* Sphinx figure captions */
+p.caption {
+ font-weight: bold;
+}
+
/* Doxygen side bar */
#nav-tree {
font-size: 12px;
--- a/doc/tutorial/source/building-topologies.rst Thu Jul 18 14:07:56 2013 +0200
+++ b/doc/tutorial/source/building-topologies.rst Thu Jul 18 12:04:27 2013 -0700
@@ -1,5 +1,5 @@
.. include:: replace.txt
-
+.. highlight:: cpp
Building Topologies
-------------------
@@ -337,10 +337,10 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
``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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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
--- a/doc/tutorial/source/conceptual-overview.rst Thu Jul 18 14:07:56 2013 +0200
+++ b/doc/tutorial/source/conceptual-overview.rst Thu Jul 18 12:04:27 2013 -0700
@@ -1,5 +1,5 @@
.. include:: replace.txt
-
+.. highlight:: cpp
Conceptual Overview
-------------------
@@ -153,7 +153,7 @@
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 @@
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 @@
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 @@
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 @@
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
--- a/doc/tutorial/source/getting-started.rst Thu Jul 18 14:07:56 2013 +0200
+++ b/doc/tutorial/source/getting-started.rst Thu Jul 18 12:04:27 2013 -0700
@@ -1,5 +1,5 @@
- .. include:: replace.txt
-
+.. include:: replace.txt
+.. highlight:: bash
Getting Started
---------------
@@ -89,11 +89,11 @@
::
- 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 @@
::
- 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 @@
::
- 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 @@
::
- ./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 @@
> 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 @@
::
- ./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 @@
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 @@
::
- ./bake.py build
+ $ ./bake.py build
and you should see something like:
@@ -364,7 +366,7 @@
::
- ./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 @@
::
- ./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 @@
::
- ./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 @@
::
- ./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 @@
::
- ./waf --help
+ $ ./waf --help
We'll use some of the testing-related commands in the next section.
@@ -517,7 +519,7 @@
::
- ./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 @@
::
- 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 @@
::
- ./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 @@
::
- ./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 @@
::
- ./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 @@
::
- ./waf
+ $ ./waf
Now, if you run the ``hello-simulator`` program, you should see the
expected output.
--- a/doc/tutorial/source/tracing.rst Thu Jul 18 14:07:56 2013 +0200
+++ b/doc/tutorial/source/tracing.rst Thu Jul 18 12:04:27 2013 -0700
@@ -1,5 +1,7 @@
.. include:: replace.txt
-
+.. highlight:: cpp
+.. role:: raw-role(raw)
+ :format: html latex
Tracing
-------
@@ -426,14 +428,14 @@
If you now build and run this example,
-::
-
- ./waf --run fourth
+.. sourcecode:: bash
+
+ $ ./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 @@
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:
-::
-
- find . -name '*.cc' | xargs grep CourseChange | grep Connect
+.. sourcecode:: bash
+
+ $ 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 @@
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 @@
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 @@
who has already figured it out, You should always try to copy someone else's
working code. Try something like:
-::
-
- find . -name '*.cc' | xargs grep CourseChange | grep Connect
+.. sourcecode:: bash
+
+ $ 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 @@
...
}
-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 know this declaration is going to have to be in some kind of header file,
so just grep for it using:
-::
-
- find . -name '*.h' | xargs grep TracedCallback
+.. sourcecode:: bash
+
+ $ 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 @@
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 @@
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 @@
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 @@
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:
-::
-
- find . -name '*.cc' | xargs grep -i tcp
+.. sourcecode:: bash
+
+ $ 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 @@
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:
-::
-
- find . -name '*.cc' | xargs grep CongestionWindow
+.. sourcecode:: bash
+
+ $ 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 @@
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.
-::
-
- ./waf --run fifth
- Waf: Entering directory `/home/craigdo/repos/ns-3-allinone-dev/ns-3-dev/build
+.. sourcecode:: bash
+
+ $ ./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 @@
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``:
-::
-
- ./waf --run fifth > cwnd.dat 2>&1
+.. sourcecode:: bash
+
+ $ ./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 @@
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 @@
Now, back to the example. If you now build and run this example,
-::
-
- ./waf --run sixth
+.. sourcecode:: bash
+
+ $ ./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 @@
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 @@
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:`✓` | :raw-role:`✓` |
+ +-----------------+----------------------+----------------------+
+ | Protocol Helper | :raw-role:`✓` | :raw-role:`✓` |
+ +-----------------+----------------------+----------------------+
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
--- a/doc/tutorial/source/tweaking.rst Thu Jul 18 14:07:56 2013 +0200
+++ b/doc/tutorial/source/tweaking.rst Thu Jul 18 12:04:27 2013 -0700
@@ -1,4 +1,5 @@
.. include:: replace.txt
+.. highlight:: cpp
Tweaking
@@ -80,16 +81,16 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
* ``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 @@
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 @@
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 @@
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 @@
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