# HG changeset patch # User Peter D. Barnes, Jr. # Date 1374106176 25200 # Node ID 1a4d84a85badf6d5e3756aa99bf5b8b20bf0c669 # Parent d97de2f9fbe5dbfdbb3df59ffde6f7ffabe05094 Manual and Tutorial syntax coloring diff -r d97de2f9fbe5 -r 1a4d84a85bad doc/manual/source/attributes.rst --- a/doc/manual/source/attributes.rst Wed Jul 17 23:34:17 2013 +0200 +++ b/doc/manual/source/attributes.rst Wed Jul 17 17:09:36 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 @@ -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 diff -r d97de2f9fbe5 -r 1a4d84a85bad doc/manual/source/callbacks.rst --- a/doc/manual/source/callbacks.rst Wed Jul 17 23:34:17 2013 +0200 +++ b/doc/manual/source/callbacks.rst Wed Jul 17 17:09:36 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 one; + static double CbOne (double a, double b) {} + ^ ^ ^ + | | | + | | | + Callback 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 diff -r d97de2f9fbe5 -r 1a4d84a85bad doc/manual/source/enable-modules.rst --- a/doc/manual/source/enable-modules.rst Wed Jul 17 23:34:17 2013 +0200 +++ b/doc/manual/source/enable-modules.rst Wed Jul 17 17:09:36 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) diff -r d97de2f9fbe5 -r 1a4d84a85bad doc/manual/source/enable-tests.rst --- a/doc/manual/source/enable-tests.rst Wed Jul 17 23:34:17 2013 +0200 +++ b/doc/manual/source/enable-tests.rst Wed Jul 17 17:09:36 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) diff -r d97de2f9fbe5 -r 1a4d84a85bad doc/manual/source/events.rst --- a/doc/manual/source/events.rst Wed Jul 17 23:34:17 2013 +0200 +++ b/doc/manual/source/events.rst Wed Jul 17 17:09:36 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 diff -r d97de2f9fbe5 -r 1a4d84a85bad doc/manual/source/gnuplot.rst --- a/doc/manual/source/gnuplot.rst Wed Jul 17 23:34:17 2013 +0200 +++ b/doc/manual/source/gnuplot.rst Wed Jul 17 17:09:36 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 ***************************** diff -r d97de2f9fbe5 -r 1a4d84a85bad doc/manual/source/hash-functions.rst --- a/doc/manual/source/hash-functions.rst Wed Jul 17 23:34:17 2013 +0200 +++ b/doc/manual/source/hash-functions.rst Wed Jul 17 17:09:36 2013 -0700 @@ -1,4 +1,5 @@ .. include:: replace.txt +.. highlight:: cpp Hash Functions ---------------- diff -r d97de2f9fbe5 -r 1a4d84a85bad doc/manual/source/helpers.rst --- a/doc/manual/source/helpers.rst Wed Jul 17 23:34:17 2013 +0200 +++ b/doc/manual/source/helpers.rst Wed Jul 17 17:09:36 2013 -0700 @@ -1,4 +1,5 @@ .. include:: replace.txt +.. highlight:: cpp Helpers ------- diff -r d97de2f9fbe5 -r 1a4d84a85bad doc/manual/source/how-to-write-tests.rst --- a/doc/manual/source/how-to-write-tests.rst Wed Jul 17 23:34:17 2013 +0200 +++ b/doc/manual/source/how-to-write-tests.rst Wed Jul 17 17:09:36 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) diff -r d97de2f9fbe5 -r 1a4d84a85bad doc/manual/source/logging.rst --- a/doc/manual/source/logging.rst Wed Jul 17 23:34:17 2013 +0200 +++ b/doc/manual/source/logging.rst Wed Jul 17 17:09:36 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: diff -r d97de2f9fbe5 -r 1a4d84a85bad doc/manual/source/new-models.rst --- a/doc/manual/source/new-models.rst Wed Jul 17 23:34:17 2013 +0200 +++ b/doc/manual/source/new-models.rst Wed Jul 17 17:09:36 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 diff -r d97de2f9fbe5 -r 1a4d84a85bad doc/manual/source/new-modules.rst --- a/doc/manual/source/new-modules.rst Wed Jul 17 23:34:17 2013 +0200 +++ b/doc/manual/source/new-modules.rst Wed Jul 17 17:09:36 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. diff -r d97de2f9fbe5 -r 1a4d84a85bad doc/manual/source/object-model.rst --- a/doc/manual/source/object-model.rst Wed Jul 17 23:34:17 2013 +0200 +++ b/doc/manual/source/object-model.rst Wed Jul 17 17:09:36 2013 -0700 @@ -1,4 +1,5 @@ .. include:: replace.txt +.. highlight:: cpp .. _Object-model: diff -r d97de2f9fbe5 -r 1a4d84a85bad doc/manual/source/object-names.rst --- a/doc/manual/source/object-names.rst Wed Jul 17 23:34:17 2013 +0200 +++ b/doc/manual/source/object-names.rst Wed Jul 17 17:09:36 2013 -0700 @@ -1,4 +1,5 @@ .. include:: replace.txt +.. highlight:: cpp .. _Object-names: diff -r d97de2f9fbe5 -r 1a4d84a85bad doc/manual/source/organization.rst --- a/doc/manual/source/organization.rst Wed Jul 17 23:34:17 2013 +0200 +++ b/doc/manual/source/organization.rst Wed Jul 17 17:09:36 2013 -0700 @@ -1,4 +1,5 @@ .. include:: replace.txt +.. highlight:: cpp Organization diff -r d97de2f9fbe5 -r 1a4d84a85bad doc/manual/source/python.rst --- a/doc/manual/source/python.rst Wed Jul 17 23:34:17 2013 +0200 +++ b/doc/manual/source/python.rst Wed Jul 17 17:09:36 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 `_ 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 -``_. +If you are a developer and need more information on |ns3|'s Python bindings, please see the `Python Bindings wiki page `_. diff -r d97de2f9fbe5 -r 1a4d84a85bad doc/manual/source/random-variables.rst --- a/doc/manual/source/random-variables.rst Wed Jul 17 23:34:17 2013 +0200 +++ b/doc/manual/source/random-variables.rst Wed Jul 17 17:09:36 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 x = CreateObject (); Ptr y = CreateObject (); @@ -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 diff -r d97de2f9fbe5 -r 1a4d84a85bad doc/manual/source/realtime.rst --- a/doc/manual/source/realtime.rst Wed Jul 17 23:34:17 2013 +0200 +++ b/doc/manual/source/realtime.rst Wed Jul 17 17:09:36 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. diff -r d97de2f9fbe5 -r 1a4d84a85bad doc/manual/source/test-framework.rst --- a/doc/manual/source/test-framework.rst Wed Jul 17 23:34:17 2013 +0200 +++ b/doc/manual/source/test-framework.rst Wed Jul 17 17:09:36 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 pcap-file-object @@ -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 { diff -r d97de2f9fbe5 -r 1a4d84a85bad doc/manual/source/tracing.rst --- a/doc/manual/source/tracing.rst Wed Jul 17 23:34:17 2013 +0200 +++ b/doc/manual/source/tracing.rst Wed Jul 17 17:09:36 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 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 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 diff -r d97de2f9fbe5 -r 1a4d84a85bad doc/manual/source/troubleshoot.rst --- a/doc/manual/source/troubleshoot.rst Wed Jul 17 23:34:17 2013 +0200 +++ b/doc/manual/source/troubleshoot.rst Wed Jul 17 17:09:36 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 -`_::: +`_: - 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 = n2->GetObject (Tcp::iid); Ptr localSocket = socketFactory->CreateSocket (); @@ -77,6 +82,6 @@ Sometimes you may need to use the `valgrind memory checker `_ 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" diff -r d97de2f9fbe5 -r 1a4d84a85bad doc/ns3_html_theme/static/ns3_stylesheet.css --- a/doc/ns3_html_theme/static/ns3_stylesheet.css Wed Jul 17 23:34:17 2013 +0200 +++ b/doc/ns3_html_theme/static/ns3_stylesheet.css Wed Jul 17 17:09:36 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; diff -r d97de2f9fbe5 -r 1a4d84a85bad doc/tutorial/source/building-topologies.rst --- a/doc/tutorial/source/building-topologies.rst Wed Jul 17 23:34:17 2013 +0200 +++ b/doc/tutorial/source/building-topologies.rst Wed Jul 17 17:09:36 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 diff -r d97de2f9fbe5 -r 1a4d84a85bad doc/tutorial/source/conceptual-overview.rst --- a/doc/tutorial/source/conceptual-overview.rst Wed Jul 17 23:34:17 2013 +0200 +++ b/doc/tutorial/source/conceptual-overview.rst Wed Jul 17 17:09:36 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 diff -r d97de2f9fbe5 -r 1a4d84a85bad doc/tutorial/source/getting-started.rst --- a/doc/tutorial/source/getting-started.rst Wed Jul 17 23:34:17 2013 +0200 +++ b/doc/tutorial/source/getting-started.rst Wed Jul 17 17:09:36 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. diff -r d97de2f9fbe5 -r 1a4d84a85bad doc/tutorial/source/tracing.rst --- a/doc/tutorial/source/tracing.rst Wed Jul 17 23:34:17 2013 +0200 +++ b/doc/tutorial/source/tracing.rst Wed Jul 17 17:09:36 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 diff -r d97de2f9fbe5 -r 1a4d84a85bad doc/tutorial/source/tweaking.rst --- a/doc/tutorial/source/tweaking.rst Wed Jul 17 23:34:17 2013 +0200 +++ b/doc/tutorial/source/tweaking.rst Wed Jul 17 17:09:36 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