re-enable openflow test suite

Remove template module from doxygen configuration
Add bug references to ns-2 mobility helper
2011-12-23 13:08:14 -08:00 · 2011-12-23 12:28:32 -08:00 · 2011-12-23 12:22:38 -08:00 · 2011-12-23 12:13:54 -08:00 · 2011-12-23 12:00:12 -08:00 · 2011-12-23 11:29:36 -08:00
2511 changed files with 796507 additions and 92136 deletions
@@ -4,8 +4,29 @@
 ~$
 ^build-dir
 ^build
+^testpy-output
 ^doc/html
 ^doc/latex
-^\.lock-wscript
+^doc/ns3-object.txt
+^\.lock-wafbuild
 ^\.waf
 ^doc/introspected-doxygen\.h$
+.*\.py[co]$
+\.pcap$
+\.mob$
+\.routes$
+^doc/manual/build
+^doc/tutorial/build
+^doc/testing/build
+^doc/models/build
+^doc/models/source-temp
+^doc/manual/figures/.*eps
+^doc/manual/figures/.*pdf
+^doc/manual/figures/.*png
+^bindings/python/pybindgen/
+ms_print.*
+massif.*
+\.patch$
+\.diff$
+\.tr$
+\#[^\#/]+\#$
@@ -1,10 +1,62 @@
-56928998e05c9c11f5f3aefe79be8d2843e0db88 release ns-3.0.1
-7ac5a4b0969b255c4824c926c2b37ef450136ce9 release ns-3.0.2
-0dc81e76166c56aaae64da48b673b62155943aad packet-history-working
-38099dd26e9467b8f49f8632f22789858149a6e7 release ns-3.0.3
-5701e60bf01a8ac1308945e69001e0cc07948faf release ns-3.0.4
-08046b6aef37932507696a2f2f427b42d693781e release ns-3.0.5
-267e2ebc28e4e4ae2f579e1cfc29902acade0c34 buffer-working-before-breaking
-606df29888e7573b825fc891a002f0757166b616 release ns-3.0.6
-36472385a1cc7c44d34fb7a5951b930010f4e8d2 release ns-3.0.7
-560a5091e0e6ded47d269e2f2dee780f13950a63 release ns-3.0.8
+56928998e05c9c11f5f3aefe79be8d2843e0db88 ns-3.0.1
+7ac5a4b0969b255c4824c926c2b37ef450136ce9 ns-3.0.2
+38099dd26e9467b8f49f8632f22789858149a6e7 ns-3.0.3
+5701e60bf01a8ac1308945e69001e0cc07948faf ns-3.0.4
+08046b6aef37932507696a2f2f427b42d693781e ns-3.0.5
+606df29888e7573b825fc891a002f0757166b616 ns-3.0.6
+36472385a1cc7c44d34fb7a5951b930010f4e8d2 ns-3.0.7
+560a5091e0e6ded47d269e2f2dee780f13950a63 ns-3.0.8
+4db981a0d9eb135e3e1c07765cff8d66f7a55cca ns-3.0.9
+b5bf2588cde2f1273b1095cc5c83a0c272e55370 ns-3.0.10
+ee5e1da76ecc52337f097cd90ebb50a3d49ec541 ns-3.0.11
+b17f2928291eec5bf5b1c59a4a5fd583f704ac40 ns-3.0.12
+79dba133b5f8a2d6f6f678a22e8519bc155e6a4e ns-3.0.13
+8869a79a391f49d0c787f0558cc9329b4e7ee40e ns-3.1-RC1
+951296e9a277e14113a0d3ba86a9688b222569ae ns-3.1-RC2
+ea16c44eb90db579c83d3434fc8a960be506a7f5 ns-3.1-RC3
+42504fb1f7be7817b8be513cdcd3d9bc8f3660e8 ns-3.1
+5768685f9fdba9fbf2e9561a840f085142c73575 ns-3.1
+dfd634417b8d1896d981b6f44d8f71030611596a ns-3.2-RC1
+319eb29611b18998abbad01548825643a8017bcb ns-3.2-RC2
+d783a951f8f5e64b33bc518f0415f76cae1ca6f3 ns-3.2-RC2-bis
+fa1c7b813873cfa251be7d1b7cea38373fe82fa1 ns-3.2-RC3
+68218c266a844f9fbda34a0ffddb1ae2adebd4b0 ns-3.2-RC4
+2ecac911b3ec40d73ab8301471bea6d9ba5b9885 ns-3.2
+f33cbf6b051c51d92db41b6fa825437958fbf801 ns-3.3-RC1
+0000000000000000000000000000000000000000 ns-3.3-RC1
+a84f2ab246e691a88b527a84ce21896b95080070 ns-3.3-RC1
+654eed5f3ad03c04c2bcfb6852b5b4ae94260bc6 ns-3.3-RC2
+a66553c56a8f14644af6c229c83bb0a653cb3f32 ns-3.3-RC3
+dfd0bc16dc991313896f351530a3dc5a25f62e15 ns-3.3-RC4
+58ae52c5845ff03ba08dc921e13e6cf3604c810a ns-3.3-RC5
+4267fd454004f5a60e517496f43a01000ccebc72 ns-3.3-RC6
+2efae18e73794c0acd8061a9bd5c74b69f1b0d93 ns-3.3
+5396ecd09060bcb1e7b1f750bb170cbfde7a77c2 ns-3.4
+13a5b15fbe3429a6c3d00c1bccffa2c156a0603b ns-3.5-rc1
+8562a42accf6f715d312c037326ec7da48095e13 ns-3.5-rc2
+a600c11ff8d40a40e88c2d692acad6512dde70c8 ns-3.5-rc3
+c975274c9707b1f07d94cc51f205c351122131a5 ns-3.5
+549243b47311211975b388cd64fcb9111caa2fc2 ns-3.6-RC1
+8996042990466b1eda718a848e1c02923c0add74 ns-3.6-RC2
+79ff6ad1adbb7b4677759ddf52028b68b0515168 ns-3.6-RC3
+39a82d7a0d661febe42e75f26ada79424258e330 ns-3.6-RC4
+d55c479666ac6be0575fac695ddf355c0530e0dd ns-3.6
+892efc87a1518fb69b04628c779195aee139d33e ns-3.7-RC3
+17bf6ee332baaa6b6f9b8a26d29c98f4e715648f ns-3.7-RC4
+be3fb855c65a46d22a7693cd156f154f63602e8e ns-3.7
+e61ce382fcdd5363a9d0052601c5eeae6f5e8d81 ns-3.8-RC1
+3b7ec0d36079b22fbc8c0d86b8edb876bf0ae9d8 ns-3.8-RC2
+d588e7fe6cb064919e2738e71e6169dc9be94e0b ns-3.8-RC3
+533be42b3c7ff738d76517a9a6e48f1795f54844 ns-3.8-RC4
+0ef062c0897e189f016951c307eaceedccad81e0 ns-3.8
+fb5ad9c7755aa6ea871e76d322fd4c43a5b1047d ns-3.9-RC1
+14019c625ab84486f0c263074048b0519db15f73 ns-3.9-RC2
+def4153e27cd744f117acf8c509979617850da83 ns-3.9-RC3
+8ddf25211f8995cde73baa8b8a419711ed451b85 ns-3.9
+63a8a4ed4054f1e1cd1756045abba657f6fd884c ns-3.10
+440bbee145f096193abcdd67fe6c16de62935d89 ns-3.11-RC1
+0a7a16b599e86ca7884e5b5772bf7c5cfe146603 ns-3.11-RC2
+e48ed3aabca6ad71c8c49e4604c0f83345eda6a8 ns-3.11-RC3
+9843c12351cb5ceb9613c9db390d94073b713284 ns-3.11
+19c9e2b33b4a53f200be80cd49810bdfecf76770 ns-3.12-RC1
+167fc2274f53d4d89fdd769e4a7683ad7b6b7157 ns-3.12
@@ -1,7 +1,93 @@
-Raj Bhattarcharjea (raj.b@gatech.edu)
+Alexander Afanasyev <alexander.afanasyev@ucla.edu> 
+Kirill Andreev (andreev@iitp.ru)
+Dean Armstrong (deanarm@gmail.com)
+Nicola Baldo (nbaldo@cttc.es)
+Mirko Banchi (mk.banchi@gmail.com)
+Ramon Bauza (monbauza@gmail.com)
+Mehdi Benamor (mehdi.benamor@telecom-bretagne.eu)
+Raj Bhattacharjea (raj.b@gatech.edu)
+Timo Bingmann (timo.bingmann@student.kit.edu)
+Julien Boite <juboite@gmail.com> 
+Elena Borovkova (borokovaes@iitp.ru)
+Pavel Boyko (boyko@iitp.ru)
+Dan Broyles (muxman@sbcglobal.net)
+Jonathan Brugge (j.d.brugge@student.utwente.nl)
+Elena Buchatskaia (borovkovaes@iitp.ru)
 Gustavo Carneiro (gjc@inescporto.pt, gjcarneiro@gmail.com)
+Egemen K. Cetinkaya (ekc@iitc.ku.edu)
+Angelos Chatzipapas (chatzipa@ceid.upatras.gr)
+Andrey Churin (aachurin@gmail.com)
+Salva Climent (jocliba@gmail.com)
+Luis Cortes (cortes@gatech.edu)
 Craig Dowell (craigdo@ee.washington.edu)
+Denis Fakhriev (fakhriev@iitp.ru)
+Jahanzeb Farooq (Jahanzeb.Farooq@inria.fr, Jahanzeb.Farooq@gmail.com)
+Juliana Freitag Borin (juliana.freitag@gmail.com)
+Martin Giachino (martin.giachino@gmail.com,giachino@fing.edu.uy)
+Charline Taibi Guguen (charline.guguen@gmail.com)
+Tom Goff (tgoff@tgoff.net)
+David Gross (gdavid.devel@gmail.com)
+Daniel Halperin <daniel@halper.in>
 Tom Henderson (tomhend@u.washington.edu)
-Mathieu Lacage (mathieu.lacage@sophia.inria.fr)
+Blake Hurd (naimorai@gmail.com)
+ishan <ishan.chhabra@gmail.com>
+Mohamed Amine Ismail (amine.ismail@inria.fr, iamine@udcast.com)
+Atishay Jain <atishayjain25@gmail.com> 
+Sascha Alexander Jopen <jopen@informatik.uni-bonn.de>
+Sam Jansen (sam.jansen@gmail.com)
+Liu Jian (liujatp@gmail.com)
+Joe Kopena (tjkopena@cs.drexel.edu)
+Flavio Kobuta (flaviokubota@gmail.com)
+Aleksey Kovalenko (kovalenko@iitp.ru)
+Mathieu Lacage (mathieu.lacage@inria.fr)
 Emmanuelle Laprise (emmmanuelle.laprise@bluekazoo.ca)
+Björn Lichtblau (lichtbla@informatik.hu-berlin.de)
+Keith Ma (keith.nwsuaf@gmail.com)
+Federico Maguolo (maguolof@dei.unipd.it)
+Antti Makela (zarhan@cc.hut.fi)
+Francesco Malandrino (francesco.malandrino@gmail.com)
+Fabian Mauchle (f1mauchl@hsr.ch)
+Andrey Mazo (mazo@iitp.ru)
+Vedran Miletić <rivanvx@gmail.com>
+Faker Moatamri (faker.moatamri@inria.fr)
+Sidharth Nabar (snabar@uw.edu)
+Hemanth Narra (hemanth@ittc.ku.edu)
+Michael Nowatkowski (nowatkom@gmail.com)
+Duy Nguyen (duy@soe.ucsc.edu)
+Tommaso Pecorella (tommaso.pecorella@unifi.it)
+Josh Pelkey (jpelkey@gatech.edu)
+Colin Perkins <csp@csperkins.org> 
+Giuseppe Piro (g.piro@poliba.it)
+Yana Podkosova (yanapdk@rambler.ru)
+Guangyu Pei (guangyu.pei@boeing.com)
+Andrea Ranieri <andreran@uno.it>
+Bruno Ranieri (Yrrsinn@googlemail.com)
+Ken Renard (kenneth.renard@arl.army.mil)
 George F. Riley (riley@ece.gatech.edu)
+Bill Roome (wdr@bell-labs.com)
+Andrea Sacco (andrea.sacco85@gmail.com)
+Providence Salumu Munga (Providence.Salumu@gmail.com, Providence.Salumu_Munga@it-sudparis.eu)
+Florian Schmidt (Florian.Schmidt@cs.rwth-aachen.de)
+Guillaume Seguin (guillaume.seguin@inria.fr)
+Kulin Shah (m.kulin@gmail.com)
+Phillip Sitbon (phillip.sitbon@gmail.com)
+Anirudh Sivaraman <sk.anirudh@gmail.com> 
+Ewgenij Starostin (estar@cs.tu-berlin.de)
+YunQiang Su <wzssyqa@gmail.com>
+Lalith Suresh  (suresh.lalith@gmail.com)
+Marcos Talau <talau@users.sourceforge.net>
+Adrian S. W. Tam (adrian.sw.tam@gmail.com)
+Hajime Tazaki (tazaki@sfc.wide.ad.jp)
+Wilson Thong (wilsonwk@ee.cityu.edu.hk)
+Mauro Tortonesi (mauro.tortonesi@unife.it)
+Quincy Tse (quincy.tse@gmail.com)
+Frederic Urbani (frederic.urbani@inria.fr)
+Andras Varga (andras@omnetpp.org)
+Sebastien Vincent (vincent@clarinet.u-strasbg.fr)
+Guillaume Vu-Brugier (gvubrugier@gmail.com)
+Tom Wambold (tom5760@gmail.com)
+Danqi Wang (beyondwdq@gmail.com)
+Mitch Watrous (watrous@u.washington.edu)
+Florian Westphal (fw@strlen.de)
+He Wu (mdzz@u.washington.edu)
+Yoshihiko Yazawa (yoshiyaz@gmail.com)
@@ -5,63 +5,36 @@
 Table of Contents:
 ------------------

-1) An Open Source project
-2) An overview of the ns-3 project
-3) Building ns-3
-4) Running ns-3
-5) Getting access to the ns-3 documentation
-6) Working with the development version of ns-3
+1) An overview
+2) Building ns-3
+3) Running ns-3
+4) Getting access to the ns-3 documentation
+5) Working with the development version of ns-3

+Note:  Much more substantial information about ns-3 can be found at
+http://www.nsnam.org

 1) An Open Source project
 -------------------------

-ns-3 is an Open Source project.   We intend to make this
-project a successful collaborative project: we hope that 
+ns-3 is a free open source project aiming to build a discrete-event
+network simulator targeted for simulation research and education.   
+This is a collaborative project; we hope that
 the missing pieces of the models we have not yet implemented
 will be contributed by the community in an open collaboration
 process.

-Contributing to the ns-3 project is still a very informal
-process because that process depends heavily on the background
-of the people involved, the amount of time they can invest
-and the type of model they want to work on.  
+The process of contributing to the ns-3 project varies with
+the people involved, the amount of time they can invest
+and the type of model they want to work on, but the current
+process that the project tries to follow is described here:
+http://www.nsnam.org/developers/contributing-code/

-Despite this lack of a formal process, there are a number of 
-steps which naturally stem from the open-source roots of the
-project.  These steps are described in doc/contributing.txt
+This README excerpts some details from a more extensive
+tutorial that is maintained at:
+http://www.nsnam.org/documentation/latest/

-2) An overview of the ns-3 project
----------------------------------
-
-This package contains the latest version of ns-3 which aims 
-at being a replacement for ns-2. Currently, ns-3 provides a 
-number of very simple network simulation models:
-  - an ipv4 and udp stack
-  - arp support at the bottom of the stack
-  - point-to-point physical-layer links
-  - OnOff traffic generator
-
-Our focus to date has been on getting an overall software
-framework in place.  The framework is there to make adding 
-new models as simple as possible:
-  - an extensive tracing system can be used to connect
-    any number of arbitrary trace sources to any number
-    of trace sinks. This tracing system is decoupled
-    from the act of serializing the trace events to a 
-    file: users can and should provide their own
-    trace handling routines.
-
-  - simple file trace serialization support is included
-    to both text and pcap files.
-
-  - adding new MAC-level models simply requires subclassing
-    the pair of classes NetDevice and Channel.
-
-  - adding new traffic generation algorithms is also very 
-    simple through the Application and the Socket classes.
-
-3) Building ns-3
+2) Building ns-3
 ----------------

 The code for the framework and the default models provided
@@ -71,44 +44,39 @@ use of these ns-3 libraries.

 To build the set of default libraries and the example
 programs included in this package, you need to use the
-tool 'waf'. Detailed information on how to install
-and use waf is included in the file doc/build.txt
+tool 'waf'. Detailed information on how use waf is 
+included in the file doc/build.txt

 However, the real quick and dirty way to get started is to
-type the command "./waf" the the directory which contains
+type the command
+  ./waf configure --enable-examples
+followed by
+  ./waf 
+in the the directory which contains
 this README file. The files built will be copied in the
-build/debug or build/optimized.
+build/ directory.

 The current codebase is expected to build and run on the
-following set of platforms:
-  - linux x86 gcc 4.2, 4.1, and, 3.4.
-  - linux x86_64 gcc 4.0
-  - MacOS X ppc and x86
-  - cygwin
+set of platforms listed in the RELEASE_NOTES file.

-The current codebase is expected to fail to build on
-the following platforms:
-  - gcc 3.3 and earlier
-  - optimized builds on linux x86 gcc 4.0 
+Other platforms may or may not work: we welcome patches to 
+improve the portability of the code to these other platforms. 

-Other platforms may or may not work: we welcome 
-patches to improve the portability of the code to these
-other platforms.
-
-4) Running ns-3
+3) Running ns-3
 ---------------

-On recent Linux systems, once you have built ns-3, it 
-should be easy to run the sample programs with the
-following command:
+On recent Linux systems, once you have built ns-3 (with examples
+enabled), it should be easy to run the sample programs with the
+following command, such as:

-./waf --run simple-point-to-point
+  ./waf --run simple-global-routing

-That program should generate a simple-point-to-point.tr text 
-trace file and a set of simple-point-to-point-xx-xx.pcap binary
-pcap trace files, which can be read by tcpdump.
+That program should generate a simple-global-routing.tr text 
+trace file and a set of simple-global-routing-xx-xx.pcap binary
+pcap trace files, which can be read by tcpdump -tt -r filename.pcap
+The program source can be found in the examples/routing directory.

-5) Getting access to the ns-3 documentation
+4) Getting access to the ns-3 documentation
 -------------------------------------------

 Once you have verified that your build of ns-3 works by running
@@ -117,37 +85,24 @@ quite likely that you will want to get started on reading
 some ns-3 documentation. 

 All of that documentation should always be available from
-the ns-3 website: http:://www.nsnam.org/ but we
-include some of it in this release for ease of use.
+the ns-3 website: http:://www.nsnam.org/documentation/.

 This documentation includes:

-  - an architecture document which describes a very 
-    high-level view of ns-3: it tries to explain the
-    use-cases the ns-3 developers really focused on when
-    doing the initial design and then goes on to explain
-    the structure of the resulting framework.
-    See the file doc/architecture.pdf
+  - a tutorial
+ 
+  - a reference manual
+
+  - models in the ns-3 model library

  - a wiki for user-contributed tips: http://www.nsnam.org/wiki/

-  - an API documentation generated using doxygen: this is
+  - API documentation generated using doxygen: this is
    a reference manual, most likely not very well suited 
    as introductory text:
    http://www.nsnam.org/doxygen/index.html

-If you want to re-generate this documentation, you can 
-easily do so:
-
-  - doc/architecture.pdf is generated from the architecture.tex
-    file in http://code.nsnam.org/docs
-
-  - the doxygen documentation is generated from the doc/doxygen.conf
-    configuration file. The command "./waf --doxygen" will generate it
-    as doc/html/index.html if you have installed the doxygen tools 
-    (see http://www.doxygen.org)
-
-6) Working with the development version of ns-3
+5) Working with the development version of ns-3
 -----------------------------------------------

 If you want to download and use the development version 
@@ -1 +1 @@
-3.0.9
+3-dev
@@ -0,0 +1,13 @@
+from pybindgen import Module, FileCodeSink, write_preamble, param, retval
+
+def register_types(module):
+    module.add_class('MyClass')
+    
+def register_methods(root_module):
+    MyClass = root_module['MyClass']
+    MyClass.add_constructor([], visibility='public')
+    MyClass.add_constructor([param('double', 's'), param('double', 'l'), param('double', 'mean')], visibility='public')
+
+def register_functions(module):
+    module.add_function('SomeFunction', 'int', [param('int', 'xpto')])
+
@@ -0,0 +1,7 @@
+
+from _ns3 import *
+
+import atexit
+atexit.register(Simulator.Destroy)
+del atexit
+
@@ -0,0 +1,336 @@
+#include "ns3module.h"
+#include "ns3/ref-count-base.h"
+
+
+namespace ns3{
+
+void PythonCompleteConstruct (Ptr<Object> object, TypeId typeId, const AttributeList &attributes)
+{
+  object->SetTypeId (typeId);
+  object->Object::Construct (attributes);
+}
+
+}
+
+
+
+class PythonEventImpl : public ns3::EventImpl
+{
+private:
+    PyObject *m_callback;
+    PyObject *m_args;
+public:
+    PythonEventImpl (PyObject *callback, PyObject *args)
+    {
+        m_callback = callback;
+        Py_INCREF(m_callback);
+        m_args = args;
+        Py_INCREF(m_args);
+    }
+    virtual ~PythonEventImpl ()
+    {
+        PyGILState_STATE __py_gil_state;
+        __py_gil_state = (PyEval_ThreadsInitialized() ? PyGILState_Ensure() : (PyGILState_STATE) 0);
+
+        Py_DECREF(m_callback);
+        Py_DECREF(m_args);
+
+        if (PyEval_ThreadsInitialized())
+            PyGILState_Release(__py_gil_state);
+    }
+    virtual void Notify ()
+    {
+        PyGILState_STATE __py_gil_state;
+        __py_gil_state = (PyEval_ThreadsInitialized() ? PyGILState_Ensure() : (PyGILState_STATE) 0);
+        
+        PyObject *retval = PyObject_CallObject(m_callback, m_args);
+        if (retval) {
+            if (retval != Py_None) {
+                PyErr_SetString(PyExc_TypeError, "event callback should return None");
+                PyErr_Print();
+            }
+            Py_DECREF(retval);
+        } else {
+             PyErr_Print();
+        }
+
+        if (PyEval_ThreadsInitialized())
+            PyGILState_Release(__py_gil_state);
+    }
+};
+
+
+PyObject *
+_wrap_Simulator_Schedule(PyNs3Simulator *PYBINDGEN_UNUSED(dummy), PyObject *args, PyObject *kwargs,
+                         PyObject **return_exception)
+{
+    PyObject *exc_type, *traceback;
+    PyObject *py_time;
+    PyObject *py_callback;
+    PyObject *user_args;
+    ns3::Ptr<PythonEventImpl> py_event_impl;
+    PyNs3EventId *py_EventId;
+
+    if (kwargs && PyObject_Length(kwargs) > 0) {
+        PyErr_SetString(PyExc_TypeError, "keyword arguments not supported");
+        goto error;
+    }
+
+    if (PyTuple_GET_SIZE(args) < 2) {
+        PyErr_SetString(PyExc_TypeError, "ns3.Simulator.Schedule needs at least 2 arguments");
+        goto error;
+    }
+    py_time = PyTuple_GET_ITEM(args, 0);
+    py_callback = PyTuple_GET_ITEM(args, 1);
+
+    if (!PyObject_IsInstance(py_time, (PyObject*) &PyNs3Time_Type)) {
+        PyErr_SetString(PyExc_TypeError, "Parameter 1 should be a ns3.Time instance");
+        goto error;
+    }
+    if (!PyCallable_Check(py_callback)) {
+        PyErr_SetString(PyExc_TypeError, "Parameter 2 should be callable");
+        goto error;
+    }
+    user_args = PyTuple_GetSlice(args, 2, PyTuple_GET_SIZE(args));
+    py_event_impl = ns3::Create<PythonEventImpl>(py_callback, user_args);
+    Py_DECREF(user_args);
+
+    py_EventId = PyObject_New(PyNs3EventId, &PyNs3EventId_Type);
+    py_EventId->obj = new ns3::EventId(
+       ns3::Simulator::Schedule(*((PyNs3Time *) py_time)->obj, py_event_impl));
+    return (PyObject *) py_EventId;
+
+error:
+    PyErr_Fetch(&exc_type, return_exception, &traceback);
+    Py_XDECREF(exc_type);
+    Py_XDECREF(traceback);
+    return NULL;
+}
+
+
+PyObject *
+_wrap_Simulator_ScheduleNow(PyNs3Simulator *PYBINDGEN_UNUSED(dummy), PyObject *args, PyObject *kwargs,
+                            PyObject **return_exception)
+{
+    PyObject *exc_type, *traceback;
+    PyObject *py_callback;
+    PyObject *user_args;
+    ns3::Ptr<PythonEventImpl> py_event_impl;
+    PyNs3EventId *py_EventId;
+
+    if (kwargs && PyObject_Length(kwargs) > 0) {
+        PyErr_SetString(PyExc_TypeError, "keyword arguments not supported");
+        goto error;
+    }
+
+    if (PyTuple_GET_SIZE(args) < 1) {
+        PyErr_SetString(PyExc_TypeError, "ns3.Simulator.Schedule needs at least 1 argument");
+        goto error;
+    }
+    py_callback = PyTuple_GET_ITEM(args, 0);
+
+    if (!PyCallable_Check(py_callback)) {
+        PyErr_SetString(PyExc_TypeError, "Parameter 2 should be callable");
+        goto error;
+    }
+    user_args = PyTuple_GetSlice(args, 1, PyTuple_GET_SIZE(args));
+    py_event_impl = ns3::Create<PythonEventImpl>(py_callback, user_args);
+    Py_DECREF(user_args);
+
+    py_EventId = PyObject_New(PyNs3EventId, &PyNs3EventId_Type);
+    py_EventId->obj = new ns3::EventId(ns3::Simulator::ScheduleNow(py_event_impl));
+    return (PyObject *) py_EventId;
+
+error:
+    PyErr_Fetch(&exc_type, return_exception, &traceback);
+    Py_XDECREF(exc_type);
+    Py_XDECREF(traceback);
+    return NULL;
+}
+
+
+PyObject *
+_wrap_Simulator_ScheduleDestroy(PyNs3Simulator *PYBINDGEN_UNUSED(dummy), PyObject *args, PyObject *kwargs,
+                                PyObject **return_exception)
+{
+    PyObject *exc_type, *traceback;
+    PyObject *py_callback;
+    PyObject *user_args;
+    ns3::Ptr<PythonEventImpl> py_event_impl;
+    PyNs3EventId *py_EventId;
+
+    if (kwargs && PyObject_Length(kwargs) > 0) {
+        PyErr_SetString(PyExc_TypeError, "keyword arguments not supported");
+        goto error;
+    }
+
+    if (PyTuple_GET_SIZE(args) < 1) {
+        PyErr_SetString(PyExc_TypeError, "ns3.Simulator.Schedule needs at least 1 argument");
+        goto error;
+    }
+    py_callback = PyTuple_GET_ITEM(args, 0);
+
+    if (!PyCallable_Check(py_callback)) {
+        PyErr_SetString(PyExc_TypeError, "Parameter 2 should be callable");
+        goto error;
+    }
+    user_args = PyTuple_GetSlice(args, 1, PyTuple_GET_SIZE(args));
+    py_event_impl = ns3::Create<PythonEventImpl>(py_callback, user_args);
+    Py_DECREF(user_args);
+
+    py_EventId = PyObject_New(PyNs3EventId, &PyNs3EventId_Type);
+    py_EventId->obj = new ns3::EventId(ns3::Simulator::ScheduleDestroy(py_event_impl));
+    return (PyObject *) py_EventId;
+
+error:
+    PyErr_Fetch(&exc_type, return_exception, &traceback);
+    Py_XDECREF(exc_type);
+    Py_XDECREF(traceback);
+    return NULL;
+}
+
+
+PyObject *
+_wrap_TypeId_LookupByNameFailSafe(PyNs3TypeId *PYBINDGEN_UNUSED(dummy), PyObject *args, PyObject *kwargs,
+                                  PyObject **return_exception)
+{
+    bool ok;
+    const char *name;
+    Py_ssize_t name_len;
+    ns3::TypeId tid;
+    PyNs3TypeId *py_tid;
+    const char *keywords[] = {"name", NULL};
+    
+    if (!PyArg_ParseTupleAndKeywords(args, kwargs, (char *) "s#", (char **) keywords, &name, &name_len)) {
+        PyObject *exc_type, *traceback;
+        PyErr_Fetch(&exc_type, return_exception, &traceback);
+        Py_XDECREF(exc_type);
+        Py_XDECREF(traceback);
+        return NULL;
+    }
+    ok = ns3::TypeId::LookupByNameFailSafe(std::string(name, name_len), &tid);
+    if (!ok)
+    {
+        PyErr_Format(PyExc_KeyError, "The ns3 type with name `%s' is not registered", name);
+        return NULL;
+    }
+
+    py_tid = PyObject_New(PyNs3TypeId, &PyNs3TypeId_Type);
+    py_tid->obj = new ns3::TypeId (tid);
+    PyNs3TypeId_wrapper_registry[(void *) py_tid->obj] = (PyObject *) py_tid;    
+    
+    return (PyObject *) py_tid;
+}
+
+
+class CommandLinePythonValueSetter : public ns3::RefCountBase
+{
+    PyObject *m_namespace;
+    std::string m_variable;
+public:
+    CommandLinePythonValueSetter (PyObject *ns, std::string const &variable) {
+        Py_INCREF(ns);
+        m_namespace = ns;
+        m_variable = variable;
+    }
+    bool Parse (std::string value) {
+        PyObject *pyvalue = PyString_FromStringAndSize (value.data(), value.size());
+        PyObject_SetAttrString (m_namespace, (char *) m_variable.c_str(), pyvalue);
+        if (PyErr_Occurred()) {
+            PyErr_Print();
+            return false;
+        }
+        return true;
+    }
+    virtual ~CommandLinePythonValueSetter () {
+        Py_DECREF (m_namespace);
+        m_namespace = NULL;
+    }
+    
+};
+
+PyObject *
+_wrap_CommandLine_AddValue(PyNs3CommandLine *self, PyObject *args, PyObject *kwargs,
+                           PyObject **return_exception)
+{
+    const char *name, *help, *variable = NULL;
+    PyObject *py_namespace = NULL;
+    const char *keywords[] = {"name", "help", "variable", "namespace", NULL};
+    
+    if (!PyArg_ParseTupleAndKeywords(args, kwargs, (char *) "ss|sO", (char **) keywords, &name, &help, &variable, &py_namespace)) {
+        PyObject *exc_type, *traceback;
+        PyErr_Fetch(&exc_type, return_exception, &traceback);
+        Py_XDECREF(exc_type);
+        Py_XDECREF(traceback);
+        return NULL;
+    }
+    
+    if (variable == NULL) {
+        variable = name;
+    }
+    if (py_namespace == NULL) {
+        py_namespace = (PyObject *) self;
+    }
+
+    ns3::Ptr<CommandLinePythonValueSetter> setter = ns3::Create<CommandLinePythonValueSetter> (py_namespace, variable);
+    self->obj->AddValue (name, help, ns3::MakeCallback (&CommandLinePythonValueSetter::Parse, setter));
+
+    Py_INCREF(Py_None);
+    return Py_None;
+}
+
+
+PyObject *
+_wrap_Simulator_Run(PyNs3Simulator *PYBINDGEN_UNUSED(dummy), PyObject *args, PyObject *kwargs,
+                    PyObject **return_exception)
+{
+    const char *keywords[] = {"signal_check_frequency", NULL};
+    int signal_check_frequency;
+
+    ns3::Ptr<ns3::DefaultSimulatorImpl> defaultSim =
+        ns3::DynamicCast<ns3::DefaultSimulatorImpl> (ns3::Simulator::GetImplementation ());
+    if (defaultSim) {
+        signal_check_frequency = 100;
+    } else {
+        signal_check_frequency = -1;
+    }
+    
+    if (!PyArg_ParseTupleAndKeywords(args, kwargs, (char *) "|i", (char **) keywords, &signal_check_frequency)) {
+        PyObject *exc_type, *traceback;
+        PyErr_Fetch(&exc_type, return_exception, &traceback);
+        Py_XDECREF(exc_type);
+        Py_XDECREF(traceback);
+        return NULL;
+    }
+
+    PyThreadState *py_thread_state = NULL;
+
+    if (signal_check_frequency == -1)
+    {
+        if (PyEval_ThreadsInitialized ())
+            py_thread_state = PyEval_SaveThread();
+        ns3::Simulator::Run();
+        if (py_thread_state)
+            PyEval_RestoreThread(py_thread_state);
+    } else {
+        while (!ns3::Simulator::IsFinished())
+        {        
+            if (PyEval_ThreadsInitialized())
+                py_thread_state = PyEval_SaveThread();
+
+            for (int n = signal_check_frequency; n > 0 && !ns3::Simulator::IsFinished(); --n)
+            {        
+                ns3::Simulator::RunOneEvent();
+            }
+            
+            if (py_thread_state)
+                PyEval_RestoreThread(py_thread_state);
+            PyErr_CheckSignals();
+            if (PyErr_Occurred())
+                return NULL;
+        }
+    }
+    Py_INCREF(Py_None);
+    return Py_None;
+}
+
@@ -0,0 +1,113 @@
+import warnings
+import sys
+import os
+import pybindgen.settings
+from pybindgen import Module, FileCodeSink, param, retval, cppclass, typehandlers
+from pybindgen.module import MultiSectionFactory
+import ns3modulegen_core_customizations
+
+
+
+
+pybindgen.settings.wrapper_registry = pybindgen.settings.StdMapWrapperRegistry
+
+class ErrorHandler(pybindgen.settings.ErrorHandler):
+    def handle_error(self, wrapper, exception, traceback_):
+        warnings.warn("exception %r in wrapper %s" % (exception, wrapper))
+        return True
+pybindgen.settings.error_handler = ErrorHandler()
+
+
+#print >> sys.stderr, ">>>>>>>>>>>>>>>>>>>>>>>>>>>> ", bool(eval(os.environ["GCC_RTTI_ABI_COMPLETE"]))
+pybindgen.settings.gcc_rtti_abi_complete = bool(eval(os.environ["GCC_RTTI_ABI_COMPLETE"]))
+
+class MyMultiSectionFactory(MultiSectionFactory):
+    def __init__(self, main_file_name):
+        super(MyMultiSectionFactory, self).__init__()
+        self.main_file_name = main_file_name
+        self.main_sink = FileCodeSink(open(main_file_name, "wt"))
+        self.header_name = "ns3module.h"
+        header_file_name = os.path.join(os.path.dirname(self.main_file_name), self.header_name)
+        #print >> sys.stderr, ">>>>>>>>>>>>>>>>>", header_file_name, main_file_name
+        self.header_sink = FileCodeSink(open(header_file_name, "wt"))
+    def get_section_code_sink(self, section_name):
+        return self.main_sink
+    def get_main_code_sink(self):
+        return self.main_sink
+    def get_common_header_code_sink(self):
+        return self.header_sink
+    def get_common_header_include(self):
+        return '"%s"' % self.header_name
+    def close(self):
+        self.header_sink.file.close()
+        self.main_sink.file.close()
+
+
+
+def main(argv):
+    module_abs_src_path, target, extension_name, output_cc_file_name = argv[1:]
+    module_name = os.path.basename(module_abs_src_path)
+    out = MyMultiSectionFactory(output_cc_file_name)
+
+    sys.path.insert(0, os.path.join(module_abs_src_path, "bindings"))
+    try:
+        module_apidefs = __import__("modulegen__%s" % target)
+        del sys.modules["modulegen__%s" % target]
+        try:
+            module_customization = __import__("modulegen_customizations")
+            del sys.modules["modulegen_customizations"]
+        except ImportError:
+            module_customization = object()
+
+        try:
+            from callbacks_list import callback_classes
+        except ImportError, ex:
+            print >> sys.stderr, "***************", repr(ex)
+            callback_classes = []
+        else:
+            print >> sys.stderr, ">>>>>>>>>>>>>>>>", repr(callback_classes)
+
+    finally:
+        sys.path.pop(0)
+    
+    root_module = module_apidefs.module_init()
+    root_module.set_name(extension_name)
+    root_module.add_include('"ns3/%s-module.h"' % module_name)
+
+    ns3modulegen_core_customizations.add_std_ios_openmode(root_module)
+
+    # -----------
+    module_apidefs.register_types(root_module)
+
+    if hasattr(module_customization, 'post_register_types'):
+        module_customization.post_register_types(root_module)
+
+    # register Callback<...> type handlers
+    ns3modulegen_core_customizations.generate_callback_classes(root_module.after_forward_declarations,
+                                                               callback_classes)
+
+    # -----------
+    module_apidefs.register_methods(root_module)
+
+    if hasattr(module_customization, 'post_register_methods'):
+        module_customization.post_register_methods(root_module)
+
+    ns3modulegen_core_customizations.Object_customizations(root_module)
+    ns3modulegen_core_customizations.Attribute_customizations(root_module)
+
+
+    # -----------
+    module_apidefs.register_functions(root_module)
+    
+    if hasattr(module_customization, 'post_register_functions'):
+        module_customization.post_register_functions(root_module)
+
+
+    # -----------
+    root_module.generate(out)
+
+if __name__ == '__main__':
+    import sys
+    main(sys.argv)
+
+    
@@ -0,0 +1,177 @@
+
+LOCAL_MODULES = [
+    #'my_extra_api_definitions',
+    ]
+
+
+
+import sys
+import os
+
+sys.path.insert(0, sys.argv[2])
+
+from pybindgen import FileCodeSink, write_preamble
+from pybindgen.module import MultiSectionFactory
+
+import pybindgen.settings
+pybindgen.settings.deprecated_virtuals = False
+
+from ns3modulegen_generated import module_init, register_types, register_methods, register_functions
+import ns3modulegen_core_customizations
+import callbacks_list
+import traceback
+
+this_script_dir = os.path.dirname(os.path.abspath(sys.argv[0]))
+
+class ErrorHandler(pybindgen.settings.ErrorHandler):
+    def handle_error(self, wrapper, exception, traceback_):
+        print >> sys.stderr
+        print >> sys.stderr, "---- location:"
+        traceback.print_stack()
+        print >> sys.stderr, "---- error:"
+        traceback.print_tb(traceback_)
+        try:
+            stack = wrapper.stack_where_defined
+        except AttributeError:
+            print >> sys.stderr, "??:??: %s / %r" % (wrapper, exception)
+        else:
+            stack = list(stack)
+            stack.reverse()
+            for (filename, line_number, function_name, text) in stack:
+                file_dir = os.path.dirname(os.path.abspath(filename))
+                if file_dir.startswith(this_script_dir):
+                    print >> sys.stderr, "%s:%i: %r" % (os.path.join("..", "bindings", "python", os.path.basename(filename)),
+                                                        line_number, exception)
+                    break
+        return True
+pybindgen.settings.error_handler = ErrorHandler()
+
+pybindgen.settings.wrapper_registry = pybindgen.settings.StdMapWrapperRegistry
+
+
+class MyMultiSectionFactory(MultiSectionFactory):
+
+    def __init__(self, main_file_name, modules):
+        super(MyMultiSectionFactory, self).__init__()
+        self.main_file_name = main_file_name
+        self.main_sink = FileCodeSink(open(main_file_name, "wt"))
+        self.header_name = "ns3module.h"
+        header_file_name = os.path.join(os.path.dirname(self.main_file_name), 'pch', self.header_name)
+        self.header_sink = FileCodeSink(open(header_file_name, "wt"))
+        self.section_sinks = {'__main__': self.main_sink}
+
+        for module in modules:
+            section_name = 'ns3_module_%s' % module.replace('-', '_')
+            file_name = os.path.join(os.path.dirname(self.main_file_name), "%s.cc" % section_name)
+            sink = FileCodeSink(open(file_name, "wt"))
+            self.section_sinks[section_name] = sink            
+
+    def get_section_code_sink(self, section_name):
+        return self.section_sinks[section_name]
+
+    def get_main_code_sink(self):
+        return self.main_sink
+
+    def get_common_header_code_sink(self):
+        return self.header_sink
+
+    def get_common_header_include(self):
+        return '"%s"' % self.header_name
+
+    def close(self):
+        self.header_sink.file.close()
+        self.main_sink.file.close()
+        for sink in self.section_sinks.itervalues():
+            sink.file.close()
+
+
+
+def main():
+    out = MyMultiSectionFactory(sys.argv[1], sys.argv[3:])
+    root_module = module_init()
+    root_module.add_include('"everything.h"')
+
+    register_types(root_module)
+
+    ns3modulegen_core_customizations.Simulator_customizations(root_module)
+    ns3modulegen_core_customizations.CommandLine_customizations(root_module)
+    ns3modulegen_core_customizations.TypeId_customizations(root_module)
+    ns3modulegen_core_customizations.add_std_ofstream(root_module)
+    ns3modulegen_core_customizations.add_ipv4_address_tp_hash(root_module)
+
+
+    for local_module in LOCAL_MODULES:
+        mod = __import__(local_module)
+        mod.register_types(root_module)
+
+    ns3modulegen_core_customizations.generate_callback_classes(root_module.after_forward_declarations,
+                                                               callbacks_list.callback_classes)
+
+
+    register_methods(root_module)
+
+    for local_module in LOCAL_MODULES:
+        mod = __import__(local_module)
+        mod.register_methods(root_module)
+
+    ns3modulegen_core_customizations.Object_customizations(root_module)
+    ns3modulegen_core_customizations.Attribute_customizations(root_module)
+
+    register_functions(root_module)
+
+    for local_module in LOCAL_MODULES:
+        mod = __import__(local_module)
+        mod.register_functions(root_module)
+
+    enabled_features = os.environ['NS3_ENABLED_FEATURES'].split(',')
+
+    # if GtkConfigStore support is disabled, disable the class wrapper
+    if 'GtkConfigStore' not in enabled_features:
+        try:
+            root_module.classes.remove(root_module['ns3::GtkConfigStore'])
+        except KeyError:
+            pass
+
+    # if no sqlite, the class SqliteDataOutput is disabled
+    if 'SqliteDataOutput' not in enabled_features:
+        try:
+            root_module.classes.remove(root_module['ns3::SqliteDataOutput'])
+        except KeyError:
+            pass
+
+    if 'Threading' not in enabled_features:
+        for clsname in ['SystemThread', 'SystemMutex', 'SystemCondition', 'CriticalSection',
+                        'SimpleRefCount< ns3::SystemThread, ns3::empty, ns3::DefaultDeleter<ns3::SystemThread> >']:
+            root_module.classes.remove(root_module['ns3::%s' % clsname])
+
+    if 'EmuNetDevice' not in enabled_features:
+        for clsname in ['EmuNetDevice', 'EmuHelper']:
+            root_module.classes.remove(root_module['ns3::%s' % clsname])
+        root_module.enums.remove(root_module['ns3::EmuNetDevice::EncapsulationMode'])
+
+    if 'RealTime' not in enabled_features:
+        for clsname in ['WallClockSynchronizer', 'RealtimeSimulatorImpl']:
+            root_module.classes.remove(root_module['ns3::%s' % clsname])
+        root_module.enums.remove(root_module['ns3::RealtimeSimulatorImpl::SynchronizationMode'])
+
+    if 'TapBridge' not in enabled_features:
+        for clsname in ['TapBridge', 'TapBridgeHelper', 'TapBridgeFdReader']:
+            root_module.classes.remove(root_module['ns3::%s' % clsname])
+        root_module.enums.remove(root_module['ns3::TapBridge::Mode'])
+
+    root_module.generate(out, '_ns3')
+
+    out.close()
+
+if __name__ == '__main__':
+    if 0:
+        try:
+            import cProfile as profile
+        except ImportError:
+            main()
+        else:
+            print >> sys.stderr, "** running under profiler"
+            profile.run('main()', 'ns3modulegen.pstat')
+    else:
+        main()
+
@@ -0,0 +1,446 @@
+import re
+
+from pybindgen.typehandlers import base as typehandlers
+from pybindgen import ReturnValue, Parameter
+from pybindgen.cppmethod import CustomCppMethodWrapper, CustomCppConstructorWrapper
+from pybindgen.typehandlers.codesink import MemoryCodeSink
+from pybindgen.typehandlers import ctypeparser
+from pybindgen import cppclass
+import warnings
+
+from pybindgen.typehandlers.base import CodeGenerationError
+
+import sys
+
+class SmartPointerTransformation(typehandlers.TypeTransformation):
+    """
+    This class provides a "type transformation" that tends to support
+    NS-3 smart pointers.  Parameters such as "Ptr<Foo> foo" are
+    transformed into something like Parameter.new("Foo*", "foo",
+    transfer_ownership=False).  Return values such as Ptr<Foo> are
+    transformed into ReturnValue.new("Foo*",
+    caller_owns_return=False).  Since the underlying objects have
+    reference counting, PyBindGen does the right thing.
+    """
+    def __init__(self):
+        super(SmartPointerTransformation, self).__init__()
+        self.rx = re.compile(r'(ns3::|::ns3::|)Ptr<([^>]+)>\s*$')
+
+    def _get_untransformed_type_traits(self, name):
+        m = self.rx.match(name)
+        is_const = False
+        if m is None:
+            return None, False
+        else:
+            name1 = m.group(2).strip()
+            if name1.startswith('const '):
+                name1 = name1[len('const '):]
+                is_const = True
+            if name1.endswith(' const'):
+                name1 = name1[:-len(' const')]
+                is_const = True
+            new_name = name1+' *'
+
+            if new_name.startswith('::'):
+                new_name = new_name[2:]
+            return new_name, is_const
+
+    def get_untransformed_name(self, name):
+        new_name, dummy_is_const = self._get_untransformed_type_traits(name)
+        return new_name
+
+    def create_type_handler(self, type_handler, *args, **kwargs):
+        if issubclass(type_handler, Parameter):
+            kwargs['transfer_ownership'] = False
+        elif issubclass(type_handler, ReturnValue):
+            kwargs['caller_owns_return'] = False
+        else:
+            raise AssertionError
+
+        ## fix the ctype, add ns3:: namespace
+        orig_ctype, is_const = self._get_untransformed_type_traits(args[0])
+        if is_const:
+            correct_ctype = 'ns3::Ptr< %s const >' % orig_ctype[:-2]
+        else:
+            correct_ctype = 'ns3::Ptr< %s >' % orig_ctype[:-2]
+        args = tuple([correct_ctype] + list(args[1:]))
+
+        handler = type_handler(*args, **kwargs)
+        handler.set_tranformation(self, orig_ctype)
+        return handler
+
+    def untransform(self, type_handler, declarations, code_block, expression):
+        return 'const_cast<%s> (ns3::PeekPointer (%s))' % (type_handler.untransformed_ctype, expression)
+
+    def transform(self, type_handler, declarations, code_block, expression):
+        assert type_handler.untransformed_ctype[-1] == '*'
+        return 'ns3::Ptr< %s > (%s)' % (type_handler.untransformed_ctype[:-1], expression)
+
+## register the type transformation
+transf = SmartPointerTransformation()
+typehandlers.return_type_matcher.register_transformation(transf)
+typehandlers.param_type_matcher.register_transformation(transf)
+del transf
+
+
+class ArgvParam(Parameter):
+    """
+    Converts a python list-of-strings argument to a pair of 'int argc,
+    char *argv[]' arguments to pass into C.
+
+    One Python argument becomes two C function arguments -> it's a miracle!
+
+    Note: this parameter type handler is not registered by any name;
+    must be used explicitly.
+    """
+
+    DIRECTIONS = [Parameter.DIRECTION_IN]
+    CTYPES = []
+    
+    def convert_c_to_python(self, wrapper):
+        raise NotImplementedError
+
+    def convert_python_to_c(self, wrapper):
+        py_name = wrapper.declarations.declare_variable('PyObject*', 'py_' + self.name)
+        argc_var = wrapper.declarations.declare_variable('int', 'argc')
+        name = wrapper.declarations.declare_variable('char**', self.name)
+        idx = wrapper.declarations.declare_variable('Py_ssize_t', 'idx')
+        wrapper.parse_params.add_parameter('O!', ['&PyList_Type', '&'+py_name], self.name)
+
+        #wrapper.before_call.write_error_check('!PyList_Check(%s)' % py_name) # XXX
+
+        wrapper.before_call.write_code("%s = (char **) malloc(sizeof(char*)*PyList_Size(%s));"
+                                       % (name, py_name))
+        wrapper.before_call.add_cleanup_code('free(%s);' % name)
+        wrapper.before_call.write_code('''
+for (%(idx)s = 0; %(idx)s < PyList_Size(%(py_name)s); %(idx)s++)
+{
+''' % vars())
+        wrapper.before_call.sink.indent()
+        wrapper.before_call.write_code('''
+PyObject *item = PyList_GET_ITEM(%(py_name)s, %(idx)s);
+''' % vars())
+        #wrapper.before_call.write_error_check('item == NULL')
+        wrapper.before_call.write_error_check(
+            '!PyString_Check(item)',
+            failure_cleanup=('PyErr_SetString(PyExc_TypeError, '
+                             '"argument %s must be a list of strings");') % self.name)
+        wrapper.before_call.write_code(
+            '%s[%s] = PyString_AsString(item);' % (name, idx))
+        wrapper.before_call.sink.unindent()
+        wrapper.before_call.write_code('}')
+        wrapper.before_call.write_code('%s = PyList_Size(%s);' % (argc_var, py_name))
+        
+        wrapper.call_params.append(argc_var)
+        wrapper.call_params.append(name)
+
+
+class CallbackImplProxyMethod(typehandlers.ReverseWrapperBase):
+    """
+    Class that generates a proxy virtual method that calls a similarly named python method.
+    """
+
+    def __init__(self, return_value, parameters):
+        super(CallbackImplProxyMethod, self).__init__(return_value, parameters)
+
+    def generate_python_call(self):
+        """code to call the python method"""
+        build_params = self.build_params.get_parameters(force_tuple_creation=True)
+        if build_params[0][0] == '"':
+            build_params[0] = '(char *) ' + build_params[0]
+        args = self.before_call.declare_variable('PyObject*', 'args')
+        self.before_call.write_code('%s = Py_BuildValue(%s);'
+                                    % (args, ', '.join(build_params)))
+        self.before_call.add_cleanup_code('Py_DECREF(%s);' % args)
+        self.before_call.write_code('py_retval = PyObject_CallObject(m_callback, %s);' % args)
+        self.before_call.write_error_check('py_retval == NULL')
+        self.before_call.add_cleanup_code('Py_DECREF(py_retval);')
+
+
+
+
+def generate_callback_classes(out, callbacks):
+    for callback_impl_num, template_parameters in enumerate(callbacks):
+        sink = MemoryCodeSink()
+        cls_name = "ns3::Callback< %s >" % ', '.join(template_parameters)
+        #print >> sys.stderr, "***** trying to register callback: %r" % cls_name
+        class_name = "PythonCallbackImpl%i" % callback_impl_num
+        sink.writeln('''
+class %s : public ns3::CallbackImpl<%s>
+{
+public:
+    PyObject *m_callback;
+    %s(PyObject *callback)
+    {
+        Py_INCREF(callback);
+        m_callback = callback;
+    }
+    virtual ~%s()
+    {
+        Py_DECREF(m_callback);
+        m_callback = NULL;
+    }
+
+    virtual bool IsEqual(ns3::Ptr<const ns3::CallbackImplBase> other_base) const
+    {
+        const %s *other = dynamic_cast<const %s*> (ns3::PeekPointer (other_base));
+        if (other != NULL)
+            return (other->m_callback == m_callback);
+        else
+            return false;
+    }
+
+''' % (class_name, ', '.join(template_parameters), class_name, class_name, class_name, class_name))
+        sink.indent()
+        callback_return = template_parameters[0]
+        return_ctype = ctypeparser.parse_type(callback_return)
+        if ('const' in return_ctype.remove_modifiers()):
+            kwargs = {'is_const': True}
+        else:
+            kwargs = {}
+        try:
+            return_type = ReturnValue.new(str(return_ctype), **kwargs)
+        except (typehandlers.TypeLookupError, typehandlers.TypeConfigurationError), ex:
+            warnings.warn("***** Unable to register callback; Return value '%s' error (used in %s): %r"
+                          % (callback_return, cls_name, ex),
+                          Warning)
+            continue
+
+        arguments = []
+        ok = True
+        callback_parameters = [arg for arg in template_parameters[1:] if arg != 'ns3::empty']
+        for arg_num, arg_type in enumerate(callback_parameters):
+            arg_name = 'arg%i' % (arg_num+1)
+
+            param_ctype = ctypeparser.parse_type(arg_type)
+            if ('const' in param_ctype.remove_modifiers()):
+                kwargs = {'is_const': True}
+            else:
+                kwargs = {}
+            try:
+                arguments.append(Parameter.new(str(param_ctype), arg_name, **kwargs))
+            except (typehandlers.TypeLookupError, typehandlers.TypeConfigurationError), ex:
+                warnings.warn("***** Unable to register callback; parameter '%s %s' error (used in %s): %r"
+                              % (arg_type, arg_name, cls_name, ex),
+                              Warning)
+                ok = False
+        if not ok:
+            continue
+
+        wrapper = CallbackImplProxyMethod(return_type, arguments)
+        wrapper.generate(sink, 'operator()', decl_modifiers=[])
+            
+        sink.unindent()
+        sink.writeln('};\n')
+        sink.flush_to(out)
+        
+        class PythonCallbackParameter(Parameter):
+            "Class handlers"
+            CTYPES = [cls_name]
+            print >> sys.stderr, "***** registering callback handler: %r" % ctypeparser.normalize_type_string(cls_name)
+            DIRECTIONS = [Parameter.DIRECTION_IN]
+            PYTHON_CALLBACK_IMPL_NAME = class_name
+            TEMPLATE_ARGS = template_parameters
+
+            def convert_python_to_c(self, wrapper):
+                "parses python args to get C++ value"
+                assert isinstance(wrapper, typehandlers.ForwardWrapperBase)
+
+                if self.default_value is None:
+                    py_callback = wrapper.declarations.declare_variable('PyObject*', self.name)
+                    wrapper.parse_params.add_parameter('O', ['&'+py_callback], self.name)
+                    wrapper.before_call.write_error_check(
+                        '!PyCallable_Check(%s)' % py_callback,
+                        'PyErr_SetString(PyExc_TypeError, "parameter \'%s\' must be callbale");' % self.name)
+                    callback_impl = wrapper.declarations.declare_variable(
+                        'ns3::Ptr<%s>' % self.PYTHON_CALLBACK_IMPL_NAME,
+                        '%s_cb_impl' % self.name)
+                    wrapper.before_call.write_code("%s = ns3::Create<%s> (%s);"
+                                                   % (callback_impl, self.PYTHON_CALLBACK_IMPL_NAME, py_callback))
+                    wrapper.call_params.append(
+                        'ns3::Callback<%s> (%s)' % (', '.join(self.TEMPLATE_ARGS), callback_impl))
+                else:
+                    py_callback = wrapper.declarations.declare_variable('PyObject*', self.name, 'NULL')
+                    wrapper.parse_params.add_parameter('O', ['&'+py_callback], self.name, optional=True)
+                    value = wrapper.declarations.declare_variable(
+                        'ns3::Callback<%s>' % ', '.join(self.TEMPLATE_ARGS),
+                        self.name+'_value',
+                        self.default_value)
+
+                    wrapper.before_call.write_code("if (%s) {" % (py_callback,))
+                    wrapper.before_call.indent()
+
+                    wrapper.before_call.write_error_check(
+                        '!PyCallable_Check(%s)' % py_callback,
+                        'PyErr_SetString(PyExc_TypeError, "parameter \'%s\' must be callbale");' % self.name)
+
+                    wrapper.before_call.write_code("%s = ns3::Callback<%s> (ns3::Create<%s> (%s));"
+                                                   % (value, ', '.join(self.TEMPLATE_ARGS),
+                                                      self.PYTHON_CALLBACK_IMPL_NAME, py_callback))
+
+                    wrapper.before_call.unindent()
+                    wrapper.before_call.write_code("}") # closes: if (py_callback) {
+                                        
+                    wrapper.call_params.append(value)
+                    
+
+            def convert_c_to_python(self, wrapper):
+                raise typehandlers.NotSupportedError("Reverse wrappers for ns3::Callback<...> types "
+                                                     "(python using callbacks defined in C++) not implemented.")
+
+
+# def write_preamble(out):
+#     pybindgen.write_preamble(out)
+#     out.writeln("#include \"ns3/everything.h\"")
+
+
+
+def Simulator_customizations(module):
+    Simulator = module['ns3::Simulator']
+
+    ## Simulator::Schedule(delay, callback, ...user..args...)
+    Simulator.add_custom_method_wrapper("Schedule", "_wrap_Simulator_Schedule",
+                                        flags=["METH_VARARGS", "METH_KEYWORDS", "METH_STATIC"])
+
+
+    ## Simulator::ScheduleNow(callback, ...user..args...)
+    Simulator.add_custom_method_wrapper("ScheduleNow", "_wrap_Simulator_ScheduleNow",
+                                        flags=["METH_VARARGS", "METH_KEYWORDS", "METH_STATIC"])
+
+
+    ## Simulator::ScheduleDestroy(callback, ...user..args...)
+    Simulator.add_custom_method_wrapper("ScheduleDestroy", "_wrap_Simulator_ScheduleDestroy",
+                                        flags=["METH_VARARGS", "METH_KEYWORDS", "METH_STATIC"])
+
+    Simulator.add_custom_method_wrapper("Run", "_wrap_Simulator_Run",
+                                        flags=["METH_VARARGS", "METH_KEYWORDS", "METH_STATIC"])
+
+
+def CommandLine_customizations(module):
+    CommandLine = module['ns3::CommandLine']
+    CommandLine.add_method('Parse', None, [ArgvParam(None, 'argv')],
+                           is_static=False)
+    CommandLine.add_custom_method_wrapper("AddValue", "_wrap_CommandLine_AddValue",
+                                          flags=["METH_VARARGS", "METH_KEYWORDS"])
+
+
+def Object_customizations(module):
+    ## ---------------------------------------------------------------------
+    ## Here we generate custom constructor code for all classes that
+    ## derive from ns3::Object.  The custom constructors are needed in
+    ## order to support kwargs only and to translate kwargs into ns3
+    ## attributes, etc.
+    ## ---------------------------------------------------------------------
+    try:
+        Object = module['ns3::Object']
+    except KeyError:
+        return
+
+    ## add a GetTypeId method to all generatd helper classes
+    def helper_class_hook(helper_class):
+        decl = """
+static ns3::TypeId GetTypeId (void)
+{
+  static ns3::TypeId tid = ns3::TypeId ("%s")
+    .SetParent< %s > ()
+    ;
+  return tid;
+}"""  % (helper_class.name, helper_class.class_.full_name)
+
+        helper_class.add_custom_method(decl)
+        helper_class.add_post_generation_code(
+            "NS_OBJECT_ENSURE_REGISTERED (%s);" % helper_class.name)
+    Object.add_helper_class_hook(helper_class_hook)
+
+    def ns3_object_instance_creation_function(cpp_class, code_block, lvalue,
+                                              parameters, construct_type_name):
+        assert lvalue
+        assert not lvalue.startswith('None')
+        if cpp_class.cannot_be_constructed:
+            raise CodeGenerationError("%s cannot be constructed (%s)"
+                                      % cpp_class.full_name)
+        if cpp_class.incomplete_type:
+            raise CodeGenerationError("%s cannot be constructed (incomplete type)"
+                                      % cpp_class.full_name)
+        code_block.write_code("%s = new %s(%s);" % (lvalue, construct_type_name, parameters))
+        code_block.write_code("%s->Ref ();" % (lvalue))
+
+    def ns3_object_post_instance_creation_function(cpp_class, code_block, lvalue,
+                                                   parameters, construct_type_name):
+        code_block.write_code("ns3::CompleteConstruct(%s);" % (lvalue, ))
+
+    Object.set_instance_creation_function(ns3_object_instance_creation_function)
+    Object.set_post_instance_creation_function(ns3_object_post_instance_creation_function)
+
+
+def Attribute_customizations(module):
+    # Fix up for the "const AttributeValue &v = EmptyAttribute()"
+    # case, as used extensively by helper classes.
+
+    # Here's why we need to do this: pybindgen.gccxmlscanner, when
+    # scanning parameter default values, is only provided with the
+    # value as a simple C expression string.  (py)gccxml does not
+    # report the type of the default value.
+
+    # As a workaround, here we iterate over all parameters of all
+    # methods of all classes and tell pybindgen what is the type of
+    # the default value for attributes.
+
+    for cls in module.classes:
+        for meth in cls.get_all_methods():
+            for param in meth.parameters:
+                if isinstance(param, cppclass.CppClassRefParameter):
+                    if param.cpp_class.name == 'AttributeValue' \
+                            and param.default_value is not None \
+                            and param.default_value_type is None:
+                        param.default_value_type = 'ns3::EmptyAttributeValue'
+
+
+def TypeId_customizations(module):
+    TypeId = module['ns3::TypeId']
+    TypeId.add_custom_method_wrapper("LookupByNameFailSafe", "_wrap_TypeId_LookupByNameFailSafe",
+                                     flags=["METH_VARARGS", "METH_KEYWORDS", "METH_STATIC"])
+
+
+def add_std_ofstream(module):
+    module.add_include('<fstream>')
+    ostream = module.add_class('ostream', foreign_cpp_namespace='::std')
+    ostream.set_cannot_be_constructed("abstract base class")
+    ofstream = module.add_class('ofstream', foreign_cpp_namespace='::std', parent=ostream)
+    ofstream.add_enum('openmode', [
+            ('app', 'std::ios_base::app'),
+            ('ate', 'std::ios_base::ate'),
+            ('binary', 'std::ios_base::binary'),
+            ('in', 'std::ios_base::in'),
+            ('out', 'std::ios_base::out'),
+            ('trunc', 'std::ios_base::trunc'),
+            ])
+    ofstream.add_constructor([Parameter.new("const char *", 'filename'),
+                              Parameter.new("::std::ofstream::openmode", 'mode', default_value="std::ios_base::out")])
+    ofstream.add_method('close', None, [])
+    
+    add_std_ios_openmode(module)
+
+
+def add_std_ios_openmode(module):
+    import pybindgen.typehandlers.base
+    for alias in "std::_Ios_Openmode", "std::ios::openmode":
+        pybindgen.typehandlers.base.param_type_matcher.add_type_alias(alias, "int")
+
+    for flag in 'in', 'out', 'ate', 'app', 'trunc', 'binary':
+        module.after_init.write_code('PyModule_AddIntConstant(m, (char *) "STD_IOS_%s", std::ios::%s);'
+                                     % (flag.upper(), flag))
+
+
+
+def add_ipv4_address_tp_hash(module):
+    module.body.writeln('''
+long
+_ns3_Ipv4Address_tp_hash (PyObject *obj)
+{
+   PyNs3Ipv4Address *addr = reinterpret_cast<PyNs3Ipv4Address *> (obj);
+   return static_cast<long> (ns3::Ipv4AddressHash () (*addr->obj));
+}
+''')
+    module.header.writeln('long _ns3_Ipv4Address_tp_hash (PyObject *obj);')
+    module['Ipv4Address'].pytype.slots['tp_hash'] = "_ns3_Ipv4Address_tp_hash"
@@ -0,0 +1,281 @@
+#! /usr/bin/env python
+
+import sys
+import os.path
+
+import pybindgen.settings
+from pybindgen.gccxmlparser import ModuleParser, PygenClassifier, PygenSection, WrapperWarning, find_declaration_from_name
+from pybindgen.typehandlers.codesink import FileCodeSink
+from pygccxml.declarations import templates
+from pygccxml.declarations.enumeration import enumeration_t
+from pygccxml.declarations.class_declaration import class_t
+from pygccxml.declarations.calldef import free_function_t, member_function_t, constructor_t, calldef_t
+
+
+## we need the smart pointer type transformation to be active even
+## during gccxml scanning.
+import ns3modulegen_core_customizations
+
+
+## silence gccxmlparser errors; we only want error handling in the
+## generated python script, not while scanning.
+class ErrorHandler(pybindgen.settings.ErrorHandler):
+    def handle_error(self, dummy_wrapper, dummy_exception, dummy_traceback_):
+        return True
+pybindgen.settings.error_handler = ErrorHandler()
+import warnings
+warnings.filterwarnings(category=WrapperWarning, action='ignore')
+
+
+import ns3modulescan
+type_annotations = ns3modulescan.type_annotations
+
+
+def get_ns3_relative_path(path):
+    l = []
+    head = path
+    while head:
+        new_head, tail = os.path.split(head)
+        if new_head == head:
+            raise ValueError
+        head = new_head
+        if tail == 'ns3':
+            return os.path.join(*l)
+        l.insert(0, tail)
+    raise AssertionError("is the path %r inside ns3?!" % path)
+
+class PreScanHook:
+
+    def __init__(self, headers_map, module):
+        self.headers_map = headers_map
+        self.module = module
+
+    def __call__(self, module_parser,
+                 pygccxml_definition,
+                 global_annotations,
+                 parameter_annotations):
+        try:
+            ns3_header = get_ns3_relative_path(pygccxml_definition.location.file_name)
+        except ValueError: # the header is not from ns3
+            return # ignore the definition, it's not ns-3 def.
+
+        definition_module = self.headers_map[ns3_header]
+
+        ## Note: we don't include line numbers in the comments because
+        ## those numbers are very likely to change frequently, which would
+        ## cause needless changes, since the generated python files are
+        ## kept under version control.
+
+        #global_annotations['pygen_comment'] = "%s:%i: %s" % \
+        #    (ns3_header, pygccxml_definition.location.line, pygccxml_definition)
+        global_annotations['pygen_comment'] = "%s (module %r): %s" % \
+            (ns3_header, definition_module, pygccxml_definition)
+
+
+        ## handle ns3::Object::GetObject (left to its own devices,
+        ## pybindgen will generate a mangled name containing the template
+        ## argument type name).
+        if isinstance(pygccxml_definition, member_function_t) \
+                and pygccxml_definition.parent.name == 'Object' \
+                and pygccxml_definition.name == 'GetObject':
+            template_args = templates.args(pygccxml_definition.demangled_name)
+            if template_args == ['ns3::Object']:
+                global_annotations['template_instance_names'] = 'ns3::Object=>GetObject'
+
+        ## Don't wrap Simulator::Schedule* (manually wrapped)
+        if isinstance(pygccxml_definition, member_function_t) \
+                and pygccxml_definition.parent.name == 'Simulator' \
+                and pygccxml_definition.name.startswith('Schedule'):
+            global_annotations['ignore'] = None
+
+        # manually wrapped
+        if isinstance(pygccxml_definition, member_function_t) \
+                and pygccxml_definition.parent.name == 'Simulator' \
+                and pygccxml_definition.name == 'Run':
+            global_annotations['ignore'] = True
+
+        ## http://www.gccxml.org/Bug/view.php?id=9915
+        if isinstance(pygccxml_definition, calldef_t):
+            for arg in pygccxml_definition.arguments:
+                if arg.default_value is None:
+                    continue
+                elif arg.default_value == "ns3::MilliSeconds( )":
+                    arg.default_value = "ns3::MilliSeconds(0)"
+                elif arg.default_value == "ns3::Seconds( )":
+                    arg.default_value = "ns3::Seconds(0)"
+
+        ## classes
+        if isinstance(pygccxml_definition, class_t):
+            print >> sys.stderr, pygccxml_definition
+            # no need for helper classes to allow subclassing in Python, I think...
+            #if pygccxml_definition.name.endswith('Helper'):
+            #    global_annotations['allow_subclassing'] = 'false'
+
+            #
+            # If a class is template instantiation, even if the
+            # template was defined in some other module, if a template
+            # argument belongs to this module then the template
+            # instantiation will belong to this module.
+            # 
+            if templates.is_instantiation(pygccxml_definition.decl_string):
+                cls_name, template_parameters = templates.split(pygccxml_definition.name)
+                template_parameters_decls = [find_declaration_from_name(module_parser.global_ns, templ_param)
+                                             for templ_param in template_parameters]
+                #print >> sys.stderr, "********************", cls_name, repr(template_parameters_decls)
+                
+                template_parameters_modules = []
+                for templ in template_parameters_decls:
+                    if not hasattr(templ, 'location'):
+                        continue
+                    try:
+                        h = get_ns3_relative_path(templ.location.file_name)
+                    except ValueError:
+                        continue
+                    template_parameters_modules.append(self.headers_map[h])
+
+                for templ_mod in template_parameters_modules:
+                    if templ_mod == self.module:
+                        definition_module = templ_mod
+                        break
+                #print >> sys.stderr, "********************", cls_name, repr(template_parameters_modules)
+
+
+            if definition_module != self.module:
+                global_annotations['import_from_module'] = 'ns.%s' % (definition_module.replace('-', '_'),)
+
+            if pygccxml_definition.decl_string.startswith('::ns3::SimpleRefCount<'):
+                global_annotations['incref_method'] = 'Ref'
+                global_annotations['decref_method'] = 'Unref'
+                global_annotations['peekref_method'] = 'GetReferenceCount'
+                global_annotations['automatic_type_narrowing'] = 'true'
+                return
+
+            if pygccxml_definition.decl_string.startswith('::ns3::Callback<'):
+                # manually handled in ns3modulegen_core_customizations.py
+                global_annotations['ignore'] = None
+                return
+
+            if pygccxml_definition.decl_string.startswith('::ns3::TracedCallback<'):
+                global_annotations['ignore'] = None
+                return
+
+            if pygccxml_definition.decl_string.startswith('::ns3::Ptr<'):
+                # handled by pybindgen "type transformation"
+                global_annotations['ignore'] = None
+                return
+
+            # table driven class customization
+            try:
+                annotations = type_annotations[pygccxml_definition.decl_string]
+            except KeyError:
+                pass
+            else:
+                global_annotations.update(annotations)
+
+        ## enums
+        if isinstance(pygccxml_definition, enumeration_t):
+            if definition_module != self.module:
+                global_annotations['import_from_module'] = 'ns.%s' % definition_module
+
+        ## free functions
+        if isinstance(pygccxml_definition, free_function_t):
+
+            if definition_module != self.module:
+                global_annotations['ignore'] = None
+                return
+
+            if pygccxml_definition.name == 'PeekPointer':
+                global_annotations['ignore'] = None
+                return
+
+        ## table driven methods/constructors/functions customization
+        if isinstance(pygccxml_definition, (free_function_t, member_function_t, constructor_t)):
+            try:
+                annotations = type_annotations[str(pygccxml_definition)]
+            except KeyError:
+                pass
+            else:
+                for key,value in annotations.items():
+                    if key == 'params':
+                        parameter_annotations.update (value)
+                        del annotations['params']
+                global_annotations.update(annotations)
+
+
+# def post_scan_hook(dummy_module_parser, dummy_pygccxml_definition, pybindgen_wrapper):
+#     ## classes
+#     if isinstance(pybindgen_wrapper, CppClass):
+#         if pybindgen_wrapper.name.endswith('Checker'):
+#             print >> sys.stderr, "!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!", pybindgen_wrapper
+#             #pybindgen_wrapper.set_instance_creation_function(AttributeChecker_instance_creation_function)
+
+
+def scan_callback_classes(module_parser, callback_classes_file):
+    callback_classes_file.write("callback_classes = [\n")
+    for cls in module_parser.module_namespace.classes(function=module_parser.location_filter,
+                                                      recursive=False):
+        if not cls.name.startswith("Callback<"):
+            continue
+        assert templates.is_instantiation(cls.decl_string), "%s is not a template instantiation" % cls
+        dummy_cls_name, template_parameters = templates.split(cls.decl_string)
+        callback_classes_file.write("    %r,\n" % template_parameters)
+    callback_classes_file.write("]\n")
+
+
+def ns3_module_scan(top_builddir, module_name, headers_map, output_file_name, cflags):
+    module_parser = ModuleParser('ns.%s' % module_name.replace('-', '_'), 'ns3')
+    module_parser.add_pre_scan_hook(PreScanHook(headers_map, module_name))
+    #module_parser.add_post_scan_hook(post_scan_hook)
+
+    gccxml_options = dict(
+        include_paths=[top_builddir],
+         define_symbols={
+            #'NS3_ASSERT_ENABLE': None,
+            #'NS3_LOG_ENABLE': None,
+            },
+        cflags=('--gccxml-cxxflags "%s -DPYTHON_SCAN"' % cflags)
+        )
+
+    try:
+        os.unlink(output_file_name)
+    except OSError:
+        pass
+    try:
+        os.makedirs(os.path.dirname(output_file_name))
+    except OSError:
+        pass
+    output_file = open(output_file_name, "wt")
+    output_sink = FileCodeSink(output_file)
+
+    # if there exists a scan-header.h file in src/<module>/bindings,
+    # scan it, otherwise scan ns3/xxxx-module.h.
+    scan_header = os.path.join(os.path.dirname(output_file_name), "scan-header.h")
+    if not os.path.exists(scan_header):
+        scan_header = os.path.join(top_builddir, "ns3", "%s-module.h" % module_name)
+
+    module_parser.parse_init([scan_header],
+                             None, whitelist_paths=[top_builddir],
+                             #includes=['"ns3/everything.h"'],
+                             pygen_sink=output_sink,
+                             gccxml_options=gccxml_options)
+    module_parser.scan_types()
+
+    callback_classes_file = open(os.path.join(os.path.dirname(output_file_name), "callbacks_list.py"), "wt")
+    scan_callback_classes(module_parser, callback_classes_file)
+    callback_classes_file.close()
+
+
+    module_parser.scan_methods()
+    module_parser.scan_functions()
+    module_parser.parse_finalize()
+
+    output_file.close()
+    os.chmod(output_file_name, 0400)
+
+
+if __name__ == '__main__':
+    if len(sys.argv) != 6:
+        print "ns3modulescan-modular.py top_builddir module_path module_headers output_file_name cflags"
+        sys.exit(1)
+    ns3_module_scan(sys.argv[1], sys.argv[2], eval(sys.argv[3]), sys.argv[4], sys.argv[5])
+    sys.exit(0)
@@ -0,0 +1,333 @@
+#! /usr/bin/env python
+
+import sys
+import os.path
+
+import pybindgen.settings
+from pybindgen.gccxmlparser import ModuleParser, PygenClassifier, PygenSection, WrapperWarning
+from pybindgen.typehandlers.codesink import FileCodeSink
+from pygccxml.declarations import templates
+from pygccxml.declarations.class_declaration import class_t
+from pygccxml.declarations.calldef import free_function_t, member_function_t, constructor_t, calldef_t
+
+
+## we need the smart pointer type transformation to be active even
+## during gccxml scanning.
+import ns3modulegen_core_customizations
+
+
+## silence gccxmlparser errors; we only want error handling in the
+## generated python script, not while scanning.
+class ErrorHandler(pybindgen.settings.ErrorHandler):
+    def handle_error(self, dummy_wrapper, dummy_exception, dummy_traceback_):
+        return True
+pybindgen.settings.error_handler = ErrorHandler()
+import warnings
+warnings.filterwarnings(category=WrapperWarning, action='ignore')
+
+type_annotations = {
+    '::ns3::AttributeChecker': {
+        'automatic_type_narrowing': 'true',
+        'allow_subclassing': 'false',
+        },
+    '::ns3::AttributeValue': {
+        'automatic_type_narrowing': 'true',
+        'allow_subclassing': 'false',
+        },
+
+    '::ns3::CommandLine': {
+        'allow_subclassing': 'true', # needed so that AddValue is able to set attributes on the object
+        },
+
+    '::ns3::NscTcpL4Protocol': {
+        'ignore': 'true', # this class is implementation detail
+        },
+
+
+    'ns3::RandomVariable::RandomVariable(ns3::RandomVariableBase const & variable) [constructor]': {
+        'ignore': None,
+        },
+    'ns3::RandomVariableBase * ns3::RandomVariable::Peek() const [member function]': {
+        'ignore': None,
+        },
+    'void ns3::RandomVariable::GetSeed(uint32_t * seed) const [member function]': {
+        'params': {'seed':{'direction':'out',
+                           'array_length':'6'}}
+        },
+    'bool ns3::TypeId::LookupAttributeByName(std::string name, ns3::TypeId::AttributeInfo * info) const [member function]': {
+        'params': {'info':{'transfer_ownership': 'false'}}
+        },
+    'static bool ns3::TypeId::LookupByNameFailSafe(std::string name, ns3::TypeId * tid) [member function]': {
+        'ignore': None, # manually wrapped in 
+        },
+    'bool ns3::TraceSourceAccessor::ConnectWithoutContext(ns3::ObjectBase * obj, ns3::CallbackBase const & cb) const [member function]': {
+        'params': {'obj': {'transfer_ownership':'false'}}
+        },
+    'bool ns3::TraceSourceAccessor::Connect(ns3::ObjectBase * obj, std::string context, ns3::CallbackBase const & cb) const [member function]': {
+        'params': {'obj': {'transfer_ownership':'false'}}
+        },
+    'bool ns3::TraceSourceAccessor::DisconnectWithoutContext(ns3::ObjectBase * obj, ns3::CallbackBase const & cb) const [member function]': {
+        'params': {'obj': {'transfer_ownership':'false'}}
+        },
+    'bool ns3::TraceSourceAccessor::Disconnect(ns3::ObjectBase * obj, std::string context, ns3::CallbackBase const & cb) const [member function]': {
+        'params': {'obj': {'transfer_ownership':'false'}}
+        },
+    'bool ns3::AttributeAccessor::Set(ns3::ObjectBase * object, ns3::AttributeValue const & value) const [member function]': {
+        'params': {'object': {'transfer_ownership':'false'}}
+        },
+    'ns3::EmpiricalVariable::EmpiricalVariable(ns3::RandomVariableBase const & variable) [constructor]': {
+        'ignore': None
+        },
+    'static ns3::AttributeList * ns3::AttributeList::GetGlobal() [member function]': {
+        'caller_owns_return': 'false'
+        },
+    'void ns3::CommandLine::Parse(int argc, char * * argv) const [member function]': {
+        'ignore': None # manually wrapped
+        },
+    'extern void ns3::PythonCompleteConstruct(ns3::Ptr<ns3::Object> object, ns3::TypeId typeId, ns3::AttributeList const & attributes) [free function]': {
+        'ignore': None # used transparently by, should not be wrapped
+        },
+
+    'ns3::Ptr<ns3::Ipv4RoutingProtocol> ns3::Ipv4ListRouting::GetRoutingProtocol(uint32_t index, int16_t & priority) const [member function]': {
+        'params': {'priority':{'direction':'out'}}
+        },
+    'ns3::Ipv4RoutingTableEntry * ns3::GlobalRouter::GetInjectedRoute(uint32_t i) [member function]': {
+        'params': {'return': { 'caller_owns_return': 'false',}},
+        },
+    'ns3::Ipv4RoutingTableEntry * ns3::Ipv4GlobalRouting::GetRoute(uint32_t i) const [member function]': {
+        'params': {'return': { 'caller_owns_return': 'false',}},
+        },
+
+    '::ns3::TestCase': {
+        'ignore': 'true', # we don't need to write test cases in Python
+        },
+    '::ns3::TestRunner': {
+        'ignore': 'true', # we don't need to write test cases in Python
+        },
+    '::ns3::TestSuite': {
+        'ignore': 'true', # we don't need to write test cases in Python
+        },
+    
+    }
+
+def get_ns3_relative_path(path):
+    l = []
+    head = path
+    while head:
+        head, tail = os.path.split(head)
+        if tail == 'ns3':
+            return os.path.join(*l)
+        l.insert(0, tail)
+    raise AssertionError("is the path %r inside ns3?!" % path)
+
+
+def pre_scan_hook(dummy_module_parser,
+                  pygccxml_definition,
+                  global_annotations,
+                  parameter_annotations):
+    ns3_header = get_ns3_relative_path(pygccxml_definition.location.file_name)
+
+    ## Note: we don't include line numbers in the comments because
+    ## those numbers are very likely to change frequently, which would
+    ## cause needless changes, since the generated python files are
+    ## kept under version control.
+
+    #global_annotations['pygen_comment'] = "%s:%i: %s" % \
+    #    (ns3_header, pygccxml_definition.location.line, pygccxml_definition)
+    global_annotations['pygen_comment'] = "%s: %s" % \
+        (ns3_header, pygccxml_definition)
+
+
+    ## handle ns3::Object::GetObject (left to its own devices,
+    ## pybindgen will generate a mangled name containing the template
+    ## argument type name).
+    if isinstance(pygccxml_definition, member_function_t) \
+            and pygccxml_definition.parent.name == 'Object' \
+            and pygccxml_definition.name == 'GetObject':
+        template_args = templates.args(pygccxml_definition.demangled_name)
+        if template_args == ['ns3::Object']:
+            global_annotations['template_instance_names'] = 'ns3::Object=>GetObject'
+
+    ## Don't wrap Simulator::Schedule* (manually wrapped)
+    if isinstance(pygccxml_definition, member_function_t) \
+            and pygccxml_definition.parent.name == 'Simulator' \
+            and pygccxml_definition.name.startswith('Schedule'):
+        global_annotations['ignore'] = None
+
+    # manually wrapped
+    if isinstance(pygccxml_definition, member_function_t) \
+            and pygccxml_definition.parent.name == 'Simulator' \
+            and pygccxml_definition.name == 'Run':
+        global_annotations['ignore'] = True
+
+    ## http://www.gccxml.org/Bug/view.php?id=9915
+    if isinstance(pygccxml_definition, calldef_t):
+        for arg in pygccxml_definition.arguments:
+            if arg.default_value is None:
+                continue
+            if "ns3::MilliSeconds( )" == arg.default_value:
+                arg.default_value = "ns3::MilliSeconds(0)"
+            if "ns3::Seconds( )" == arg.default_value:
+                arg.default_value = "ns3::Seconds(0)"
+
+    ## classes
+    if isinstance(pygccxml_definition, class_t):
+        # no need for helper classes to allow subclassing in Python, I think...
+        #if pygccxml_definition.name.endswith('Helper'):
+        #    global_annotations['allow_subclassing'] = 'false'
+
+        if pygccxml_definition.decl_string.startswith('::ns3::SimpleRefCount<'):
+            global_annotations['incref_method'] = 'Ref'
+            global_annotations['decref_method'] = 'Unref'
+            global_annotations['peekref_method'] = 'GetReferenceCount'
+            global_annotations['automatic_type_narrowing'] = 'true'
+            return
+
+        if pygccxml_definition.decl_string.startswith('::ns3::Callback<'):
+            # manually handled in ns3modulegen_core_customizations.py
+            global_annotations['ignore'] = None
+            return
+
+        if pygccxml_definition.decl_string.startswith('::ns3::TracedCallback<'):
+            global_annotations['ignore'] = None
+            return
+
+        if pygccxml_definition.decl_string.startswith('::ns3::Ptr<'):
+            # handled by pybindgen "type transformation"
+            global_annotations['ignore'] = None
+            return
+
+        # table driven class customization
+        try:
+            annotations = type_annotations[pygccxml_definition.decl_string]
+        except KeyError:
+            pass
+        else:
+            global_annotations.update(annotations)
+
+    ## free functions
+    if isinstance(pygccxml_definition, free_function_t):
+        if pygccxml_definition.name == 'PeekPointer':
+            global_annotations['ignore'] = None
+            return
+
+    ## table driven methods/constructors/functions customization
+    if isinstance(pygccxml_definition, (free_function_t, member_function_t, constructor_t)):
+        try:
+            annotations = type_annotations[str(pygccxml_definition)]
+        except KeyError:
+            pass
+        else:
+            for key,value in annotations.items():
+                if key == 'params':
+                    parameter_annotations.update (value)
+                    del annotations['params']
+            global_annotations.update(annotations)
+
+
+# def post_scan_hook(dummy_module_parser, dummy_pygccxml_definition, pybindgen_wrapper):
+#     ## classes
+#     if isinstance(pybindgen_wrapper, CppClass):
+#         if pybindgen_wrapper.name.endswith('Checker'):
+#             print >> sys.stderr, "!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!", pybindgen_wrapper
+#             #pybindgen_wrapper.set_instance_creation_function(AttributeChecker_instance_creation_function)
+
+
+def scan_callback_classes(module_parser, callback_classes_file):
+    callback_classes_file.write("callback_classes = [\n")
+    for cls in module_parser.module_namespace.classes(function=module_parser.location_filter,
+                                                      recursive=False):
+        if not cls.name.startswith("Callback<"):
+            continue
+        assert templates.is_instantiation(cls.decl_string), "%s is not a template instantiation" % cls
+        dummy_cls_name, template_parameters = templates.split(cls.decl_string)
+        callback_classes_file.write("    %r,\n" % template_parameters)
+    callback_classes_file.write("]\n")
+
+
+class MyPygenClassifier(PygenClassifier):
+    def __init__(self, headers_map, section_precendences):
+        self.headers_map = headers_map
+        self.section_precendences = section_precendences
+
+    def classify(self, pygccxml_definition):
+        name = os.path.basename(pygccxml_definition.location.file_name)
+        try:
+            return self.headers_map[name]
+        except KeyError:
+            return '__main__'
+
+    def get_section_precedence(self, section_name):
+        if section_name == '__main__':
+            return -1
+        return self.section_precendences[section_name]
+
+
+def ns3_module_scan(top_builddir, pygen_file_name, everything_h, cflags):
+
+    ns3_modules = eval(sys.stdin.readline())
+
+    ## do a topological sort on the modules graph
+    from topsort import topsort
+    graph = []
+    module_names = ns3_modules.keys()
+    module_names.sort()
+    for ns3_module_name in module_names:
+        ns3_module_deps = list(ns3_modules[ns3_module_name][0])
+        ns3_module_deps.sort()
+        for dep in ns3_module_deps:
+            graph.append((dep, ns3_module_name))
+    sorted_ns3_modules = topsort(graph)
+    #print >> sys.stderr, "******* topological sort: ", sorted_ns3_modules
+
+    sections = [PygenSection('__main__', FileCodeSink(open(pygen_file_name, "wt")))]
+    headers_map = {} # header_name -> section_name
+    section_precendences = {} # section_name -> precedence
+    for prec, ns3_module in enumerate(sorted_ns3_modules):
+        section_name = "ns3_module_%s" % ns3_module.replace('-', '_')
+        file_name = os.path.join(os.path.dirname(pygen_file_name), "%s.py" % section_name)
+        sections.append(PygenSection(section_name, FileCodeSink(open(file_name, "wt")),
+                                     section_name + "__local"))
+        for header in ns3_modules[ns3_module][1]:
+            headers_map[header] = section_name
+        section_precendences[section_name] = prec
+
+    module_parser = ModuleParser('ns3', 'ns3')
+
+    module_parser.add_pre_scan_hook(pre_scan_hook)
+    #module_parser.add_post_scan_hook(post_scan_hook)
+
+    gccxml_options = dict(
+        include_paths=[top_builddir],
+         define_symbols={
+            #'NS3_ASSERT_ENABLE': None,
+            #'NS3_LOG_ENABLE': None,
+            },
+        cflags=('--gccxml-cxxflags "%s -DPYTHON_SCAN"' % cflags)
+        )
+
+    module_parser.parse_init([everything_h],
+                             None, whitelist_paths=[top_builddir, os.path.dirname(everything_h)],
+                             #includes=['"ns3/everything.h"'],
+                             pygen_sink=sections,
+                             pygen_classifier=MyPygenClassifier(headers_map, section_precendences),
+                             gccxml_options=gccxml_options)
+    module_parser.scan_types()
+
+    callback_classes_file = open(os.path.join(os.path.dirname(pygen_file_name), "callbacks_list.py"), "wt")
+    scan_callback_classes(module_parser, callback_classes_file)
+    callback_classes_file.close()
+
+
+    module_parser.scan_methods()
+    module_parser.scan_functions()
+    module_parser.parse_finalize()
+
+    for section in sections:
+        section.code_sink.file.close()
+
+
+
+if __name__ == '__main__':
+    ns3_module_scan(sys.argv[1], sys.argv[3], sys.argv[2], sys.argv[4])
+
@@ -0,0 +1 @@
+
@@ -0,0 +1 @@
+placeholder
@@ -0,0 +1,909 @@
+# Copyright (c) 2007 RADLogic
+# 
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+# 
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+# 
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+"""Provide various handy Python functions.
+
+Running this script directly will execute the doctests.
+
+Functions:
+int2bin(i, n) -- Convert integer to binary string.
+bin2int(bin_string) -- Convert binary string to integer.
+reverse(input_string) -- Reverse a string.
+transpose(matrix) -- Transpose a list of lists.
+polygon_area(points_list) -- Calculate the area of an arbitrary polygon.
+timestamp() -- Return string containing current time stamp.
+pt2str(point) -- Return prettier string version of point tuple.
+gcf(a, b) -- Return the greatest common factor of two numbers.
+lcm(a, b) -- Return the least common multiple of two numbers.
+permutations(input_list) -- Generate all permutations of a list of items.
+reduce_fraction(fraction) -- Reduce fraction (num, denom) to simplest form.
+quantile(l, p) -- Return p quantile of list l. E.g. p=0.25 for q1.
+trim(l) -- Discard values in list more than 1.5*IQR outside IQR.
+nice_units(value) -- Return value converted to human readable units.
+uniquify(seq) -- Return sequence with duplicate items in sequence seq removed.
+reverse_dict(d) -- Return the dictionary with the items as keys and vice-versa.
+lsb(x, n) -- Return the n least significant bits of x.
+gray_encode(i) -- Gray encode the given integer.
+random_vec(bits, max_value=None) -- Return a random binary vector.
+binary_range(bits) -- Return list of all possible binary numbers width=bits.
+float_range([start], stop, [step]) -- Return range of floats.
+find_common_fixes(s1, s2) -- Find common (prefix, suffix) of two strings.
+is_rotated(seq1, seq2) -- Return true if the list is a rotation of other list.
+getmodule(obj) -- Return the module that contains the object definition of obj.
+                  (use inspect.getmodule instead, though)
+get_args(argv) -- Store command-line args in a dictionary.
+
+This module requires Python >= 2.2
+
+"""
+__author__ = 'Tim Wegener <twegener@radlogic.com.au>'
+__date__ = '$Date: 2007/03/27 03:15:06 $'
+__version__ = '$Revision: 0.45 $'
+__credits__ = """
+              David Chandler, for polygon area algorithm.
+               (http://www.davidchandler.com/AreaOfAGeneralPolygon.pdf)
+              """
+
+import re
+import sys
+import time
+import random
+
+try:
+    True, False
+except NameError:
+    True, False = (1==1, 0==1)
+
+
+def int2bin(i, n):
+    """Convert decimal integer i to n-bit binary number (string).
+
+    >>> int2bin(0, 8)
+    '00000000'
+
+    >>> int2bin(123, 8)
+    '01111011'
+
+    >>> int2bin(123L, 8)
+    '01111011'
+
+    >>> int2bin(15, 2)
+    Traceback (most recent call last):
+    ValueError: Value too large for given number of bits.
+
+    """
+    hex2bin = {'0': '0000', '1': '0001', '2': '0010', '3': '0011',
+               '4': '0100', '5': '0101', '6': '0110', '7': '0111',
+               '8': '1000', '9': '1001', 'a': '1010', 'b': '1011',
+               'c': '1100', 'd': '1101', 'e': '1110', 'f': '1111'}
+    # Convert to hex then map each hex digit to binary equivalent.
+    result = ''.join([hex2bin[x] for x in hex(i).lower().replace('l','')[2:]])
+                      
+    # Shrink result to appropriate length.
+    # Raise an error if the value is changed by the truncation.
+    if '1' in result[:-n]:
+        raise ValueError("Value too large for given number of bits.")
+    result = result[-n:]
+    # Zero-pad if length longer than mapped result.
+    result = '0'*(n-len(result)) + result
+    return result
+
+
+def bin2int(bin_string):
+    """Convert binary number string to decimal integer.
+    
+    Note: Python > v2 has int(bin_string, 2)
+
+    >>> bin2int('1111')
+    15
+
+    >>> bin2int('0101')
+    5
+
+    """
+##     result = 0
+##     bin_list = list(bin_string)
+##     if len(filter(lambda x: x in ('1','0'), bin_list)) < len(bin_list):
+##         raise Exception ("bin2int: Error - not a binary number: %s"
+##                          % bin_string)
+##     bit_list = map(int, bin_list)
+##     bit_list.reverse()  # Make most significant bit have highest index.
+##     for bit_place in range(len(bit_list)):
+##         result = result + ((2**bit_place) * bit_list[bit_place])
+##     return result
+    return int(bin_string, 2)
+
+
+def reverse(input_string):
+    """Reverse a string. Useful for strings of binary numbers.
+
+    >>> reverse('abc')
+    'cba'
+
+    """
+    str_list = list(input_string)
+    str_list.reverse()
+    return ''.join(str_list)
+
+
+def transpose(matrix):
+    """Transpose a list of lists.
+
+    >>> transpose([['a', 'b', 'c'], ['d', 'e', 'f'], ['g', 'h', 'i']])
+    [['a', 'd', 'g'], ['b', 'e', 'h'], ['c', 'f', 'i']]
+
+    >>> transpose([['a', 'b', 'c'], ['d', 'e', 'f']])
+    [['a', 'd'], ['b', 'e'], ['c', 'f']]
+
+    >>> transpose([['a', 'b'], ['d', 'e'], ['g', 'h']])
+    [['a', 'd', 'g'], ['b', 'e', 'h']]
+
+    """
+    result = zip(*matrix)
+    # Convert list of tuples to list of lists.
+    # map is faster than a list comprehension since it is being used with
+    # a built-in function as an argument.
+    result = map(list, result)
+    return result
+
+
+def polygon_area(points_list, precision=100):
+    """Calculate area of an arbitrary polygon using an algorithm from the web.
+
+    Return the area of the polygon as a positive float. 
+
+    Arguments:
+    points_list -- list of point tuples [(x0, y0), (x1, y1), (x2, y2), ...]
+                   (Unclosed polygons will be closed automatically.
+    precision -- Internal arithmetic precision (integer arithmetic).
+
+    >>> polygon_area([(0, 0), (0, 1), (1, 1), (1, 2), (2, 2), (2, 0), (0, 0)])
+    3.0
+
+    Credits:
+    Area of a General Polygon by David Chandler
+    http://www.davidchandler.com/AreaOfAGeneralPolygon.pdf
+    
+    """
+    # Scale up co-ordinates and convert them to integers.
+    for i in range(len(points_list)):
+        points_list[i] = (int(points_list[i][0] * precision),
+                          int(points_list[i][1] * precision))
+    # Close polygon if not closed.
+    if points_list[-1] != points_list[0]:
+        points_list.append(points_list[0])
+    # Calculate area.
+    area = 0
+    for i in range(len(points_list)-1):
+        (x_i, y_i) = points_list[i]
+        (x_i_plus_1, y_i_plus_1) = points_list[i+1]
+        area = area + (x_i_plus_1 * y_i) - (y_i_plus_1 * x_i)
+    area = abs(area / 2)
+    # Unscale area.
+    area = float(area)/(precision**2)
+    return area
+
+
+def timestamp():
+    """Return string containing current time stamp.
+
+    Note: In Python 2 onwards can use time.asctime() with no arguments.
+
+    """
+
+    return time.asctime()
+
+
+def pt2str(point):
+    """Return prettier string version of point tuple.
+
+    >>> pt2str((1.8, 1.9))
+    '(1.8, 1.9)'
+
+    """
+    return "(%s, %s)" % (str(point[0]), str(point[1]))
+
+
+def gcf(a, b, epsilon=1e-16):
+    """Return the greatest common factor of a and b, using Euclidean algorithm.
+
+    Arguments:
+    a, b -- two numbers
+            If both numbers are integers return an integer result, 
+            otherwise return a float result.
+    epsilon -- floats less than this magnitude are considered to be zero
+               (default: 1e-16)
+
+    Examples:
+
+    >>> gcf(12, 34)
+    2
+
+    >>> gcf(13.5, 4)
+    0.5
+
+    >>> gcf(-2, 4)
+    2
+
+    >>> gcf(5, 0)
+    5
+
+    By (a convenient) definition:
+    >>> gcf(0, 0)
+    0
+
+    """
+    result = max(a, b)
+    remainder = min(a, b)
+    while remainder and abs(remainder) > epsilon:
+        new_remainder = result % remainder
+        result = remainder
+        remainder = new_remainder
+    return abs(result)
+
+def lcm(a, b, precision=None):
+    """Return the least common multiple of a and b, using the gcf function.
+
+    Arguments:
+    a, b -- two numbers. If both are integers return an integer result, 
+            otherwise a return a float result.
+    precision -- scaling factor if a and/or b are floats.
+
+    >>> lcm(21, 6)
+    42
+
+    >>> lcm(2.5, 3.5)
+    17.5
+
+    >>> str(lcm(1.5e-8, 2.5e-8, precision=1e9))
+    '7.5e-08'
+
+    By (an arbitary) definition:
+    >>> lcm(0, 0)
+    0
+
+    """
+    # Note: Dummy precision argument is for backwards compatibility.
+    # Do the division first.
+    # (See http://en.wikipedia.org/wiki/Least_common_multiple )
+    denom = gcf(a, b)
+    if denom == 0:
+        result = 0
+    else:
+        result = a * (b / denom)
+    return result
+
+
+def permutations(input_list):
+    """Return a list containing all permutations of the input list.
+
+    Note: This is a recursive function.
+
+    >>> perms = permutations(['a', 'b', 'c'])
+    >>> perms.sort()
+    >>> for perm in perms:
+    ...     print perm
+    ['a', 'b', 'c']
+    ['a', 'c', 'b']
+    ['b', 'a', 'c']
+    ['b', 'c', 'a']
+    ['c', 'a', 'b']
+    ['c', 'b', 'a']
+
+    """
+    out_lists = []
+    if len(input_list) > 1:
+        # Extract first item in list.
+        item = input_list[0]
+        # Find all permutations of remainder of list. (Recursive call.)
+        sub_lists = permutations(input_list[1:])
+        # For every permutation of the sub list...
+        for sub_list in sub_lists:
+            # Insert the extracted first item at every position of the list.
+            for i in range(len(input_list)):
+                new_list = sub_list[:]
+                new_list.insert(i, item)
+                out_lists.append(new_list)
+    else:
+        # Termination condition: only one item in input list.
+        out_lists = [input_list]
+    return out_lists
+
+
+def reduce_fraction(fraction):
+    """Reduce fraction tuple to simplest form. fraction=(num, denom)
+    
+    >>> reduce_fraction((14, 7))
+    (2, 1)
+
+    >>> reduce_fraction((-2, 4))
+    (-1, 2)
+
+    >>> reduce_fraction((0, 4))
+    (0, 1)
+
+    >>> reduce_fraction((4, 0))
+    (1, 0)
+    
+    """
+    (numerator, denominator) = fraction
+    common_factor = abs(gcf(numerator, denominator))
+    result = (numerator/common_factor, denominator/common_factor)
+    return result
+
+
+def quantile(l, p):
+    """Return p quantile of list l. E.g. p=0.25 for q1.
+
+    See:
+    http://rweb.stat.umn.edu/R/library/base/html/quantile.html
+
+    """
+    l_sort = l[:]
+    l_sort.sort()
+    n = len(l)
+    r = 1 + ((n - 1) * p)
+    i = int(r)
+    f = r - i
+    if i < n:
+        result =  (1-f)*l_sort[i-1] + f*l_sort[i]
+    else:
+        result = l_sort[i-1]
+    return result
+
+
+def trim(l):
+    """Discard values in list more than 1.5*IQR outside IQR.
+
+    (IQR is inter-quartile-range)
+
+    This function uses rad_util.quantile
+
+    1.5*IQR -- mild outlier
+    3*IQR -- extreme outlier
+
+    See:
+    http://wind.cc.whecn.edu/~pwildman/statnew/section_7_-_exploratory_data_analysis.htm
+
+    """
+    l_sort = l[:]
+    l_sort.sort()
+    # Calculate medianscore  (based on stats.py lmedianscore by Gary Strangman)
+    if len(l_sort) % 2 == 0:
+        # If even number of scores, average middle 2.
+        index = int(len(l_sort) / 2)  # Integer division correct
+        median = float(l_sort[index] + l_sort[index-1]) / 2
+    else:
+        # int divsion gives mid value when count from 0
+        index = int(len(l_sort) / 2)
+        median = l_sort[index]
+    # Calculate IQR.
+    q1 = quantile(l_sort, 0.25)
+    q3 = quantile(l_sort, 0.75)
+    iqr = q3 - q1
+    iqr_extra = iqr * 1.5
+    def in_interval(x, i=iqr_extra, q1=q1, q3=q3):
+        return (x >= q1-i and x <= q3+i)
+    l_trimmed = [x for x in l_sort if in_interval(x)]
+    return l_trimmed
+
+
+def nice_units(value, dp=0, sigfigs=None, suffix='', space=' ',
+               use_extra_prefixes=False, use_full_name=False, mode='si'):
+    """Return value converted to human readable units eg milli, micro, etc.
+
+    Arguments:
+    value -- number in base units
+    dp -- number of decimal places to display (rounded)
+    sigfigs -- number of significant figures to display (rounded)
+               This overrides dp if set.
+    suffix -- optional unit suffix to append to unit multiplier
+    space -- seperator between value and unit multiplier (default: ' ')
+    use_extra_prefixes -- use hecto, deka, deci and centi as well if set.
+                          (default: False)
+    use_full_name -- use full name for multiplier symbol,
+                     e.g. milli instead of m
+                     (default: False)
+    mode -- 'si' for SI prefixes, 'bin' for binary multipliers (1024, etc.)
+            (Default: 'si')
+
+    SI prefixes from:
+    http://physics.nist.gov/cuu/Units/prefixes.html
+    (Greek mu changed to u.)
+    Binary prefixes based on:
+    http://physics.nist.gov/cuu/Units/binary.html
+
+    >>> nice_units(2e-11)
+    '20 p'
+
+    >>> nice_units(2e-11, space='')
+    '20p'
+
+    """
+    si_prefixes = {1e24:  ('Y', 'yotta'),
+                   1e21:  ('Z', 'zetta'),
+                   1e18:  ('E', 'exa'),
+                   1e15:  ('P', 'peta'),
+                   1e12:  ('T', 'tera'),
+                   1e9:   ('G', 'giga'),
+                   1e6:   ('M', 'mega'),
+                   1e3:   ('k', 'kilo'),
+                   1e-3:  ('m', 'milli'),
+                   1e-6:  ('u', 'micro'),
+                   1e-9:  ('n', 'nano'),
+                   1e-12: ('p', 'pico'),
+                   1e-15: ('f', 'femto'),
+                   1e-18: ('a', 'atto'),
+                   1e-21: ('z', 'zepto'),
+                   1e-24: ('y', 'yocto')
+                   }
+    if use_extra_prefixes:
+        si_prefixes.update({1e2:  ('h', 'hecto'),
+                            1e1:  ('da', 'deka'),
+                            1e-1: ('d', 'deci'),
+                            1e-2: ('c', 'centi')
+                            })
+    bin_prefixes = {2**10: ('K', 'kilo'),
+                    2**20: ('M', 'mega'),
+                    2**30: ('G', 'mega'),
+                    2**40: ('T', 'tera'),
+                    2**50: ('P', 'peta'),
+                    2**60: ('E', 'exa')
+                    }
+    if mode == 'bin':
+        prefixes = bin_prefixes
+    else:
+        prefixes = si_prefixes
+    prefixes[1] = ('', '')  # Unity.
+    # Determine appropriate multiplier.
+    multipliers = prefixes.keys()
+    multipliers.sort()
+    mult = None
+    for i in range(len(multipliers) - 1):
+        lower_mult = multipliers[i]
+        upper_mult = multipliers[i+1]
+        if lower_mult <= value < upper_mult:
+            mult_i = i
+            break
+    if mult is None:
+        if value < multipliers[0]:
+            mult_i = 0
+        elif value >= multipliers[-1]:
+            mult_i = len(multipliers) - 1
+    mult = multipliers[mult_i]
+    # Convert value for this multiplier.
+    new_value = value / mult
+    # Deal with special case due to rounding.
+    if sigfigs is None:
+        if mult_i < (len(multipliers) - 1) and \
+               round(new_value, dp) == \
+               round((multipliers[mult_i+1] / mult), dp):
+            mult = multipliers[mult_i + 1]
+            new_value = value / mult
+    # Concatenate multiplier symbol.
+    if use_full_name:
+        label_type = 1
+    else:
+        label_type = 0
+    # Round and truncate to appropriate precision.
+    if sigfigs is None:
+        str_value = eval('"%.'+str(dp)+'f" % new_value', locals(), {})
+    else:
+        str_value = eval('"%.'+str(sigfigs)+'g" % new_value', locals(), {})
+    return str_value + space + prefixes[mult][label_type] + suffix
+
+
+def uniquify(seq, preserve_order=False):
+    """Return sequence with duplicate items in sequence seq removed.
+
+    The code is based on usenet post by Tim Peters.
+
+    This code is O(N) if the sequence items are hashable, O(N**2) if not.
+    
+    Peter Bengtsson has a blog post with an empirical comparison of other
+    approaches:
+    http://www.peterbe.com/plog/uniqifiers-benchmark
+
+    If order is not important and the sequence items are hashable then
+    list(set(seq)) is readable and efficient.
+
+    If order is important and the sequence items are hashable generator
+    expressions can be used (in py >= 2.4) (useful for large sequences):
+    seen = set()
+    do_something(x for x in seq if x not in seen or seen.add(x))
+
+    Arguments:
+    seq -- sequence
+    preserve_order -- if not set the order will be arbitrary
+                      Using this option will incur a speed penalty.
+                      (default: False)
+
+    Example showing order preservation:
+
+    >>> uniquify(['a', 'aa', 'b', 'b', 'ccc', 'ccc', 'd'], preserve_order=True)
+    ['a', 'aa', 'b', 'ccc', 'd']
+
+    Example using a sequence of un-hashable items:
+
+    >>> uniquify([['z'], ['x'], ['y'], ['z']], preserve_order=True)
+    [['z'], ['x'], ['y']]
+
+    The sorted output or the non-order-preserving approach should equal
+    that of the sorted order-preserving approach output:
+    
+    >>> unordered = uniquify([3, 3, 1, 2], preserve_order=False)
+    >>> unordered.sort()
+    >>> ordered = uniquify([3, 3, 1, 2], preserve_order=True)
+    >>> ordered.sort()
+    >>> ordered
+    [1, 2, 3]
+    >>> int(ordered == unordered)
+    1
+
+    """
+    try:
+        # Attempt fast algorithm.
+        d = {}
+        if preserve_order:
+            # This is based on Dave Kirby's method (f8) noted in the post:
+            # http://www.peterbe.com/plog/uniqifiers-benchmark
+            return [x for x in seq if (x not in d) and not d.__setitem__(x, 0)]
+        else:
+            for x in seq:
+                d[x] = 0
+            return d.keys()
+    except TypeError:
+        # Have an unhashable object, so use slow algorithm.
+        result = []
+        app = result.append
+        for x in seq:
+            if x not in result:
+                app(x)
+        return result
+
+# Alias to noun form for backward compatibility.
+unique = uniquify
+
+
+def reverse_dict(d):
+    """Reverse a dictionary so the items become the keys and vice-versa.
+
+    Note: The results will be arbitrary if the items are not unique.
+
+    >>> d = reverse_dict({'a': 1, 'b': 2})
+    >>> d_items = d.items()
+    >>> d_items.sort()
+    >>> d_items
+    [(1, 'a'), (2, 'b')]
+
+    """
+    result = {}
+    for key, value in d.items():
+        result[value] = key
+    return result
+
+    
+def lsb(x, n):
+    """Return the n least significant bits of x.
+
+    >>> lsb(13, 3)
+    5
+
+    """
+    return x & ((2 ** n) - 1)
+
+
+def gray_encode(i):
+    """Gray encode the given integer."""
+
+    return i ^ (i >> 1)
+
+
+def random_vec(bits, max_value=None):
+    """Generate a random binary vector of length bits and given max value."""
+
+    vector = ""
+    for _ in range(int(bits / 10) + 1):
+        i = int((2**10) * random.random())
+        vector += int2bin(i, 10)
+
+    if max_value and (max_value < 2 ** bits - 1):
+        vector = int2bin((int(vector, 2) / (2 ** bits - 1)) * max_value, bits)
+    
+    return vector[0:bits]
+
+
+def binary_range(bits):
+    """Return a list of all possible binary numbers in order with width=bits. 
+    
+    It would be nice to extend it to match the
+    functionality of python's range() built-in function.
+    
+    """
+    l = []
+    v = ['0'] * bits
+
+    toggle = [1] + [0] * bits
+    
+    while toggle[bits] != 1:
+        v_copy = v[:]
+        v_copy.reverse()
+        l.append(''.join(v_copy))
+        
+        toggle = [1] + [0]*bits
+        i = 0
+        while i < bits and toggle[i] == 1:
+            if toggle[i]:
+                if v[i] == '0':
+                    v[i] = '1'
+                    toggle[i+1] = 0
+                else:
+                    v[i] = '0'
+                    toggle[i+1] = 1
+            i += 1
+    return l
+
+
+def float_range(start, stop=None, step=None):
+    """Return a list containing an arithmetic progression of floats.
+
+    Return a list of floats between 0.0 (or start) and stop with an
+    increment of step. 
+
+    This is in functionality to python's range() built-in function 
+    but can accept float increments.
+
+    As with range(), stop is omitted from the list.
+
+    """
+    if stop is None:
+        stop = float(start)
+        start = 0.0
+
+    if step is None:
+        step = 1.0
+
+    cur = float(start)
+    l = []
+    while cur < stop:
+        l.append(cur)
+        cur += step
+
+    return l
+
+
+def find_common_fixes(s1, s2):
+    """Find common (prefix, suffix) of two strings.
+
+    >>> find_common_fixes('abc', 'def')
+    ('', '')
+
+    >>> find_common_fixes('abcelephantdef', 'abccowdef')
+    ('abc', 'def')
+
+    >>> find_common_fixes('abcelephantdef', 'abccow')
+    ('abc', '')
+
+    >>> find_common_fixes('elephantdef', 'abccowdef')
+    ('', 'def')
+
+    """
+    prefix = []
+    suffix = []
+
+    i = 0
+    common_len = min(len(s1), len(s2))
+    while i < common_len:
+        if s1[i] != s2[i]:
+            break
+
+        prefix.append(s1[i])
+        i += 1
+
+    i = 1
+    while i < (common_len + 1):
+        if s1[-i] != s2[-i]:
+            break
+        
+        suffix.append(s1[-i])
+        i += 1
+
+    suffix.reverse()
+
+    prefix = ''.join(prefix)
+    suffix = ''.join(suffix)
+        
+    return (prefix, suffix)
+
+
+def is_rotated(seq1, seq2):
+    """Return true if the first sequence is a rotation of the second sequence.
+
+    >>> seq1 = ['A', 'B', 'C', 'D']
+    >>> seq2 = ['C', 'D', 'A', 'B']
+    >>> int(is_rotated(seq1, seq2))
+    1
+
+    >>> seq2 = ['C', 'D', 'B', 'A']
+    >>> int(is_rotated(seq1, seq2))
+    0
+
+    >>> seq1 = ['A', 'B', 'C', 'A']
+    >>> seq2 = ['A', 'A', 'B', 'C']
+    >>> int(is_rotated(seq1, seq2))
+    1
+
+    >>> seq2 = ['A', 'B', 'C', 'A']
+    >>> int(is_rotated(seq1, seq2))
+    1
+
+    >>> seq2 = ['A', 'A', 'C', 'B']
+    >>> int(is_rotated(seq1, seq2))
+    0
+
+    """
+    # Do a sanity check.
+    if len(seq1) != len(seq2):
+        return False
+    # Look for occurrences of second sequence head item in first sequence.
+    start_indexes = []
+    head_item = seq2[0]
+    for index1 in range(len(seq1)):
+        if seq1[index1] == head_item:
+            start_indexes.append(index1)
+    # Check that wrapped sequence matches.
+    double_seq1 = seq1 + seq1
+    for index1 in start_indexes:
+        if double_seq1[index1:index1+len(seq1)] == seq2:
+            return True
+    return False
+
+def getmodule(obj):
+    """Return the module that contains the object definition of obj.
+
+    Note: Use inspect.getmodule instead.
+
+    Arguments:
+    obj -- python obj, generally a class or a function
+
+    Examples:
+    
+    A function:
+    >>> module = getmodule(random.choice)
+    >>> module.__name__
+    'random'
+    >>> module is random
+    1
+
+    A class:
+    >>> module = getmodule(random.Random)
+    >>> module.__name__
+    'random'
+    >>> module is random
+    1
+
+    A class inheriting from a class in another module:
+    (note: The inheriting class must define at least one function.)
+    >>> class MyRandom(random.Random):
+    ...     def play(self):
+    ...         pass
+    >>> module = getmodule(MyRandom)
+    >>> if __name__ == '__main__':
+    ...     name = 'rad_util'
+    ... else:
+    ...     name = module.__name__
+    >>> name
+    'rad_util'
+    >>> module is sys.modules[__name__]
+    1
+
+    Discussion:
+    This approach is slightly hackish, and won't work in various situations.
+    However, this was the approach recommended by GvR, so it's as good as
+    you'll get.
+
+    See GvR's post in this thread:
+    http://groups.google.com.au/group/comp.lang.python/browse_thread/thread/966a7bdee07e3b34/c3cab3f41ea84236?lnk=st&q=python+determine+class+module&rnum=4&hl=en#c3cab3f41ea84236
+    
+    """
+    if hasattr(obj, 'func_globals'):
+        func = obj
+    else:
+        # Handle classes.
+        func = None
+        for item in obj.__dict__.values():
+            if hasattr(item, 'func_globals'):
+                func = item
+                break
+        if func is None:
+            raise ValueError("No functions attached to object: %r" % obj)
+    module_name = func.func_globals['__name__']
+    # Get module.
+    module = sys.modules[module_name]
+    return module
+
+
+def round_grid(value, grid, mode=0):
+    """Round off the given value to the given grid size.
+
+    Arguments:
+    value -- value to be roudne
+    grid -- result must be a multiple of this
+    mode -- 0 nearest, 1 up, -1 down
+
+    Examples:
+    
+    >>> round_grid(7.5, 5)
+    10
+
+    >>> round_grid(7.5, 5, mode=-1)
+    5
+
+    >>> round_grid(7.3, 5, mode=1)
+    10
+
+    >>> round_grid(7.3, 5.0, mode=1)
+    10.0
+
+    """
+    off_grid = value % grid
+    if mode == 0:
+        add_one = int(off_grid >= (grid / 2.0))
+    elif mode == 1 and off_grid:
+        add_one = 1
+    elif mode == -1 and off_grid:
+        add_one = 0
+    result = ((int(value / grid) + add_one) * grid)
+    return result
+
+
+def get_args(argv):
+    """Store command-line args in a dictionary.
+    
+    -, -- prefixes are removed
+    Items not prefixed with - or -- are stored as a list, indexed by 'args'
+
+    For options that take a value use --option=value
+
+    Consider using optparse or getopt (in Python standard library) instead.
+
+    """
+    d = {}
+    args = []
+    
+    for arg in argv:
+            
+        if arg.startswith('-'):
+            parts = re.sub(r'^-+', '', arg).split('=')
+            if len(parts) == 2:
+                d[parts[0]] = parts[1]
+            else:
+                d[parts[0]] = None
+        else:
+            args.append(arg)
+
+    d['args'] = args
+    
+    return d
+
+
+if __name__ == '__main__':
+    import doctest
+    doctest.testmod(sys.modules['__main__'])
+
@@ -0,0 +1,392 @@
+# topsort - dependency (topological) sorting and cycle finding functions
+# Copyright (C) 2007 RADLogic
+# 
+# This library is free software; you can redistribute it and/or
+# modify it under the terms of the GNU Lesser General Public
+# License as published by the Free Software Foundation; 
+# version 2.1 of the License.
+# 
+# This library is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+# Lesser General Public License for more details.
+#
+# See http://www.fsf.org/licensing/licenses/lgpl.txt for full license text.
+"""Provide toplogical sorting (i.e. dependency sorting) functions.
+
+The topsort function is based on code posted on Usenet by Tim Peters.
+
+Modifications:
+- added doctests
+- changed some bits to use current Python idioms
+  (listcomp instead of filter, +=/-=, inherit from Exception)
+- added a topsort_levels version that ports items in each dependency level
+  into a sub-list
+- added find_cycles to aid in cycle debugging
+
+Run this module directly to run the doctests (unittests).
+Make sure they all pass before checking in any modifications.
+
+Requires Python >= 2.2
+(For Python 2.2 also requires separate sets.py module)
+
+This requires the rad_util.py module.
+
+"""
+
+# Provide support for Python 2.2*
+from __future__ import generators
+
+__version__ = '$Revision: 0.9 $'
+__date__ = '$Date: 2007/03/27 04:15:26 $'
+__credits__ = '''Tim Peters -- original topsort code
+Tim Wegener -- doctesting, updating to current idioms, topsort_levels,
+               find_cycles
+'''
+
+# Make Python 2.3 sets look like Python 2.4 sets.
+try:
+    set
+except NameError:
+    from sets import Set as set
+
+from rad_util import is_rotated
+
+
+class CycleError(Exception):
+    """Cycle Error"""
+    pass
+
+
+def topsort(pairlist):
+    """Topologically sort a list of (parent, child) pairs.
+
+    Return a list of the elements in dependency order (parent to child order).
+
+    >>> print topsort( [(1,2), (3,4), (5,6), (1,3), (1,5), (1,6), (2,5)] ) 
+    [1, 2, 3, 5, 4, 6]
+
+    >>> print topsort( [(1,2), (1,3), (2,4), (3,4), (5,6), (4,5)] )
+    [1, 2, 3, 4, 5, 6]
+
+    >>> print topsort( [(1,2), (2,3), (3,2)] )
+    Traceback (most recent call last):
+    CycleError: ([1], {2: 1, 3: 1}, {2: [3], 3: [2]})
+    
+    """
+    num_parents = {}  # element -> # of predecessors 
+    children = {}  # element -> list of successors 
+    for parent, child in pairlist: 
+        # Make sure every element is a key in num_parents.
+        if not num_parents.has_key( parent ): 
+            num_parents[parent] = 0 
+        if not num_parents.has_key( child ): 
+            num_parents[child] = 0 
+
+        # Since child has a parent, increment child's num_parents count.
+        num_parents[child] += 1
+
+        # ... and parent gains a child.
+        children.setdefault(parent, []).append(child)
+
+    # Suck up everything without a parent.
+    answer = [x for x in num_parents.keys() if num_parents[x] == 0]
+
+    # For everything in answer, knock down the parent count on its children.
+    # Note that answer grows *in* the loop.
+    for parent in answer: 
+        del num_parents[parent]
+        if children.has_key( parent ): 
+            for child in children[parent]: 
+                num_parents[child] -= 1
+                if num_parents[child] == 0: 
+                    answer.append( child ) 
+            # Following "del" isn't needed; just makes 
+            # CycleError details easier to grasp.
+            del children[parent]
+
+    if num_parents: 
+        # Everything in num_parents has at least one child -> 
+        # there's a cycle.
+        raise CycleError(answer, num_parents, children)
+    return answer 
+
+def topsort_levels(pairlist):
+    """Topologically sort a list of (parent, child) pairs into depth levels.
+
+    This returns a generator. 
+    Turn this into a an iterator using the iter built-in function.
+    (if you iterate over the iterator, each element gets generated when
+    it is asked for, rather than generating the whole list up-front.)
+
+    Each generated element is a list of items at that dependency level.
+
+    >>> dependency_pairs = [(1,2), (3,4), (5,6), (1,3), (1,5), (1,6), (2,5)]
+    >>> for level in iter(topsort_levels( dependency_pairs )):
+    ...    print level
+    [1]
+    [2, 3]
+    [4, 5]
+    [6]
+
+    >>> dependency_pairs = [(1,2), (1,3), (2,4), (3,4), (5,6), (4,5)]
+    >>> for level in iter(topsort_levels( dependency_pairs )):
+    ...    print level
+    [1]
+    [2, 3]
+    [4]
+    [5]
+    [6]
+
+    >>> dependency_pairs = [(1,2), (2,3), (3,4), (4, 3)]
+    >>> try:
+    ...     for level in iter(topsort_levels( dependency_pairs )):
+    ...         print level
+    ... except CycleError, exc:
+    ...     print 'CycleError:', exc
+    [1]
+    [2]
+    CycleError: ({3: 1, 4: 1}, {3: [4], 4: [3]})
+
+
+    The cycle error should look like.
+    CycleError: ({3: 1, 4: 1}, {3: [4], 4: [3]})
+    # todo: Make the doctest more robust (i.e. handle arbitrary dict order).
+
+    """
+    num_parents = {}  # element -> # of predecessors 
+    children = {}  # element -> list of successors 
+    for parent, child in pairlist: 
+        # Make sure every element is a key in num_parents.
+        if not num_parents.has_key( parent ): 
+            num_parents[parent] = 0 
+        if not num_parents.has_key( child ): 
+            num_parents[child] = 0 
+
+        # Since child has a parent, increment child's num_parents count.
+        num_parents[child] += 1
+
+        # ... and parent gains a child.
+        children.setdefault(parent, []).append(child)
+
+    return topsort_levels_core(num_parents, children)
+
+def topsort_levels_core(num_parents, children):
+    """Topologically sort a bunch of interdependent items based on dependency.
+
+    This returns a generator.
+    Turn this into a an iterator using the iter built-in function.
+    (if you iterate over the iterator, each element gets generated when
+    it is asked for, rather than generating the whole list up-front.)
+
+    Each generated element is a list of items at that dependency level.
+
+    >>> list(topsort_levels_core(
+    ...          {1: 0, 2: 1, 3: 1, 4: 1, 5: 2, 6: 2},
+    ...          {1: [2, 3, 5, 6], 2: [5], 3: [4], 4: [], 5: [6]}))
+    [[1], [2, 3], [4, 5], [6]]
+
+    >>> list(topsort_levels_core(
+    ...          {1: 0, 2: 2, 3: 1},
+    ...          {1: [2], 2: [3], 3: [2]}))
+    Traceback (most recent call last):
+    CycleError: ({2: 1, 3: 1}, {2: [3], 3: [2]})
+
+    This function has a more complicated interface than topsort_levels,
+    but is useful if the data is easier to generate in this form.
+
+    Arguments:
+    num_parents -- key: item, value: number of parents (predecessors)
+    children -- key: item, value: list of children (successors)
+
+    """
+    while 1:
+        # Suck up everything without a predecessor.
+        level_parents = [x for x in num_parents.keys() if num_parents[x] == 0]
+
+        if not level_parents:
+            break
+
+        # Offer the next generated item,
+        # which is a list of the items at this dependency level.
+        yield level_parents
+
+        # For everything item in this level,
+        # decrement the parent count,
+        # since we have accounted for its parent.
+        for level_parent in level_parents:
+
+            del num_parents[level_parent]
+
+            if children.has_key(level_parent):
+                for level_parent_child in children[level_parent]:
+                    num_parents[level_parent_child] -= 1
+                del children[level_parent]
+        
+    if num_parents: 
+        # Everything in num_parents has at least one child -> 
+        # there's a cycle.
+        raise CycleError(num_parents, children)
+    else:
+        # This is the end of the generator.
+        raise StopIteration
+
+
+def find_cycles(parent_children):
+    """Yield cycles. Each result is a list of items comprising a cycle.
+
+    Use a 'stack' based approach to find all the cycles.
+    This is a generator, so yields each cycle as it finds it.
+
+    It is implicit that the last item in each cycle list is a parent of the
+    first item (thereby forming a cycle).
+
+    Arguments:
+    parent_children -- parent -> collection of children
+
+    Simplest cycle:
+    >>> cycles = list(find_cycles({'A': ['B'], 'B': ['A']}))
+    >>> len(cycles)
+    1
+    >>> cycle = cycles[0]
+    >>> cycle.sort()
+    >>> print cycle
+    ['A', 'B']
+
+    Simplest cycle with extra baggage at the start and the end:
+    >>> cycles = list(find_cycles(parent_children={'A': ['B'],
+    ...                                            'B': ['C'],
+    ...                                            'C': ['B', 'D'],
+    ...                                            'D': [],
+    ...                                            }))
+    >>> len(cycles)
+    1
+    >>> cycle = cycles[0]
+    >>> cycle.sort()
+    >>> print cycle
+    ['B', 'C']
+
+    Double cycle:
+    >>> cycles = list(find_cycles(parent_children={'A': ['B'],
+    ...                                            'B': ['C1', 'C2'],
+    ...                                            'C1': ['D1'],
+    ...                                            'D1': ['E1'],
+    ...                                            'E1': ['D1'],
+    ...                                            'C2': ['D2'],
+    ...                                            'D2': ['E2'],
+    ...                                            'E2': ['D2'],
+    ...                                            }))
+    >>> len(cycles)
+    2
+    >>> for cycle in cycles:
+    ...     cycle.sort()
+    >>> cycles.sort()
+    >>> cycle1 = cycles[0]
+    >>> cycle1.sort()
+    >>> print cycle1
+    ['D1', 'E1']
+    >>> cycle2 = cycles[1]
+    >>> cycle2.sort()
+    >>> print cycle2
+    ['D2', 'E2']
+
+    Simple cycle with children not specified for one item:
+    # todo: Should this barf instead?
+    >>> cycles = list(find_cycles(parent_children={'A': ['B'],
+    ...                                            'B': ['A'],
+    ...                                            'C': ['D']}))
+    >>> len(cycles)
+    1
+    >>> cycle = cycles[0]
+    >>> cycle.sort()
+    >>> print cycle
+    ['A', 'B']
+
+    Diamond cycle
+    >>> cycles = list(find_cycles(parent_children={'A': ['B1', 'B2'],
+    ...                                            'B1': ['C'],
+    ...                                            'B2': ['C'],
+    ...                                            'C': ['A', 'B1']}))
+    >>> len(cycles)
+    3
+    >>> sorted_cycles = []
+    >>> for cycle in cycles:
+    ...     cycle = list(cycle)
+    ...     cycle.sort()
+    ...     sorted_cycles.append(cycle)
+    >>> sorted_cycles.sort()
+    >>> for cycle in sorted_cycles:
+    ...     print cycle
+    ['A', 'B1', 'C']
+    ['A', 'B2', 'C']
+    ['B1', 'C']
+
+    Hairy case (order can matter if something is wrong):
+    (Note order of B and C in the list.)
+    >>> cycles = list(find_cycles(parent_children={
+    ...                                           'TD': ['DD'],
+    ...                                           'TC': ['DC'],
+    ...                                           'DC': ['DQ'],
+    ...                                           'C': ['DQ'],
+    ...                                           'DQ': ['IA', 'TO'],
+    ...                                           'IA': ['A'],
+    ...                                           'A': ['B', 'C'],
+    ...                                           }))
+    >>> len(cycles)
+    1
+    >>> cycle = cycles[0]
+    >>> cycle.sort()
+    >>> print cycle
+    ['A', 'C', 'DQ', 'IA']
+
+    """
+    cycles = []
+    visited_nodes = set()
+
+    for parent in parent_children:
+        if parent in visited_nodes:
+            # This node is part of a path that has already been traversed.
+            continue
+
+        paths = [[parent]]
+        while paths:
+            path = paths.pop()
+
+            parent = path[-1]
+            
+            try:
+                children = parent_children[parent]
+            except KeyError:
+                continue
+
+            for child in children:
+                # Keeping a set of the path nodes, for O(1) lookups at the
+                # expense of more memory and complexity, actually makes speed
+                # worse. (Due to construction of sets.)
+                # This is O(N).
+                if child in path:
+                    # This is a cycle.
+                    cycle = path[path.index(child):]
+                    # Check that this is not a dup cycle.
+                    is_dup = False
+                    for other_cycle in cycles:
+                        if is_rotated(other_cycle, cycle):
+                            is_dup = True
+                            break
+                    if not is_dup:
+                        cycles.append(cycle)
+                        yield cycle
+                else:
+                    # Push this new path onto the 'stack'.
+                    # This is probably the most expensive part of the algorithm
+                    # (a list copy).
+                    paths.append(path + [child])
+                    # Mark the node as visited.
+                    visited_nodes.add(child)
+
+
+if __name__ == '__main__':
+    # Run the doctest tests.
+    import sys
+    import doctest
+    doctest.testmod(sys.modules['__main__'])
@@ -0,0 +1,487 @@
+## -*- Mode: python; py-indent-offset: 4; indent-tabs-mode: nil; coding: utf-8; -*-
+import types
+import re
+import os
+import subprocess
+import shutil
+import sys
+
+import Task
+import Options
+import Configure
+import TaskGen
+import Logs
+import Build
+import Utils
+
+from waflib.Errors import WafError
+
+## https://launchpad.net/pybindgen/
+REQUIRED_PYBINDGEN_VERSION = (0, 15, 0, 795)
+REQUIRED_PYGCCXML_VERSION = (0, 9, 5)
+
+
+from TaskGen import feature, after
+import Task
+
+
+
+def add_to_python_path(path):
+    if os.environ.get('PYTHONPATH', ''):
+        os.environ['PYTHONPATH'] = path + os.pathsep + os.environ.get('PYTHONPATH')
+    else:
+        os.environ['PYTHONPATH'] = path
+
+def set_pybindgen_pythonpath(env):
+    if env['WITH_PYBINDGEN']:
+        add_to_python_path(env['WITH_PYBINDGEN'])
+
+
+def options(opt):
+    opt.tool_options('python', ["waf-tools"])
+    opt.add_option('--disable-python',
+                   help=("Don't build Python bindings."),
+                   action="store_true", default=False,
+                   dest='python_disable')
+    opt.add_option('--apiscan',
+                   help=("Rescan the API for the indicated module(s), for Python bindings.  "
+                         "Needs working GCCXML / pygccxml environment.  "
+                         "The metamodule 'all' expands to all available ns-3 modules."),
+                   default=None, dest='apiscan', metavar="MODULE[,MODULE...]")
+    opt.add_option('--with-pybindgen',
+                   help=('Path to an existing pybindgen source tree to use.'),
+                   default=None,
+                   dest='with_pybindgen', type="string")
+    opt.add_option('--with-python',
+                   help=('Path to the Python interpreter to use.'),
+                   default=None, dest='with_python', type="string")
+
+
+def configure(conf):
+    conf.env['ENABLE_PYTHON_BINDINGS'] = False
+    if Options.options.python_disable:
+        conf.report_optional_feature("python", "Python Bindings", False,
+                                     "disabled by user request")
+        return
+    # Disable python in static builds (bug #1253)
+    if ((conf.env['ENABLE_STATIC_NS3']) or \
+      (conf.env['ENABLE_SHARED_AND_STATIC_NS3'])):
+        conf.report_optional_feature("python", "Python Bindings", False,
+                                     "bindings incompatible with static build")
+        return
+
+    enabled_modules = list(conf.env['NS3_ENABLED_MODULES'])
+    enabled_modules.sort()
+    available_modules = list(conf.env['NS3_MODULES'])
+    available_modules.sort()
+    all_modules_enabled = (enabled_modules == available_modules)
+
+    conf.check_tool('misc', tooldir=['waf-tools'])
+
+    if sys.platform == 'cygwin':
+        conf.report_optional_feature("python", "Python Bindings", False,
+                                     "unsupported platform 'cygwin'")
+        Logs.warn("Python is not supported in CygWin environment.  Try MingW instead.")
+        return
+
+
+    ## Check for Python
+
+    if Options.options.with_python is not None:
+        conf.env.PYTHON = Options.options.with_python
+
+    try:
+        conf.check_tool('python', ["waf-tools"])
+        conf.check_python_version((2,3))
+        conf.check_python_headers()
+    except Configure.ConfigurationError, ex:
+        conf.report_optional_feature("python", "Python Bindings", False, str(ex))
+        return
+
+    # stupid Mac OSX Python wants to build extensions as "universal
+    # binaries", i386, x86_64, and ppc, but this way the type
+    # __uint128_t is not available.  We need to disable the multiarch
+    # crap by removing the -arch parameters.
+    for flags_var in ["CFLAGS_PYEXT", "CFLAGS_PYEMBED", "CXXFLAGS_PYEMBED",
+                      "CXXFLAGS_PYEXT", "LINKFLAGS_PYEMBED", "LINKFLAGS_PYEXT"]:
+        flags = conf.env[flags_var]
+        i = 0
+        while i < len(flags):
+            if flags[i] == '-arch':
+                del flags[i]
+                del flags[i]
+                continue
+            i += 1
+        conf.env[flags_var] = flags
+
+    # -fvisibility=hidden optimization
+    if (conf.env['CXX_NAME'] == 'gcc' and [int(x) for x in conf.env['CC_VERSION']] >= [4,0,0]
+        and conf.check_compilation_flag('-fvisibility=hidden')):
+        conf.env.append_value('CXXFLAGS_PYEXT', '-fvisibility=hidden')
+        conf.env.append_value('CCFLAGS_PYEXT', '-fvisibility=hidden')
+
+    # Check for the location of pybindgen
+    if Options.options.with_pybindgen is not None:
+        if os.path.isdir(Options.options.with_pybindgen):
+            conf.msg("Checking for pybindgen location", ("%s (given)" % Options.options.with_pybindgen))
+            conf.env['WITH_PYBINDGEN'] = os.path.abspath(Options.options.with_pybindgen)
+    else:
+        # ns-3-dev uses ../pybindgen, while ns-3 releases use ../REQUIRED_PYBINDGEN_VERSION
+        pybindgen_dir = os.path.join('..', "pybindgen")
+        pybindgen_release_str = "pybindgen-" + '.'.join([str(x) for x in REQUIRED_PYBINDGEN_VERSION])
+        pybindgen_release_dir = os.path.join('..', pybindgen_release_str)
+        if os.path.isdir(pybindgen_dir):
+            conf.msg("Checking for pybindgen location", ("%s (guessed)" % pybindgen_dir))
+            conf.env['WITH_PYBINDGEN'] = os.path.abspath(pybindgen_dir)
+        elif os.path.isdir(pybindgen_release_dir):
+            conf.msg("Checking for pybindgen location", ("%s (guessed)" % pybindgen_release_dir))
+            conf.env['WITH_PYBINDGEN'] = os.path.abspath(pybindgen_release_dir)
+        del pybindgen_dir
+        del pybindgen_release_dir
+    if not conf.env['WITH_PYBINDGEN']:
+        conf.msg("Checking for pybindgen location", False)
+
+    # Check for pybindgen
+
+    set_pybindgen_pythonpath(conf.env)
+
+    try:
+        conf.check_python_module('pybindgen')
+    except Configure.ConfigurationError:
+        Logs.warn("pybindgen missing => no python bindings")
+        conf.report_optional_feature("python", "Python Bindings", False,
+                                     "PyBindGen missing")
+        return
+    else:
+        out = subprocess.Popen([conf.env['PYTHON'][0], "-c",
+                                "import pybindgen.version; "
+                                "print '.'.join([str(x) for x in pybindgen.version.__version__])"],
+                                stdout=subprocess.PIPE).communicate()[0]
+        pybindgen_version_str = out.strip()
+        pybindgen_version = tuple([int(x) for x in pybindgen_version_str.split('.')])
+        conf.msg('Checking for pybindgen version', pybindgen_version_str)
+        if not (pybindgen_version == REQUIRED_PYBINDGEN_VERSION):
+            Logs.warn("pybindgen (found %s), (need %s)" %
+                    (pybindgen_version_str,
+                     '.'.join([str(x) for x in REQUIRED_PYBINDGEN_VERSION])))
+            conf.report_optional_feature("python", "Python Bindings", False,
+                                         "PyBindGen version not correct and newer version could not be retrieved")
+            return
+
+
+    def test(t1, t2):
+        test_program = '''
+#include <stdint.h>
+#include <vector>
+
+int main ()
+{
+   std::vector< %(type1)s > t = std::vector< %(type2)s > ();
+   return 0;
+}
+''' % dict(type1=t1, type2=t2)
+
+        try:
+            ret = conf.run_c_code(code=test_program,
+                                  env=conf.env.copy(), compile_filename='test.cc',
+                                  features='cxx cprogram', execute=False)
+        except Configure.ConfigurationError:
+            ret = 1
+        conf.msg('Checking for types %s and %s equivalence' % (t1, t2), (ret and 'no' or 'yes'))
+        return not ret
+
+    uint64_is_long = test("uint64_t", "unsigned long")
+    uint64_is_long_long = test("uint64_t", "unsigned long long")
+
+    if uint64_is_long:
+        conf.env['PYTHON_BINDINGS_APIDEFS'] = 'gcc-LP64'
+    elif uint64_is_long_long:
+        conf.env['PYTHON_BINDINGS_APIDEFS'] = 'gcc-ILP32'
+    else:
+        conf.env['PYTHON_BINDINGS_APIDEFS'] = None
+    if conf.env['PYTHON_BINDINGS_APIDEFS'] is None:
+        msg = 'none available'
+    else:
+        msg = conf.env['PYTHON_BINDINGS_APIDEFS']
+
+    conf.msg('Checking for the apidefs that can be used for Python bindings', msg)
+
+    if conf.env['PYTHON_BINDINGS_APIDEFS'] is None:
+        conf.report_optional_feature("python", "Python Bindings", False,
+                                     "No apidefs are available that can be used in this system")
+        return
+
+
+    ## If all has gone well, we finally enable the Python bindings
+    conf.env['ENABLE_PYTHON_BINDINGS'] = True
+    conf.report_optional_feature("python", "Python Bindings", True, None)
+
+
+    # check cxxabi stuff (which Mac OS X Lion breaks)
+    fragment = r"""
+# include <cxxabi.h>
+int main ()
+{
+   const abi::__si_class_type_info *_typeinfo  __attribute__((unused)) = NULL;
+   return 0;
+}
+"""
+    gcc_rtti_abi = conf.check_nonfatal(fragment=fragment, msg="Checking for internal GCC cxxabi",
+                                       okmsg="complete", errmsg='incomplete',
+                                       mandatory=False)
+    conf.env["GCC_RTTI_ABI_COMPLETE"] = str(bool(gcc_rtti_abi))
+
+
+
+    ## Check for pygccxml
+    try:
+        conf.check_python_module('pygccxml')
+    except Configure.ConfigurationError:
+        conf.report_optional_feature("pygccxml", "Python API Scanning Support", False,
+                                     "Missing 'pygccxml' Python module")
+        return
+
+    out = subprocess.Popen([conf.env['PYTHON'][0], "-c",
+                            "import pygccxml; print pygccxml.__version__"],
+                            stdout=subprocess.PIPE).communicate()[0]
+    pygccxml_version_str = out.strip()
+    pygccxml_version = tuple([int(x) for x in pygccxml_version_str.split('.')])
+    conf.msg('Checking for pygccxml version', pygccxml_version_str)
+    if not (pygccxml_version >= REQUIRED_PYGCCXML_VERSION):
+        Logs.warn("pygccxml (found %s) is too old (need %s) => "
+                "automatic scanning of API definitions will not be possible" %
+                (pygccxml_version_str,
+                 '.'.join([str(x) for x in REQUIRED_PYGCCXML_VERSION])))
+        conf.report_optional_feature("pygccxml", "Python API Scanning Support", False,
+                                     "pygccxml too old")
+        return
+    
+
+    ## Check gccxml version
+    try:
+        gccxml = conf.find_program('gccxml', var='GCCXML')
+    except WafError:
+        gccxml = None
+    if not gccxml:
+        Logs.warn("gccxml missing; automatic scanning of API definitions will not be possible")
+        conf.report_optional_feature("pygccxml", "Python API Scanning Support", False,
+                                     "gccxml missing")
+        return
+
+    gccxml_version_line = os.popen(gccxml + " --version").readline().strip()
+    m = re.match( "^GCC-XML version (\d\.\d(\.\d)?)$", gccxml_version_line)
+    gccxml_version = m.group(1)
+    gccxml_version_ok = ([int(s) for s in gccxml_version.split('.')] >= [0, 9])
+    conf.msg('Checking for gccxml version', gccxml_version)
+    if not gccxml_version_ok:
+        Logs.warn("gccxml too old, need version >= 0.9; automatic scanning of API definitions will not be possible")
+        conf.report_optional_feature("pygccxml", "Python API Scanning Support", False,
+                                     "gccxml too old")
+        return
+
+    ## If we reached
+    conf.env['ENABLE_PYTHON_SCANNING'] = True
+    conf.report_optional_feature("pygccxml", "Python API Scanning Support", True, None)
+
+# ---------------------
+
+def get_headers_map(bld):
+    headers_map = {} # header => module
+    for ns3headers in bld.all_task_gen:
+        if 'ns3header' in getattr(ns3headers, "features", []):
+            if ns3headers.module.endswith('-test'):
+                continue
+            for h in ns3headers.to_list(ns3headers.headers):
+                headers_map[os.path.basename(h)] = ns3headers.module
+    return headers_map
+
+def get_module_path(bld, module):
+    for ns3headers in bld.all_task_gen:
+        if 'ns3header' in getattr(ns3headers, "features", []):
+            if ns3headers.module == module:
+                break
+    else:
+        raise ValueError("Module %r not found" % module)
+    return ns3headers.path.abspath()
+
+class apiscan_task(Task.TaskBase):
+    """Uses gccxml to scan the file 'everything.h' and extract API definitions.
+    """
+    after = 'gen_ns3_module_header ns3header'
+    before = 'cc cxx command'
+    color = "BLUE"
+    def __init__(self, curdirnode, env, bld, target, cflags, module):
+        self.bld = bld
+        super(apiscan_task, self).__init__(generator=self)
+        self.curdirnode = curdirnode
+        self.env = env
+        self.target = target
+        self.cflags = cflags
+        self.module = module
+
+    def display(self):
+        return 'api-scan-%s\n' % (self.target,)
+
+    def run(self):
+        top_builddir = self.bld.bldnode.abspath()
+        module_path = get_module_path(self.bld, self.module)
+        headers_map = get_headers_map(self.bld)
+        scan_header = os.path.join(top_builddir, "ns3", "%s-module.h" % self.module)
+
+        if not os.path.exists(scan_header):
+            Logs.error("Cannot apiscan module %r: %s does not exist" % (self.module, scan_header))
+            return 0
+
+        argv = [
+            self.env['PYTHON'][0],
+            os.path.join(self.curdirnode.abspath(), 'ns3modulescan-modular.py'), # scanning script
+            top_builddir,
+            self.module,
+            repr(get_headers_map(self.bld)),
+            os.path.join(module_path, "bindings", 'modulegen__%s.py' % (self.target)), # output file
+            self.cflags,
+            ]
+        scan = subprocess.Popen(argv, stdin=subprocess.PIPE)
+        retval = scan.wait()
+        return retval
+
+
+def get_modules_and_headers(bld):
+    """
+    Gets a dict of
+       module_name => ([module_dep1, module_dep2, ...], [module_header1, module_header2, ...])
+    tuples, one for each module.
+    """
+
+    retval = {}
+    for module in bld.all_task_gen:
+        if not module.name.startswith('ns3-'):
+            continue
+        if module.name.endswith('-test'):
+            continue
+        module_name = module.name[4:] # strip the ns3- prefix
+        ## find the headers object for this module
+        headers = []
+        for ns3headers in bld.all_task_gen:
+            if 'ns3header' not in getattr(ns3headers, "features", []):
+                continue
+            if ns3headers.module != module_name:
+                continue
+            for source in ns3headers.to_list(ns3headers.headers):
+                headers.append(os.path.basename(source))
+        retval[module_name] = (list(module.module_deps), headers)
+    return retval
+
+
+
+
+class python_scan_task_collector(Task.TaskBase):
+    """Tasks that waits for the python-scan-* tasks to complete and then signals WAF to exit
+    """
+    after = 'apiscan'
+    before = 'cc cxx'
+    color = "BLUE"
+    def __init__(self, curdirnode, env, bld):
+        self.bld = bld
+        super(python_scan_task_collector, self).__init__(generator=self)
+        self.curdirnode = curdirnode
+        self.env = env
+
+    def display(self):
+        return 'python-scan-collector\n'
+
+    def run(self):
+        # signal stop (we generated files into the source dir and WAF
+        # can't cope with it, so we have to force the user to restart
+        # WAF)
+        self.bld.producer.stop = 1
+        self.bld.producer.free_task_pool()
+        return 0
+
+
+
+class gen_ns3_compat_pymod_task(Task.Task):
+    """Generates a 'ns3.py' compatibility module."""
+    before = 'cc cxx'
+    color = 'BLUE'
+    
+    def run(self):
+        assert len(self.outputs) == 1
+        outfile = file(self.outputs[0].abspath(), "w")
+        print >> outfile, "import warnings"
+        print >> outfile, 'warnings.warn("the ns3 module is a compatibility layer '\
+            'and should not be used in newly written code", DeprecationWarning, stacklevel=2)'
+        print >> outfile
+        for module in self.bld.env['PYTHON_MODULES_BUILT']:
+            print >> outfile, "from ns.%s import *" % (module.replace('-', '_'))
+        outfile.close()
+        return 0
+
+
+
+def build(bld):
+    if Options.options.python_disable:
+        return
+
+    env = bld.env
+    curdir = bld.path.abspath()
+
+    set_pybindgen_pythonpath(env)
+
+    if Options.options.apiscan:
+        if not env['ENABLE_PYTHON_SCANNING']:
+            raise WafError("Cannot re-scan python bindings: (py)gccxml not available")
+        scan_targets = []
+        if sys.platform == 'cygwin':
+            scan_targets.append(('gcc_cygwin', ''))
+        else:
+            import struct
+            if struct.calcsize('I') == 4 and struct.calcsize('L') == 8 and struct.calcsize('P') == 8:
+                scan_targets.extend([('gcc_ILP32', '-m32'), ('gcc_LP64', '-m64')])
+            elif struct.calcsize('I') == 4 and struct.calcsize('L') == 4 and struct.calcsize('P') == 4:
+                scan_targets.append(('gcc_ILP32', ''))
+            else:
+                raise WafError("Cannot scan python bindings for unsupported data model")
+
+        test_module_path = bld.path.find_dir("../../src/test")
+        if Options.options.apiscan == 'all':
+            scan_modules = []
+            for mod in bld.all_task_gen:
+                if not mod.name.startswith('ns3-'):
+                    continue
+                if mod.path.is_child_of(test_module_path):
+                    continue
+                if mod.name.endswith('-test'):
+                    continue
+                bindings_enabled = (mod.name in env.MODULAR_BINDINGS_MODULES)
+                #print mod.name, bindings_enabled
+                if bindings_enabled:
+                    scan_modules.append(mod.name.split('ns3-')[1])
+        else:
+            scan_modules = Options.options.apiscan.split(',')
+        print "Modules to scan: ", scan_modules
+        for target, cflags in scan_targets:
+            group = bld.get_group(bld.current_group)
+            for module in scan_modules:
+                group.append(apiscan_task(bld.path, env, bld, target, cflags, module))
+        group.append(python_scan_task_collector(bld.path, env, bld))
+        return
+
+
+    if env['ENABLE_PYTHON_BINDINGS']:
+        task = gen_ns3_compat_pymod_task(env=env.derive())
+        task.set_outputs(bld.path.find_or_declare("ns3.py"))
+        task.dep_vars = ['PYTHON_MODULES_BUILT']
+        task.bld = bld
+        grp = bld.get_group(bld.current_group)
+        grp.append(task)
+
+        bld.new_task_gen(features='copy',
+                         source="ns__init__.py",
+                         target='ns/__init__.py')
+        bld.install_as('${PYTHONDIR}/ns/__init__.py', 'ns__init__.py')
+
+
+    # note: the actual build commands for the python bindings are in
+    # src/wscript, not here.
+
@@ -1,9 +1,19 @@
 The Waf build system is used to build ns-3.  Waf is a Python-based
 build system (http://www.freehackers.org/~tnagy/waf.html)

+Note:  We've added a wiki page with more complete build instructions
+than the quick ones you find below:
+http://www.nsnam.org/wiki/index.php/Installation
+
 === Installing Waf ===

-The top-level ns-3 directory should contain a current waf script.
+The top-level ns-3 directory should contain a current waf script, so
+there is no need to have WAF installed in the system.  We are using
+some extensions to WAF, which can be found in the 'waf-tools'
+directory. The upstream location for these WAF extensions is:
+
+    https://code.launchpad.net/~gjc/waf/cmd
+

 === Building with Waf ===

@@ -13,29 +23,29 @@ To build ns-3 with waf type the commands from the top-level directory:

 To see valid configure options, type ./waf --help.  The most important
 option is -d <debug level>.  Valid debug levels (which are listed in
-waf --help) are: "debug" or "optimized".  It is
+waf --help) are: "debug" or "optimized", with debug being default.  It is
 also possible to change the flags used for compilation with (e.g.):
-CXXFLAGS="-O3" ./waf configure.
+CXXFLAGS="-O3" ./waf configure.  By default, ns-3 is built as debug code, 
+with examples and tests disabled, and with python bindings enabled.  

 [ Note:  Unlike some other build tools, to change the build target,
 the option must be supplied during the configure stage rather than
 the build stage (i.e., "./waf -d optimized" will not work; instead, do
 "./waf -d optimized configure; ./waf" ]

-The resulting binaries are placed in build/<debuglevel>/srcpath.
+The resulting executables and libraries are placed in build/.

 Other waf usages include:

- 1. ./waf check
-    Runs the unit tests
+ 1. ./waf configure --enable-examples --enable-tests
+    Turn on examples and tests.

- 2. ./waf --doxygen
+ 2. ./waf configure --disable-python
+    Disable python bindings.
+
+ 3. ./waf --doxygen
    Run doxygen to generate documentation

- 3. ./waf --lcov-report
-    Run code coverage analysis (assuming the project was configured
-with --enable-gcov)
-
 4. ./waf --run "program [args]"
    Run a ns3 program, given its target name, with the given
    arguments.  This takes care of automatically modifying the the
@@ -63,36 +73,35 @@ with --enable-gcov)
    It includes all files in the source directory, except some particular
    extensions that are blacklisted, such as back files (ending in ~).

-
 === Extending ns-3 ===

 To add new modules:
-  1. Create the module directory under src (or src/devices, or whatever);
+  1. Create the module directory under src;
  2. Add the source files to it;
  3. Add a 'wscript' describing it;
-  4. Add the module subdirectory name to the all_modules list in src/wscript.
+
+A convenience program to auto-generate the template of a new module can
+be found in src/create-module.py.

 A module's wscript file is basically a regular Waf script.  A ns-3
 module is created as a cpp/shlib object, like this:

 def build(bld):
-    obj = bld.create_obj('cpp', 'shlib')
+    module = bld.create_ns3_module('ns3-mymodule', ['core'])
+    module.source = [
+        'model/ns3-mymodule.cc',
+        'helper/ns3-mymodule-helper.cc',
+        ]

-    ## set module name; by convention it starts with ns3-
-    obj.name = 'ns3-mymodule'
-    obj.target = obj.name 
-
-    ## list dependencies to other modules
-    obj.uselib_local = ['ns3-core'] 
-
-    ## list source files (private or public header files excluded)
-    obj.source = [
-        'mymodule.cc',
-    ]
-
-    ## list module public header files
-    headers = bld.create_obj('ns3header')
+    headers = bld.new_task_gen(features=['ns3header'])
+    headers.module = 'ns3-mymodule'
    headers.source = [
-        'mymodule-header.h',
-    ]
+        'model/ns3-mymodule.h',
+        'helper/ns3-mymodule-helper.h',
+        ]
+
+    if bld.env.ENABLE_EXAMPLES:
+        bld.add_subdirs('examples')
+
+    # bld.ns3_python_bindings()

@@ -1,210 +1,2 @@
-       The Ns-3 Coding Style
-
-/*
- * Note:  This file is incomplete and will be converted to non-text (html,pdf)
- * formats at a future date
- */
-
-1) Code layout
-     -----------
-
-The code layout follows the GNU coding standard layout for C and extends
-it to C++. Do not use tabs for indentation. Indentation spacing is 2
-spaces as outlined below:
-
-void 
-Foo (void)
-{
-  if (test)
-    {
-      // do stuff here
-    }
-  else
-    {
-      // do other stuff here
-    }
-
-  for (int i = 0; i < 100; i++)
-    {
-      // do loop
-    }
-
-  while (test)
-    {
-      // do while
-    }
-
-  do
-    {
-      // do stuff
-    } while ();
-}
-
-The following is not recommended:
-
-if (test) statement
-
-if (test)
-  statement
-
-for (...) statement
-
-Each statement should be put on a separate line to increase readability.
-Short one-line comments can use the C++ comment style, that is, '//'
-but longer comments should use C-style comments:
-/*
- *
- *
- */
-
-
-2) Naming Patterns
-   ---------------
-
-2.1) Name encoding
-     -------------
-Function, Method, and Type names should follow the CamelCase convention:
-words are joined without spaces and are capitalized. For example,
-"my computer" is transformed into MyComputer. Do not use all capital 
-letters such as MAC or, PHY, but choose instead Mac or Phy. Do not use
-all capital letters, even for acronyms such as EDCA: use Edca instead.
-The goal of the CamelCase convention is to ensure that the words which
-make up a name can be separated by the eye: the initial Caps fills
-that role.
-
-Variable names should follow a slight variation on the base CamelCase
-convention: camelBack. For example, the variable "user name" would be
-named "userName". This variation on the basic naming pattern is used to
-allow a reader to distinguish a variable name from its type. For example,
-"UserName userName;" would be used to declare a variable named userName
-of type UserName.
-
-Global variables should be prefixed with a "g_" and member variables
-(including static member variables) should be prefixed with a "m_". The
-goal of that prefix is to give a reader a sense of where a variable of
-a given name is declared to allow the reader to locate the variable 
-declaration and infer the variable type from that declaration. For example
-you could declare in your class header my-class.h:
-
-class MyClass
-{
-  void MyMethod (int aVar);
-  int m_aVar;
-  static int m_anotherVar;
-};
-
-and implement in your class file my-class.cc:
-
-int MyClass::m_anotherVar = 10;
-static int g_aStaticVar = 100;
-int g_aGlobalVar = 1000;
-
-void
-MyClass::MyMethod (int aVar)
-{
-  m_aVar = aVar;
-}
-
-2.2) Choosing names
-
-Variable, function, method, and type names should be based on the
-english language. Furthermore, always try to choose descriptive
-names for them. Types are often english names such as: Packet, 
-Buffer, Mac, or Phy. Functions and Methods are often named
-based on verbs and adjectives: GetX, DoDispose, ClearArray, etc.
-
-A long descriptive name which requires a lot of typing is always
-better than a short name which is hard to decipher. Do not use
-abbreviations in names unless the abbreviation is really unambiguous
-and obvious to everyone. Do not use short inapropriate names such
-as foo, bar, or baz. The name of an item should always match its 
-purpose. As such, names such as tmp to identify a temporary
-variable or such as 'i' to identify a loop index are ok.
-
-3) File layout and code organization
-   ---------------------------------
-
-A class named MyClass should be declared in a header named my-class.h
-and implemented in a source file named my-class.cc. The goal of this
-naming pattern is to allow a reader to quickly navigate through
-the ns-3 codebase to locate the source file relevant to a specific
-type.
-
-Each my-class.h header should start with the following comments: the
-first line ensures that developers who use the emacs editor will be 
-able to indent your code correctly. The following lines ensure that
-your code is licensed under the GPL, that the copyright holders
-are properly identified (typically, you or your employer), and
-that the actual author of the code is identified. The latter is
-purely informational and we use it to try to track the most
-appropriate person to review a patch or fix a bug.
-
-/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
-/*
- * Copyright (c) YEAR COPYRIGHTHOLDER
- * 
- * 3-paragran GPL blurb
- *
- * Author: MyName <myemail@foo.com>
- */
-
-Below these C-style comments, always include the following which
-defines a set of header guards (MY_CLASS_H) used to avoid multiple
-header includes, which ensures that your code is included
-in the "ns3" namespace and which provides a set of doxygen comments
-for the public part of your class API. Detailed information
-on the set of tags available for doxygen documentation is described
-in the doxygen website: http://www.doxygen.org.
-
-#ifndef MY_CLASS_H
-#define MY_CLASS_H
-
-namespace n3 {
-
-/**
- * \brief short one-line description of the purpose of your class
- *
- * A longer description of the purpose of your class after a blank
- * empty line.
- */
-class MyClass
-{
-public:
- MyClass ();
- /**
-  * \param firstParam a short description of the purpose of this parameter
-  * \returns a short description of what is returned from this function.
-  *
-  * A detailed description of the purpose of the method.
-  */
- int DoFoo (int firstParam);
-private:
- void MyPrivateMethod (void);
- int m_myPrivateMemberVariable;
-};
-
-} // namespace ns3
-
-#endif /* MY_CLASS_H */
-
-The my-class.cc file is structured similarly:
-
-/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
-/*
- * Copyright (c) YEAR COPYRIGHTHOLDER
- * 
- * 3-paragran GPL blurb
- *
- * Author: MyName <myemail@foo.com>
- */
-#include "my-class.h"
-
-namespace ns3 {
-
-MyClass::MyClass ()
-{}
-
-...
-
-} // namespace ns3
-
+The project coding style document is maintained at:
+http://www.nsnam.org/developers/contributing-code/coding-style/
@@ -1,63 +1,7 @@
 Contributing to the ns-3 project
 --------------------------------

-ns-3 is an open source project backed by an NSF CISE CRI grant. 
-Although the NSF PIs have specific aims to fulfill, we want others to 
-contribute, and we'd like to have a broad community of users and 
-developers, with the goal of a self-sustaining project downstream. 
-The project is currently in a bootstrapping phase, but we welcome 
-ambitious developers who might want to help shape the early design.
-
-Despite the lack of a formal contribution process to the ns-3
-project, there are a number of steps which we expect every
-potential contributor to follow. These naturally stem from 
-the open-source roots of the project:
-
-  - first, you should subscribe to the ns-developers 
-    mailing-list (see http://www.nsnam.org/mailing_lists.html)
-
-  - then, you should send an email there stating your interest
-    in working on a specific part of the models and trying
-    to explain how you would like to implement it, what 
-    resources you have, etc.
-
-  - you should be prepared to work together with the other
-    potential contributors who want to work on the same models.
-
-  - you should be prepared to go through code reviews with the
-    ns-3 development team prior to integration. The goal of these
-    code reviews is to:
-      - ensure adherence to the coding style of the project
-        (see doc/codingstyle.html)
-      - ensure that the structure of your code has a certain 
-        coherence with regard to the rest of the ns-3 codebase
-      - improve the quality of the code: we strongly believe in
-        the old saying: "many eyes make all bugs shallow".
-      - increase code reuse by trying to generalize certain 
-        useful pieces of your code to make them available to
-        other models.
-
-  - you should be prepared to try to integrate as many tests
-    in the codebase as possible: we understand that writing
-    tests is not sexy and that not everyone is convinced that
-    they improve the code-writing poductivity which is why
-    we do not enforce strict rules about testing. However,
-    we expect model authors to answer basic questions about
-    how they plan to test and validate their models.
-
-  - you should be prepared to maintain your model once it is
-    integrated: while we consider every bug filed against the 
-    simulator as being a bug we must deal with and while we 
-    will try to fix as many bugs as humanly possible, we
-    also expect model authors to act as responsible maintainers
-    and be reactive to bug reports concerning their models.
-
-  - The project has decided upon GNU GPLv2 as the licensing structure. 
-    All simulation software in the ns-3 repositories will be GNU GPLv2 
-    or GNU GPLv2-compatible (with non-GPLv2 licensing reserved for
-    ports of pre-existing code under a different license, such as BSD).
-    You do not have to assign your copyright to the ns-3 project but
-    you must accept the terms of the GPLv2 and attest that your 
-    contributions can be licensed under those terms.  See the 
-    following link:
-    http://www.fsf.org/licensing/licenses/info/GPLv2.html
+ns-3 is a free, open source software project that welcomes contributions
+from users worldwide.  Please see the following web page for how to 
+contribute:  
+http://www.nsnam.org/developers/contributing-code/
@@ -0,0 +1,74 @@
+/**
+ * \mainpage ns-3 Documentation
+ *
+ * \section intro-sec Introduction
+ * <a href="http://www.nsnam.org/">ns-3</a> documentation is maintained using 
+ * <a href="http://www.doxygen.org">Doxygen</a>.
+ * Doxygen is typically used for 
+ * API documentation, and organizes such documentation across different
+ * modules.   This project uses Doxygen for building the definitive
+ * maintained API documentation.  Additional ns-3 project documentation 
+ * can be found at the
+ * <a href="http://www.nsnam.org/documentation/latest">project web site</a>.
+ *
+ * \section install-sec Building the Documentation
+ * 
+ * ns-3 requires Doxygen version 1.5.4 or greater to fully build all items,
+ * although earlier versions of Doxygen will mostly work.
+ * 
+ * Type "./waf --doxygen" or "./waf --doxygen-no-build" to build the 
+ *  documentation.  The doc/ directory contains
+ * configuration for Doxygen (doxygen.conf) and main.h.  The Doxygen 
+ * build process puts html files into the doc/html/ directory, and latex 
+ * filex into the doc/latex/ directory.
+ * 
+ * \section module-sec Module overview
+ *
+ * The ns-3 library is split across many modules organized under the 
+ * <b><a href="modules.html">Modules</a></b> tab.
+ *     - aodv
+ *     - applications
+ *     - bridge
+ *     - click
+ *     - config-store
+ *     - core
+ *     - csma
+ *     - csma-layout
+ *     - dsdv
+ *     - emu
+ *     - energy
+ *     - flow-monitor
+ *     - internet
+ *     - lte
+ *     - mesh
+ *     - mobility
+ *     - mpi
+ *     - netanim
+ *     - network
+ *     - nix-vector-routing
+ *     - ns3tcp
+ *     - ns3wifi
+ *     - olsr
+ *     - openflow
+ *     - point-to-point
+ *     - point-to-point-layout
+ *     - propagation
+ *     - spectrum
+ *     - stats
+ *     - tap-bridge
+ *     - test
+ *     - tools
+ *     - topology-read
+ *     - uan
+ *     - virtual-net-device
+ *     - visualizer
+ *     - wifi
+ *     - wimax
+ *
+ */
+/**
+ * \namespace ns3
+ * \brief Every class exported by the ns3 library is enclosed in the
+ * ns3 namespace.
+ */
+
@@ -1,68 +0,0 @@
-/**
- * \mainpage An Introduction to ns-3
- *
- * The ns-3 library is split across multiple modules:
- *     - core: located in src/core and contains a number of facilities which
- *       do not depend on any other module. Some of these facilities are
- *       OS-dependent.
- *     - simulator: located in src/simulator and contains event scheduling
- *       facilities.
- *     - common: located in src/common and contains facilities specific
- *       to network simulations but shared by pretty much every model
- *       of a network component.
- *     - node: located in src/node. Defines the abstract interfaces which 
- *       must be implemented by every node and more specifically, by ipv4 nodes.       
- *     - devices: located in src/devices. Contains a set of MAC-level models
- *
- * The "core" module contains:
- *    - a Functor class: ns3::Callback
- *    - an os-independent interface to get access to the elapsed wall clock time: ns3::SystemWallClockMs
- *    - a class to register regression tests with the test manager: ns3::Test and ns3::TestManager
- *    - debugging facilities: \ref logging, \ref assert, \ref error
- *    - \ref randomvariable
- *    - \ref config
- *    - a base class for objects which need to support reference counting 
- *      and QueryInterface: ns3::Object and ns3::InterfaceId
- *    - a set of low-level trace facilities integrated in the ns3::Object system: \ref tracing
- *    - a ns3::ComponentManager which can be used to manage the creation
- *      of any object which derives from ns3::Object through an ns3::ClassId
- *    - a smart-pointer class ns3::Ptr designed to work together with ns3::Object
- *
- * The "simulator" module contains:
- *    - a time management class to hold a time and convert between various time units: ns3::Time
- *    - a scheduler base class used to implement new simulation event schedulers: 
- *      ns3::Scheduler and ns3::SchedulerFactory
- *    - a simulator class used to create, schedule and cancel events: ns3::Simulator
- *
- * The "core" module contains:
- *    - a packet class to create and manipulate simulation packets: ns3::Packet, ns3::Header, 
- *      and ns3::Trailer. This packet class also supports per-packet ns3::Tag which are
- *      globs of data which can be attached to any packet.
- *
- * The "node" module contains:
- *    - a ns3::Node base class which should be subclassed by any new type of
- *      network Node.
- *    - models which abstract the MAC-layer from the IP layer protocols:
- *      ns3::NetDevice and ns3::Channel.
- *    - models which abstract the application-layer API: ns3::Application,
- *      ns3::Socket, ns3::SocketFactory, and, ns3::Udp
- *
- * The "internet-node" module contains a set of classes which implement the
- * APIs defined in the "node" module:
- *    - an Ipv4/Udp stack with socket support
- *    - an ARP module
- *    - an InternetNode class which is a Node subclass. 
- *
- * The "devices" module contains:
- *    - a PointToPoint MAC device: ns3::PointToPointNetDevice, ns3::PointToPointChannel,
- *      and ns3::PointToPointTopology.
- */
-/**
- * \namespace ns3
- * \brief Every class exported by the ns3 library is enclosed in the
- * ns3 namespace.
- */
-/**
- * \defgroup constants Constants
- * \brief Constants you can change
- */
@@ -0,0 +1,163 @@
+EPSTOPDF = epstopdf
+DIA = dia
+CONVERT = convert
+
+FIGURES = figures
+VPATH = $(FIGURES)
+
+IMAGES_EPS = \
+	$(FIGURES)/software-organization.eps \
+
+# rescale pdf figures as necessary
+$(FIGURES)/software-organization.pdf_width = 5in
+
+IMAGES_PNG = \
+	$(FIGURES)/plot-2d.png \
+	$(FIGURES)/plot-2d-with-error-bars.png \
+	$(FIGURES)/plot-3d.png \
+	${IMAGES_EPS:.eps=.png}
+IMAGES_PDF = ${IMAGES_EPS:.eps=.pdf}
+
+IMAGES = $(IMAGES_EPS) $(IMAGES_PNG) $(IMAGES_PDF)
+
+%.eps : %.dia; $(DIA) -t eps $< -e $@
+%.png : %.dia; $(DIA) -t png $< -e $@
+%.png : %.eps; $(CONVERT) $< $@
+%.pdf : %.eps; $(EPSTOPDF) $< -o=$@; if test x$($@_width) != x; then TMPFILE=`mktemp`; ./rescale-pdf.sh $($@_width) $@ $${TMPFILE} && mv $${TMPFILE} $@; fi
+
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+PAPER         =
+BUILDDIR      = build
+
+# Internal variables.
+PAPEROPT_a4     = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
+
+.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest
+
+help:
+	@echo "Please use \`make <target>' where <target> is one of"
+	@echo "  html       to make standalone HTML files"
+	@echo "  dirhtml    to make HTML files named index.html in directories"
+	@echo "  singlehtml to make a single large HTML file"
+	@echo "  pickle     to make pickle files"
+	@echo "  json       to make JSON files"
+	@echo "  htmlhelp   to make HTML files and a HTML help project"
+	@echo "  qthelp     to make HTML files and a qthelp project"
+	@echo "  devhelp    to make HTML files and a Devhelp project"
+	@echo "  epub       to make an epub"
+	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"
+	@echo "  text       to make text files"
+	@echo "  man        to make manual pages"
+	@echo "  changes    to make an overview of all changed/added/deprecated items"
+	@echo "  linkcheck  to check all external links for integrity"
+	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
+
+clean:
+	-rm -rf $(BUILDDIR)
+	-rm -rf $(IMAGES)
+
+frag: pickle
+	@if test ! -d $(BUILDDIR)/frag; then mkdir $(BUILDDIR)/frag; fi
+	pushd $(BUILDDIR)/frag && ../../pickle-to-xml.py ../pickle/index.fpickle  > navigation.xml && popd
+	cp -r $(BUILDDIR)/pickle/_images $(BUILDDIR)/frag
+
+html: $(IMAGES)
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+dirhtml: $(IMAGES)
+	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+
+singlehtml: $(IMAGES)
+	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
+	@echo
+	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
+
+pickle: $(IMAGES)
+	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
+	@echo
+	@echo "Build finished; now you can process the pickle files."
+
+json: $(IMAGES)
+	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
+	@echo
+	@echo "Build finished; now you can process the JSON files."
+
+htmlhelp: $(IMAGES)
+	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
+	@echo
+	@echo "Build finished; now you can run HTML Help Workshop with the" \
+	      ".hhp project file in $(BUILDDIR)/htmlhelp."
+
+qthelp: $(IMAGES)
+	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
+	@echo
+	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
+	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
+	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/ns-3.qhcp"
+	@echo "To view the help file:"
+	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/ns-3.qhc"
+
+devhelp: $(IMAGES)
+	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
+	@echo
+	@echo "Build finished."
+	@echo "To view the help file:"
+	@echo "# mkdir -p $$HOME/.local/share/devhelp/ns-3"
+	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/ns-3"
+	@echo "# devhelp"
+
+epub: $(IMAGES)
+	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
+	@echo
+	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
+
+latex: $(IMAGES)
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo
+	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
+	@echo "Run \`make' in that directory to run these through (pdf)latex" \
+	      "(use \`make latexpdf' here to do that automatically)."
+
+latexpdf: $(IMAGES)
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo "Running LaTeX files through pdflatex..."
+	make -C $(BUILDDIR)/latex all-pdf
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+text: $(IMAGES)
+	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
+	@echo
+	@echo "Build finished. The text files are in $(BUILDDIR)/text."
+
+man: $(IMAGES)
+	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
+	@echo
+	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
+
+changes: $(IMAGES)
+	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
+	@echo
+	@echo "The overview file is in $(BUILDDIR)/changes."
+
+linkcheck: $(IMAGEs)
+	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+	@echo
+	@echo "Link check complete; look for any errors in the above output " \
+	      "or in $(BUILDDIR)/linkcheck/output.txt."
+
+doctest: $(IMAGES)
+	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
+	@echo "Testing of doctests in the sources finished, look at the " \
+	      "results in $(BUILDDIR)/doctest/output.txt."
+
+
@@ -0,0 +1,18 @@
+Please write image files in a vector graphics format, when possible, and
+generate the .png and .pdf versions on the fly (see ../Makefile).  
+
+The currently supported tool is dia.  xfig could be added similarly
+if someone wants to add it.  The main requirement for adding another format
+is that the tool to edit it is freely available and that a cron script can 
+autogenerate the pdf and png from the figure source.  Tgif (.obj) files
+were once used but the file conversions require a valid X display to 
+be running, and are therefore to be avoided since our code server 
+does not run such a server.  Tgif pdf conversions were also cumbersome.
+
+Store the .dia versions in mercurial, but not the .png or .pdfs.  
+If the figure is not available in a vector graphics format, store both
+a .png and a .pdf version in this directory.
+
+If you add a source (.dia) file here, remember to add it to
+the list of figure sources in the Makefile in the directory above
+
@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+
+TMPFILE=`mktemp`
+
+echo "\documentclass{book}
+\usepackage{pdfpages}
+\begin{document}
+\includepdf[width=${1},fitpaper]{${2}}
+\end{document}" >${TMPFILE}.tex
+pdflatex -output-directory /tmp ${TMPFILE}.tex >/dev/null 2>/dev/null
+cp ${TMPFILE}.pdf ${3}
+
@@ -0,0 +1,887 @@
+.. include:: replace.txt
+
+Attributes
+----------
+
+In |ns3| simulations, there are two main aspects to configuration:
+
+* the simulation topology and how objects are connected 
+* the values used by the models instantiated in the topology
+
+This chapter focuses on the second item above: how the many values in use in
+|ns3| are organized, documented, and modifiable by |ns3| users. The |ns3|
+attribute system is also the underpinning of how traces and statistics are
+gathered in the simulator. 
+
+Before delving into details of the attribute value system, it will help to
+review some basic properties of class :cpp:class:`ns3::Object`.
+
+Object Overview
+***************
+
+|ns3| is fundamentally a C++ object-based system. By this we mean that new C++
+classes (types) can be declared, defined, and subclassed as usual.
+
+Many |ns3| objects inherit from the :cpp:class:`ns3::Object` base class.  These
+objects have some additional properties that we exploit for organizing the
+system and improving the memory management of our objects:
+
+* a "metadata" system that links the class name to a lot of meta-information
+  about the object, including the base class of the subclass, the set of
+  accessible constructors in the subclass, and the set of "attributes" of the
+  subclass
+* a reference counting smart pointer implementation, for memory management.
+
+|ns3| objects that use the attribute system derive from either
+:cpp:class:`ns3::Object` or :cpp:class:`ns3::ObjectBase`. Most |ns3| objects we
+will discuss derive from :cpp:class:`ns3::Object`, but a few that are outside
+the smart pointer memory management framework derive from
+:cpp:class:`ns3::ObjectBase`.
+
+Let's review a couple of properties of these objects.
+
+Smart pointers
+**************
+
+As introduced in the |ns3| tutorial, |ns3| objects are memory managed by a
+`reference counting smart pointer implementation
+<http://en.wikipedia.org/wiki/Smart_pointer>`_, class :cpp:class:`ns3::Ptr`. 
+
+Smart pointers are used extensively in the |ns3| APIs, to avoid passing
+references to heap-allocated objects that may cause memory leaks.  
+For most basic usage (syntax), treat a smart pointer like a regular pointer:::
+
+  Ptr<WifiNetDevice> nd = ...;
+  nd->CallSomeFunction ();
+  // etc.
+
+CreateObject
++++++++++++
+
+As we discussed above in :ref:`Memory management and class Ptr`, at the
+lowest-level API, objects of type :cpp:class:`ns3::Object` are not instantiated
+using ``operator new`` as usual but instead by a templated function called
+:cpp:func:`CreateObject()`.
+
+A typical way to create such an object is as follows:::
+
+  Ptr<WifiNetDevice> nd = CreateObject<WifiNetDevice> ();
+
+You can think of this as being functionally equivalent to:::
+
+  WifiNetDevice* nd = new WifiNetDevice ();
+
+Objects that derive from :cpp:class:`ns3::Object` must be allocated on the heap
+using CreateObject(). Those deriving from :cpp:class:`ns3::ObjectBase`, such as
+|ns3| helper functions and packet headers and trailers, can be allocated on the
+stack.  
+
+In some scripts, you may not see a lot of CreateObject() calls in the code; this
+is because there are some helper objects in effect that are doing the
+CreateObject()s for you.
+
+TypeId
++++++
+
+|ns3| classes that derive from class ns3::Object can include a metadata class
+called ``TypeId`` that records meta-information about the class, for use in the
+object aggregation and component manager systems:
+
+* a unique string identifying the class
+* the base class of the subclass, within the metadata system
+* the set of accessible constructors in the subclass
+
+Object Summary
++++++++++++++
+
+Putting all of these concepts together, let's look at a specific
+example: class :cpp:class:`ns3::Node`.
+
+The public header file node.h has a declaration that includes a static GetTypeId
+function call:::
+
+    class Node : public Object
+    {
+    public:
+      static TypeId GetTypeId (void);
+      ...
+
+This is defined in the ``node.cc`` file as follows:::
+
+    TypeId 
+    Node::GetTypeId (void)
+    {
+      static TypeId tid = TypeId ("ns3::Node")
+        .SetParent<Object> ()
+        .AddConstructor<Node> ()
+        .AddAttribute ("DeviceList", "The list of devices associated to this Node.",
+                       ObjectVectorValue (),
+                       MakeObjectVectorAccessor (&Node::m_devices),
+                       MakeObjectVectorChecker<NetDevice> ())
+        .AddAttribute ("ApplicationList", "The list of applications associated to this Node.",
+                       ObjectVectorValue (),
+                       MakeObjectVectorAccessor (&Node::m_applications),
+                       MakeObjectVectorChecker<Application> ())
+        .AddAttribute ("Id", "The id (unique integer) of this Node.",
+                       TypeId::ATTR_GET, // allow only getting it.
+                       UintegerValue (0),
+                       MakeUintegerAccessor (&Node::m_id),
+                       MakeUintegerChecker<uint32_t> ())
+        ;
+      return tid;
+    }
+
+Consider the TypeId of an |ns3| ``Object`` class as an extended form of run time
+type information (RTTI). The C++ language includes a simple kind of RTTI in
+order to support ``dynamic_cast`` and ``typeid`` operators.
+
+The "``.SetParent<Object> ()``" call in the declaration above is used in
+conjunction with our object aggregation mechanisms to allow safe up- and
+down-casting in inheritance trees during ``GetObject``.
+
+The "``.AddConstructor<Node> ()``" call is used in conjunction with our abstract
+object factory mechanisms to allow us to construct C++ objects without forcing a
+user to know the concrete class of the object she is building.
+
+The three calls to "``.AddAttribute``" associate a given string with a strongly
+typed value in the class. Notice that you must provide a help string which may
+be displayed, for example, via command line processors. Each ``Attribute`` is
+associated with mechanisms for accessing the underlying member variable in the
+object (for example, ``MakeUintegerAccessor`` tells the generic ``Attribute``
+code how to get to the node ID above). There are also "Checker" methods which
+are used to validate values.
+
+When users want to create Nodes, they will usually call some form of 
+``CreateObject``,::
+
+    Ptr<Node> n = CreateObject<Node> ();
+
+or more abstractly, using an object factory, you can create a ``Node`` object
+without even knowing the concrete C++ type::
+
+    ObjectFactory factory;
+    const std::string typeId = "ns3::Node'';
+    factory.SetTypeId (typeId);
+    Ptr<Object> node = factory.Create <Object> ();
+
+Both of these methods result in fully initialized attributes being available 
+in the resulting ``Object`` instances.
+
+We next discuss how attributes (values associated with member variables or
+functions of the class) are plumbed into the above TypeId.
+
+Attribute Overview
+******************
+
+The goal of the attribute system is to organize the access of
+internal member objects of a simulation. This goal arises because,
+typically in simulation, users will cut and paste/modify existing
+simulation scripts, or will use higher-level simulation constructs,
+but often will be interested in studying or tracing particular 
+internal variables.  For instance, use cases such as:
+
+* "I want to trace the packets on the wireless interface only on the first
+  access point"
+* "I want to trace the value of the TCP congestion window (every time it
+  changes) on a particular TCP socket"
+* "I want a dump of all values that were used in my simulation."
+
+Similarly, users may want fine-grained access to internal variables in the
+simulation, or may want to broadly change the initial value used for a
+particular parameter in all subsequently created objects. Finally, users may
+wish to know what variables are settable and retrievable in a simulation
+configuration. This is not just for direct simulation interaction on the command
+line; consider also a (future) graphical user interface that would like to be
+able to provide a feature whereby a user might right-click on an node on the
+canvas and see a hierarchical, organized list of parameters that are settable on
+the node and its constituent member objects, and help text and default values
+for each parameter.
+
+Functional overview
+++++++++++++++++++
+
+We provide a way for users to access values deep in the system, without having
+to plumb accessors (pointers) through the system and walk pointer chains to get
+to them. Consider a class DropTailQueue that has a member variable that is an
+unsigned integer ``m_maxPackets``; this member variable controls the depth of
+the queue.  
+
+If we look at the declaration of DropTailQueue, we see the following:::
+
+    class DropTailQueue : public Queue {
+    public:
+      static TypeId GetTypeId (void);
+      ...
+
+    private:
+      std::queue<Ptr<Packet> > m_packets;
+      uint32_t m_maxPackets;
+    };
+
+Let's consider things that a user may want to do with the value of
+m_maxPackets:
+
+* Set a default value for the system, such that whenever a new DropTailQueue is
+  created, this member is initialized to that default. 
+* Set or get the value on an already instantiated queue.
+
+The above things typically require providing Set() and Get() functions, and some
+type of global default value.
+
+In the |ns3| attribute system, these value definitions and accessor functions
+are moved into the TypeId class; e.g.:::
+
+    NS_OBJECT_ENSURE_REGISTERED (DropTailQueue);
+
+    TypeId DropTailQueue::GetTypeId (void) 
+    {
+      static TypeId tid = TypeId ("ns3::DropTailQueue")
+        .SetParent<Queue> ()
+        .AddConstructor<DropTailQueue> ()
+        .AddAttribute ("MaxPackets", 
+                       "The maximum number of packets accepted by this DropTailQueue.",
+                       UintegerValue (100),
+                       MakeUintegerAccessor (&DropTailQueue::m_maxPackets),
+                       MakeUintegerChecker<uint32_t> ())
+        ;
+      
+      return tid;
+    }
+
+The AddAttribute() method is performing a number of things with this
+value:
+
+* Binding the variable m_maxPackets to a string "MaxPackets"
+* Providing a default value (100 packets)
+* Providing some help text defining the value
+* Providing a "checker" (not used in this example) that can be used to set
+  bounds on the allowable range of values
+
+The key point is that now the value of this variable and its default value are
+accessible in the attribute namespace, which is based on strings such as
+"MaxPackets" and TypeId strings. In the next section, we will provide an example
+script that shows how users may manipulate these values.
+
+Note that initialization of the attribute relies on the macro
+``NS_OBJECT_ENSURE_REGISTERED`` (DropTailQueue) being called; if you leave this
+out of your new class implementation, your attributes will not be initialized
+correctly.
+
+While we have described how to create attributes, we still haven't described how
+to access and manage these values. For instance, there is no ``globals.h``
+header file where these are stored; attributes are stored with their classes.
+Questions that naturally arise are how do users easily learn about all of the
+attributes of their models, and how does a user access these attributes, or
+document their values as part of the record of their simulation?
+
+Default values and command-line arguments
+++++++++++++++++++++++++++++++++++++++++
+
+Let's look at how a user script might access these values.  
+This is based on the script found at ``src/point-to-point/examples/main-attribute-value.cc``,
+with some details stripped out.::
+
+    //
+    // This is a basic example of how to use the attribute system to
+    // set and get a value in the underlying system; namely, an unsigned
+    // integer of the maximum number of packets in a queue
+    //
+
+    int 
+    main (int argc, char *argv[])
+    {
+
+      // By default, the MaxPackets attribute has a value of 100 packets
+      // (this default can be observed in the function DropTailQueue::GetTypeId)
+      // 
+      // Here, we set it to 80 packets.  We could use one of two value types:
+      // a string-based value or a Uinteger value
+      Config::SetDefault ("ns3::DropTailQueue::MaxPackets", StringValue ("80"));
+      // The below function call is redundant
+      Config::SetDefault ("ns3::DropTailQueue::MaxPackets", UintegerValue (80));
+
+      // Allow the user to override any of the defaults and the above
+      // SetDefaults() at run-time, via command-line arguments
+      CommandLine cmd;
+      cmd.Parse (argc, argv);
+
+The main thing to notice in the above are the two calls to 
+``Config::SetDefault``.  This is how we set the default value
+for all subsequently instantiated DropTailQueues.  We illustrate
+that two types of Value classes, a StringValue and a UintegerValue class,
+can be used to assign the value to the attribute named by
+"ns3::DropTailQueue::MaxPackets".
+
+Now, we will create a few objects using the low-level API; here,
+our newly created queues will not have a m_maxPackets initialized to
+100 packets but to 80 packets, because of what we did above with
+default values.::
+
+    Ptr<Node> n0 = CreateObject<Node> ();
+
+    Ptr<PointToPointNetDevice> net0 = CreateObject<PointToPointNetDevice> ();
+    n0->AddDevice (net0);
+
+    Ptr<Queue> q = CreateObject<DropTailQueue> ();
+    net0->AddQueue(q);
+
+At this point, we have created a single node (Node 0) and a single
+PointToPointNetDevice (NetDevice 0) and added a DropTailQueue to it.
+
+Now, we can manipulate the MaxPackets value of the already instantiated
+DropTailQueue. Here are various ways to do that.
+
+Pointer-based access
++++++++++++++++++++
+
+We assume that a smart pointer (Ptr) to a relevant network device is in hand; in
+the current example, it is the ``net0`` pointer. 
+
+One way to change the value is to access a pointer to the underlying queue and
+modify its attribute.
+ 
+First, we observe that we can get a pointer to the (base class) queue via the
+PointToPointNetDevice attributes, where it is called TxQueue::
+
+    PointerValue tmp;
+    net0->GetAttribute ("TxQueue", tmp);
+    Ptr<Object> txQueue = tmp.GetObject ();
+
+Using the GetObject function, we can perform a safe downcast to a DropTailQueue,
+where MaxPackets is a member::
+
+    Ptr<DropTailQueue> dtq = txQueue->GetObject <DropTailQueue> ();
+    NS_ASSERT (dtq != 0);
+
+Next, we can get the value of an attribute on this queue.  We have introduced
+wrapper "Value" classes for the underlying data types, similar to Java wrappers
+around these types, since the attribute system stores values and not disparate
+types.  Here, the attribute value is assigned to a UintegerValue, and the Get()
+method on this value produces the (unwrapped) uint32_t.::
+
+    UintegerValue limit;
+    dtq->GetAttribute ("MaxPackets", limit);
+    NS_LOG_INFO ("1.  dtq limit: " << limit.Get () << " packets");
+  
+Note that the above downcast is not really needed; we could have done the same
+using the Ptr<Queue> even though the attribute is a member of the subclass::
+
+    txQueue->GetAttribute ("MaxPackets", limit);
+    NS_LOG_INFO ("2.  txQueue limit: " << limit.Get () << " packets");
+
+Now, let's set it to another value (60 packets)::
+
+    txQueue->SetAttribute("MaxPackets", UintegerValue (60));
+    txQueue->GetAttribute ("MaxPackets", limit);
+    NS_LOG_INFO ("3.  txQueue limit changed: " << limit.Get () << " packets");
+
+Namespace-based access
++++++++++++++++++++++
+
+An alternative way to get at the attribute is to use the configuration
+namespace.  Here, this attribute resides on a known path in this namespace; this
+approach is useful if one doesn't have access to the underlying pointers and
+would like to configure a specific attribute with a single statement.::
+
+    Config::Set ("/NodeList/0/DeviceList/0/TxQueue/MaxPackets", UintegerValue (25));
+    txQueue->GetAttribute ("MaxPackets", limit); 
+    NS_LOG_INFO ("4.  txQueue limit changed through namespace: " << 
+        limit.Get () << " packets");
+
+We could have also used wildcards to set this value for all nodes and all net
+devices (which in this simple example has the same effect as the previous
+Set())::
+
+    Config::Set ("/NodeList/*/DeviceList/*/TxQueue/MaxPackets", UintegerValue (15));
+    txQueue->GetAttribute ("MaxPackets", limit); 
+    NS_LOG_INFO ("5.  txQueue limit changed through wildcarded namespace: " << 
+        limit.Get () << " packets");
+
+Object Name Service-based access
++++++++++++++++++++++++++++++++
+
+Another way to get at the attribute is to use the object name service facility.
+Here, this attribute is found using a name string. This approach is useful if
+one doesn't have access to the underlying pointers and it is difficult to
+determine the required concrete configuration namespaced path.::
+
+    Names::Add ("server", serverNode);
+    Names::Add ("server/eth0", serverDevice);
+
+    ...
+
+    Config::Set ("/Names/server/eth0/TxQueue/MaxPackets", UintegerValue (25));
+
+:ref:`Object names` for a fuller treatment of the |ns3| configuration namespace.
+
+Setting through constructors helper classes
+++++++++++++++++++++++++++++++++++++++++++
+
+Arbitrary combinations of attributes can be set and fetched from
+the helper and low-level APIs; either from the constructors themselves:::
+
+    Ptr<Object> p = CreateObject<MyNewObject> ("n1", v1, "n2", v2, ...);
+
+or from the higher-level helper APIs, such as:::
+
+    mobility.SetPositionAllocator ("GridPositionAllocator",
+                                   "MinX", DoubleValue (-100.0),
+                                   "MinY", DoubleValue (-100.0),
+                                   "DeltaX", DoubleValue (5.0),
+                                   "DeltaY", DoubleValue (20.0),
+                                   "GridWidth", UintegerValue (20),
+                                   "LayoutType", StringValue ("RowFirst"));
+
+Implementation details
++++++++++++++++++++++
+
+Value classes
+~~~~~~~~~~~~~
+
+Readers will note the new FooValue classes which are subclasses of the
+AttributeValue base class. These can be thought of as an intermediate class that
+can be used to convert from raw types to the Values that are used by the
+attribute system. Recall that this database is holding objects of many types
+with a single generic type. Conversions to this type can either be done using an
+intermediate class (IntegerValue, DoubleValue for "floating point") or via
+strings. Direct implicit conversion of types to Value is not really practical.
+So in the above, users have a choice of using strings or values:::
+
+    p->Set ("cwnd", StringValue ("100")); // string-based setter
+    p->Set ("cwnd", IntegerValue (100)); // integer-based setter
+
+The system provides some macros that help users declare and define
+new AttributeValue subclasses for new types that they want to introduce into
+the attribute system: 
+
+* ATTRIBUTE_HELPER_HEADER
+* ATTRIBUTE_HELPER_CPP
+
+Initialization order
+~~~~~~~~~~~~~~~~~~~~
+
+Attributes in the system must not depend on the state of any other Attribute in
+this system. This is because an ordering of Attribute initialization is not
+specified, nor enforced, by the system. A specific example of this can be seen
+in automated configuration programs such as :cpp:class:`ns3::ConfigStore`.
+Although a given model may arrange it so that Attributes are initialized in a
+particular order, another automatic configurator may decide independently to
+change Attributes in, for example, alphabetic order.  
+
+Because of this non-specific ordering, no Attribute in the system may have any
+dependence on any other Attribute. As a corollary, Attribute setters must never
+fail due to the state of another Attribute. No Attribute setter may change (set)
+any other Attribute value as a result of changing its value.
+
+This is a very strong restriction and there are cases where Attributes must set
+consistently to allow correct operation. To this end we do allow for consistency
+checking *when the attribute is used* (cf. NS_ASSERT_MSG or NS_ABORT_MSG).
+
+In general, the attribute code to assign values to the underlying class member
+variables is executed after an object is constructed. But what if you need the
+values assigned before the constructor body executes, because you need them in
+the logic of the constructor? There is a way to do this, used for example in the
+class :cpp:class:`ns3::ConfigStore`: call ``ObjectBase::ConstructSelf ()`` as
+follows:::
+
+    ConfigStore::ConfigStore ()
+    {
+      ObjectBase::ConstructSelf (AttributeList ());
+      // continue on with constructor.
+    }
+
+Extending attributes
+********************
+
+The |ns3| system will place a number of internal values under the attribute
+system, but undoubtedly users will want to extend this to pick up ones we have
+missed, or to add their own classes to this.
+
+Adding an existing internal variable to the metadata system 
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+Consider this variable in class TcpSocket:::
+
+    uint32_t m_cWnd;   // Congestion window
+
+Suppose that someone working with TCP wanted to get or set the value of that
+variable using the metadata system. If it were not already provided by |ns3|,
+the user could declare the following addition in the runtime metadata system (to
+the TypeId declaration for TcpSocket):::
+
+    .AddAttribute ("Congestion window", 
+                   "Tcp congestion window (bytes)",
+                   UintegerValue (1),
+                   MakeUintegerAccessor (&TcpSocket::m_cWnd),
+                   MakeUintegerChecker<uint16_t> ())
+
+Now, the user with a pointer to the TcpSocket can perform operations such as
+setting and getting the value, without having to add these functions explicitly.
+Furthermore, access controls can be applied, such as allowing the parameter to
+be read and not written, or bounds checking on the permissible values can be
+applied.
+
+Adding a new TypeId
+++++++++++++++++++
+
+Here, we discuss the impact on a user who wants to add a new class to |ns3|;
+what additional things must be done to hook it into this system.
+
+We've already introduced what a TypeId definition looks like:::
+
+    TypeId
+    RandomWalk2dMobilityModel::GetTypeId (void)
+    {
+      static TypeId tid = TypeId ("ns3::RandomWalk2dMobilityModel")
+        .SetParent<MobilityModel> ()
+        .SetGroupName ("Mobility")
+        .AddConstructor<RandomWalk2dMobilityModel> ()
+        .AddAttribute ("Bounds",
+                       "Bounds of the area to cruise.",
+                       RectangleValue (Rectangle (0.0, 0.0, 100.0, 100.0)),
+                       MakeRectangleAccessor (&RandomWalk2dMobilityModel::m_bounds),
+                       MakeRectangleChecker ())
+        .AddAttribute ("Time",
+                       "Change current direction and speed after moving for this delay.",
+                       TimeValue (Seconds (1.0)),
+                       MakeTimeAccessor (&RandomWalk2dMobilityModel::m_modeTime),
+                       MakeTimeChecker ())
+        // etc (more parameters).
+        ;
+      return tid;
+    }
+
+The declaration for this in the class declaration is one-line public member
+method:::
+
+    public:
+      static TypeId GetTypeId (void);
+
+Typical mistakes here involve:
+
+* Not calling the SetParent method or calling it with the wrong type
+* Not calling the AddConstructor method of calling it with the wrong type
+* Introducing a typographical error in the name of the TypeId in its constructor
+* Not using the fully-qualified c++ typename of the enclosing c++ class as the
+  name of the TypeId
+
+None of these mistakes can be detected by the |ns3| codebase so, users
+are advised to check carefully multiple times that they got these right.
+
+Adding new class type to the attribute system
+*********************************************
+
+From the perspective of the user who writes a new class in the system and wants
+to hook it in to the attribute system, there is mainly the matter of writing the
+conversions to/from strings and attribute values.  Most of this can be
+copy/pasted with macro-ized code.  For instance, consider class declaration for
+Rectangle in the ``src/mobility/model`` directory:
+
+Header file
+++++++++++
+
+::
+
+    /**
+     * \brief a 2d rectangle
+     */
+    class Rectangle
+    {
+      ...
+
+      double xMin;
+      double xMax;
+      double yMin;
+      double yMax;
+    };
+ 
+One macro call and two operators, must be added below the class declaration in
+order to turn a Rectangle into a value usable by the ``Attribute`` system:::
+
+    std::ostream &operator << (std::ostream &os, const Rectangle &rectangle);
+    std::istream &operator >> (std::istream &is, Rectangle &rectangle);
+
+    ATTRIBUTE_HELPER_HEADER (Rectangle);
+
+Implementation file
+++++++++++++++++++
+
+In the class definition (``.cc`` file), the code looks like this:::
+
+    ATTRIBUTE_HELPER_CPP (Rectangle);
+
+    std::ostream &
+    operator << (std::ostream &os, const Rectangle &rectangle)
+    {
+      os << rectangle.xMin << "|" << rectangle.xMax << "|" << rectangle.yMin << "|"
+         << rectangle.yMax;
+      return os;
+    }
+    std::istream &
+    operator >> (std::istream &is, Rectangle &rectangle)
+     {
+      char c1, c2, c3;
+      is >> rectangle.xMin >> c1 >> rectangle.xMax >> c2 >> rectangle.yMin >> c3 
+         >> rectangle.yMax;
+      if (c1 != '|' ||
+          c2 != '|' ||
+          c3 != '|')
+        {
+          is.setstate (std::ios_base::failbit);
+        }
+      return is;
+    }
+
+These stream operators simply convert from a string representation of the
+Rectangle ("xMin|xMax|yMin|yMax") to the underlying Rectangle, and the modeler
+must specify these operators and the string syntactical representation of an
+instance of the new class.
+
+ConfigStore
+***********
+
+The ConfigStore is a specialized database for attribute values and 
+default values.  Although it is a separately maintained module in
+``src/config-store/`` directory, we document it here because of its 
+sole dependency on |ns3| core module and attributes.
+
+Values for |ns3| attributes can be stored in an ASCII or XML text file
+and loaded into a future simulation.  This feature is known as the
+|ns3| ConfigStore.  We can explore this system by using an example from
+``src/config-store/examples/config-store-save.cc``.
+
+First, all users must include the following statement:::
+
+    #include "ns3/config-store-module.h"
+
+Next, this program adds a sample object A to show how the system
+is extended:::
+
+    class A : public Object
+    {
+    public:
+      static TypeId GetTypeId (void) {
+        static TypeId tid = TypeId ("ns3::A")
+          .SetParent<Object> ()
+          .AddAttribute ("TestInt16", "help text",
+                         IntegerValue (-2),
+                         MakeIntegerAccessor (&A::m_int16),
+                         MakeIntegerChecker<int16_t> ())
+          ;
+          return tid;
+        }
+      int16_t m_int16;
+    };
+    
+    NS_OBJECT_ENSURE_REGISTERED (A);
+
+Next, we use the Config subsystem to override the defaults in a couple of
+ways:::
+     
+      Config::SetDefault ("ns3::A::TestInt16", IntegerValue (-5));
+    
+      Ptr<A> a_obj = CreateObject<A> ();
+      NS_ABORT_MSG_UNLESS (a_obj->m_int16 == -5, "Cannot set A's integer attribute via Config::SetDefault");
+    
+      Ptr<A> a2_obj = CreateObject<A> ();
+      a2_obj->SetAttribute ("TestInt16", IntegerValue (-3));
+      IntegerValue iv;
+      a2_obj->GetAttribute ("TestInt16", iv);
+      NS_ABORT_MSG_UNLESS (iv.Get () == -3, "Cannot set A's integer attribute via SetAttribute");
+    
+The next statement is necessary to make sure that (one of) the objects
+created is rooted in the configuration namespace as an object instance.
+This normally happens when you aggregate objects to ns3::Node or ns3::Channel
+but here, since we are working at the core level, we need to create a
+new root namespace object:::
+
+      Config::RegisterRootNamespaceObject (a2_obj);
+
+Next, we want to output the configuration store.  The examples show how
+to do it in two formats, XML and raw text.  In practice, one should perform
+this step just before calling ``Simulator::Run ()``;  it will allow the
+configuration to be saved just before running the simulation.
+
+There are three attributes that govern the behavior of the ConfigStore: "Mode",
+"Filename", and "FileFormat".  The Mode (default "None") configures whether
+|ns3| should load configuration from a previously saved file (specify
+"Mode=Load") or save it to a file (specify "Mode=Save").  The Filename (default
+"") is where the ConfigStore should store its output data.  The FileFormat
+(default "RawText") governs whether the ConfigStore format is Xml or RawText
+format.
+
+The example shows:::
+
+      Config::SetDefault ("ns3::ConfigStore::Filename", StringValue ("output-attributes.xml"));
+      Config::SetDefault ("ns3::ConfigStore::FileFormat", StringValue ("Xml"));
+      Config::SetDefault ("ns3::ConfigStore::Mode", StringValue ("Save"));
+      ConfigStore outputConfig;
+      outputConfig.ConfigureDefaults ();
+      outputConfig.ConfigureAttributes ();
+    
+      // Output config store to txt format
+      Config::SetDefault ("ns3::ConfigStore::Filename", StringValue ("output-attributes.txt"));
+      Config::SetDefault ("ns3::ConfigStore::FileFormat", StringValue ("RawText"));
+      Config::SetDefault ("ns3::ConfigStore::Mode", StringValue ("Save"));
+      ConfigStore outputConfig2;
+      outputConfig2.ConfigureDefaults ();
+      outputConfig2.ConfigureAttributes ();
+    
+      Simulator::Run ();
+    
+      Simulator::Destroy ();
+    
+After running, you can open the output-attributes.txt file and see:::
+
+    default ns3::RealtimeSimulatorImpl::SynchronizationMode "BestEffort"
+    default ns3::RealtimeSimulatorImpl::HardLimit "+100000000.0ns"
+    default ns3::PcapFileWrapper::CaptureSize "65535"
+    default ns3::PacketSocket::RcvBufSize "131072"
+    default ns3::ErrorModel::IsEnabled "true"
+    default ns3::RateErrorModel::ErrorUnit "EU_BYTE"
+    default ns3::RateErrorModel::ErrorRate "0"
+    default ns3::RateErrorModel::RanVar "Uniform:0:1"
+    default ns3::DropTailQueue::Mode "Packets"
+    default ns3::DropTailQueue::MaxPackets "100"
+    default ns3::DropTailQueue::MaxBytes "6553500"
+    default ns3::Application::StartTime "+0.0ns"
+    default ns3::Application::StopTime "+0.0ns"
+    default ns3::ConfigStore::Mode "Save"
+    default ns3::ConfigStore::Filename "output-attributes.txt"
+    default ns3::ConfigStore::FileFormat "RawText"
+    default ns3::A::TestInt16 "-5"
+    global RngSeed "1"
+    global RngRun "1"
+    global SimulatorImplementationType "ns3::DefaultSimulatorImpl"
+    global SchedulerType "ns3::MapScheduler"
+    global ChecksumEnabled "false"
+    value /$ns3::A/TestInt16 "-3"
+
+In the above, all of the default values for attributes for the core 
+module are shown.  Then, all the values for the |ns3| global values
+are recorded.  Finally, the value of the instance of A that was rooted
+in the configuration namespace is shown.  In a real ns-3 program, many
+more models, attributes, and defaults would be shown.
+
+An XML version also exists in ``output-attributes.xml``:::
+
+    <?xml version="1.0" encoding="UTF-8"?>
+    <ns3>
+     <default name="ns3::RealtimeSimulatorImpl::SynchronizationMode" value="BestEffort"/>
+     <default name="ns3::RealtimeSimulatorImpl::HardLimit" value="+100000000.0ns"/>
+     <default name="ns3::PcapFileWrapper::CaptureSize" value="65535"/>
+     <default name="ns3::PacketSocket::RcvBufSize" value="131072"/>
+     <default name="ns3::ErrorModel::IsEnabled" value="true"/>
+     <default name="ns3::RateErrorModel::ErrorUnit" value="EU_BYTE"/>
+     <default name="ns3::RateErrorModel::ErrorRate" value="0"/>
+     <default name="ns3::RateErrorModel::RanVar" value="Uniform:0:1"/>
+     <default name="ns3::DropTailQueue::Mode" value="Packets"/>
+     <default name="ns3::DropTailQueue::MaxPackets" value="100"/>
+     <default name="ns3::DropTailQueue::MaxBytes" value="6553500"/>
+     <default name="ns3::Application::StartTime" value="+0.0ns"/>
+     <default name="ns3::Application::StopTime" value="+0.0ns"/>
+     <default name="ns3::ConfigStore::Mode" value="Save"/>
+     <default name="ns3::ConfigStore::Filename" value="output-attributes.xml"/>
+     <default name="ns3::ConfigStore::FileFormat" value="Xml"/>
+     <default name="ns3::A::TestInt16" value="-5"/>
+     <global name="RngSeed" value="1"/>
+     <global name="RngRun" value="1"/>
+     <global name="SimulatorImplementationType" value="ns3::DefaultSimulatorImpl"/>
+     <global name="SchedulerType" value="ns3::MapScheduler"/>
+     <global name="ChecksumEnabled" value="false"/>
+     <value path="/$ns3::A/TestInt16" value="-3"/>
+    </ns3>
+    
+This file can be archived with your simulation script and output data.
+
+While it is possible to generate a sample config file and lightly edit it to
+change a couple of values, there are cases where this process will not work
+because the same value on the same object can appear multiple times in the same
+automatically-generated configuration file under different configuration paths.
+
+As such, the best way to use this class is to use it to generate an initial
+configuration file, extract from that configuration file only the strictly
+necessary elements, and move these minimal elements to a new configuration file
+which can then safely be edited and loaded in a subsequent simulation run. 
+
+When the ConfigStore object is instantiated, its attributes Filename, Mode, and
+FileFormat must be set, either via command-line or via program statements.  
+
+As a more complicated example, let's assume that we want to read in a
+configuration of defaults from an input file named "input-defaults.xml", and
+write out the resulting attributes to a separate file called
+"output-attributes.xml".  (Note-- to get this input xml file to begin with, it
+is sometimes helpful to run the program to generate an output xml file first,
+then hand-edit that file and re-input it for the next simulation run).::
+
+    #include "ns3/config-store-module.h"
+    ...
+    int main (...)
+    {
+
+      Config::SetDefault ("ns3::ConfigStore::Filename", StringValue ("input-defaults.xml"));
+      Config::SetDefault ("ns3::ConfigStore::Mode", StringValue ("Load"));
+      Config::SetDefault ("ns3::ConfigStore::FileFormat", StringValue ("Xml"));
+      ConfigStore inputConfig;
+      inputConfig.ConfigureDefaults ();
+      
+      //
+      // Allow the user to override any of the defaults and the above Bind() at
+      // run-time, via command-line arguments
+      //
+      CommandLine cmd;
+      cmd.Parse (argc, argv);
+
+      // setup topology
+      ...
+
+      // Invoke just before entering Simulator::Run ()
+      Config::SetDefault ("ns3::ConfigStore::Filename", StringValue ("output-attributes.xml"));
+      Config::SetDefault ("ns3::ConfigStore::Mode", StringValue ("Save"));
+      ConfigStore outputConfig;
+      outputConfig.ConfigureAttributes ();
+      Simulator::Run ();
+    }
+
+GTK-based ConfigStore
+++++++++++++++++++++
+
+There is a GTK-based front end for the ConfigStore.  This allows users to use a
+GUI to access and change variables.  Screenshots of this feature are available
+in the `|ns3| Overview <http://www.nsnam.org/docs/ns-3-overview.pdf>`_
+presentation.
+
+To use this feature, one must install libgtk and libgtk-dev; an example
+Ubuntu installation command is:::
+
+    sudo apt-get install libgtk2.0-0 libgtk2.0-dev
+
+To check whether it is configured or not, check the output of the step:::
+./waf configure --enable-examples --enable-tests 
+
+    ---- Summary of optional NS-3 features:
+    Threading Primitives          : enabled
+    Real Time Simulator           : enabled
+    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 ./waf configure --enable-examples --enable-tests; ./waf is rerun.
+
+Usage is almost the same as the non-GTK-based version, but there
+are no ConfigStore attributes involved:::
+
+  // Invoke just before entering Simulator::Run ()
+  GtkConfigStore config;
+  config.ConfigureDefaults ();
+  config.ConfigureAttributes ();
+
+Now, when you run the script, a GUI should pop up, allowing you to open menus of
+attributes on different nodes/objects, and then launch the simulation execution
+when you are done.  
+
+Future work
+++++++++++
+There are a couple of possible improvements:
+* save a unique version number with date and time at start of file
+* save rng initial seed somewhere.
+* make each RandomVariable serialize its own initial seed and re-read it later
@@ -0,0 +1,255 @@
+.. include:: replace.txt
+
+Callbacks
+---------
+
+Some new users to |ns3| are unfamiliar with an extensively used programming
+idiom used throughout the code: the *ns-3 callback*. This chapter provides some
+motivation on the callback, guidance on how to use it, and details on its
+implementation.
+
+Callbacks Motivation
+********************
+
+Consider that you have two simulation models A and B, and you wish to have them
+pass information between them during the simulation. One way that you can do
+that is that you can make A and B each explicitly knowledgeable about the other,
+so that they can invoke methods on each other::
+
+  class A {
+  public:
+    void ReceiveInput ( // parameters );
+    ...
+  }
+
+  (in another source file:)
+
+  class B {
+  public:
+    void DoSomething (void);
+    ...
+
+  private:
+    A* a_instance; // pointer to an A
+  }
+
+  void
+  B::DoSomething()
+  {
+    // Tell a_instance that something happened
+    a_instance->ReceiveInput ( // parameters);
+    ...
+  }
+
+This certainly works, but it has the drawback that it introduces a dependency on
+A and B to know about the other at compile time (this makes it harder to have
+independent compilation units in the simulator) and is not generalized; if in a
+later usage scenario, B needs to talk to a completely different C object, the
+source code for B needs to be changed to add a ``c_instance`` and so forth. It
+is easy to see that this is a brute force mechanism of communication that can
+lead to programming cruft in the models.  
+
+This is not to say that objects should not know about one another if there is a
+hard dependency between them, but that often the model can be made more flexible
+if its interactions are less constrained at compile time.
+
+This is not an abstract problem for network simulation research, but rather it
+has been a source of problems in previous simulators, when researchers want to
+extend or modify the system to do different things (as they are apt to do in
+research). Consider, for example, a user who wants to add an IPsec security
+protocol sublayer between TCP and IP::
+
+  ------------                   -----------
+  |   TCP    |                   |  TCP    |
+  ------------                   -----------
+       |           becomes ->        |
+  -----------                    -----------
+  |   IP    |                    | IPsec   |
+  -----------                    -----------
+                                     |
+                                 -----------
+                                 |   IP    |
+                                 -----------
+
+
+If the simulator has made assumptions, and hard coded into the code, that IP
+always talks to a transport protocol above, the user may be forced to hack the
+system to get the desired interconnections. This is clearly not an optimal way
+to design a generic simulator.
+
+Callbacks Background
+********************
+
+.. note:: Readers familiar with programming callbacks may skip this tutorial
+    section.
+
+The basic mechanism that allows one to address the problem above is known as a
+*callback*. The ultimate goal is to allow one piece of code to call a function
+(or method in C++) without any specific inter-module dependency.
+
+This ultimately means you need some kind of indirection -- you treat the address
+of the called function as a variable.  This variable is called a
+pointer-to-function variable. The relationship between function and
+pointer-to-function pointer is really no different that that of object and
+pointer-to-object.
+
+In C the canonical example of a pointer-to-function is a
+pointer-to-function-returning-integer (PFI). For a PFI taking one int parameter,
+this could be declared like,::
+
+  int (*pfi)(int arg) = 0;
+
+What you get from this is a variable named simply ``pfi`` that is initialized to
+the value 0. If you want to initialize this pointer to something meaningful, you
+have to have a function with a matching signature. In this case::
+
+  int MyFunction (int arg) {}
+
+If you have this target, you can initialize the variable to point to your
+function like::
+
+  pfi = MyFunction;
+
+You can then call MyFunction indirectly using the more suggestive form of the
+call::
+
+  int result = (*pfi) (1234);
+
+This is suggestive since it looks like you are dereferencing the function
+pointer just like you would dereference any pointer. Typically, however, people
+take advantage of the fact that the compiler knows what is going on and will
+just use a shorter form::
+
+  int result = pfi (1234);
+
+Notice that the function pointer obeys value semantics, so you can pass it
+around like any other value. Typically, when you use an asynchronous interface
+you will pass some entity like this to a function which will perform an action
+and *call back* to let you know it completed. It calls back by following the
+indirection and executing the provided function.
+
+In C++ you have the added complexity of objects. The analogy with the PFI above
+means you have a pointer to a member function returning an int (PMI) instead of
+the pointer to function returning an int (PFI).
+
+The declaration of the variable providing the indirection looks only slightly
+different::
+
+  int (MyClass::*pmi) (int arg) = 0;
+
+This declares a variable named ``pmi`` just as the previous example declared a
+variable named ``pfi``. Since the will be to call a method of an instance of a
+particular class, one must declare that method in a class::
+
+  class MyClass {
+  public:
+    int MyMethod (int arg);
+  };
+
+Given this class declaration, one would then initialize that variable like
+this::
+
+  pmi = &MyClass::MyMethod;
+
+This assigns the address of the code implementing the method to the variable,
+completing the indirection. In order to call a method, the code needs a ``this``
+pointer. This, in turn, means there must be an object of MyClass to refer to. A
+simplistic example of this is just calling a method indirectly (think virtual
+function)::
+
+  int (MyClass::*pmi) (int arg) = 0;  // Declare a PMI
+  pmi = &MyClass::MyMethod;           // Point at the implementation code
+
+  MyClass myClass;                    // Need an instance of the class
+  (myClass.*pmi) (1234);              // Call the method with an object ptr
+
+Just like in the C example, you can use this in an asynchronous call to another
+module which will *call back* using a method and an object pointer. The
+straightforward extension one might consider is to pass a pointer to the object
+and the PMI variable. The module would just do::
+
+  (*objectPtr.*pmi) (1234);
+
+to execute the callback on the desired object.
+
+One might ask at this time, *what's the point*? The called module will have to
+understand the concrete type of the calling object in order to properly make the
+callback. Why not just accept this, pass the correctly typed object pointer and
+do ``object->Method(1234)`` in the code instead of the callback?  This is
+precisely the problem described above. What is needed is a way to decouple the
+calling function from the called class completely. This requirement led to the
+development of the *Functor*.
+
+A functor is the outgrowth of something invented in the 1960s called a closure.
+It is basically just a packaged-up function call, possibly with some state.  
+
+A functor has two parts, a specific part and a generic part, related through
+inheritance. The calling code (the code that executes the callback) will execute
+a generic overloaded ``operator ()`` of a generic functor to cause the callback
+to be called. The called code (the code that wants to be called back) will have
+to provide a specialized implementation of the ``operator ()`` that performs the
+class-specific work that caused the close-coupling problem above.  
+
+With the specific functor and its overloaded ``operator ()`` created, the called
+code then gives the specialized code to the module that will execute the
+callback (the calling code).
+
+The calling code will take a generic functor as a parameter, so an implicit cast
+is done in the function call to convert the specific functor to a generic
+functor.  This means that the calling module just needs to understand the
+generic functor type. It is decoupled from the calling code completely.
+
+The information one needs to make a specific functor is the object pointer and
+the pointer-to-method address. 
+
+The essence of what needs to happen is that the system declares a generic part
+of the functor::
+
+  template <typename T>
+  class Functor
+  {
+  public:
+    virtual int operator() (T arg) = 0;
+  };
+
+The caller defines a specific part of the functor that really is just there to 
+implement the specific ``operator()`` method::
+
+  template <typename T, typename ARG>
+  class SpecificFunctor : public Functor<ARG>
+  {
+  public:
+    SpecificFunctor(T* p, int (T::*_pmi)(ARG arg))
+    {
+      m_p = p;
+      m_pmi = _pmi;
+    }
+
+    virtual int operator() (ARG arg)
+    {
+      (*m_p.*m_pmi)(arg);
+    }
+  private:
+    int (T::*m_pmi)(ARG arg);
+    T* m_p;
+  };
+
+Here is an example of the usage::
+
+  class A
+  {
+  public:
+  A (int ao) : a (a0) {}
+  int Hello (int b0)
+  {
+    std::cout << "Hello from A, a = " << a << " b0 = " << b0 << std::endl;
+  }
+  int a;
+  };
+
+  int main()
+  {
+    A a(10);
+    SpecificFunctor<A, int> sf(&a, &A::Hello);
+    sf(5);
+  }
@@ -0,0 +1,216 @@
+# -*- coding: utf-8 -*-
+#
+# ns-3 documentation build configuration file, created by
+# sphinx-quickstart on Tue Dec 14 09:00:39 2010.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys, os
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#sys.path.insert(0, os.path.abspath('.'))
+
+# -- General configuration -----------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be extensions
+# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
+extensions = ['sphinx.ext.pngmath']
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+# The encoding of source files.
+#source_encoding = 'utf-8-sig'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = u'ns-3'
+copyright = u'2010, ns-3 project'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = 'ns-3-dev'
+# The full version, including alpha/beta/rc tags.
+release = 'ns-3-dev'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#language = None
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+#today = ''
+# Else, today_fmt is used as the format for a strftime call.
+#today_fmt = '%B %d, %Y'
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+exclude_patterns = []
+
+# The reST default role (used for this markup: `text`) to use for all documents.
+#default_role = None
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+#add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+#add_module_names = True
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+#show_authors = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# A list of ignored prefixes for module index sorting.
+#modindex_common_prefix = []
+
+
+# -- Options for HTML output ---------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+html_theme = 'default'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+#html_theme_options = {}
+
+# Add any paths that contain custom themes here, relative to this directory.
+#html_theme_path = []
+
+# The name for this set of Sphinx documents.  If None, it defaults to
+# "<project> v<release> documentation".
+#html_title = None
+
+# A shorter title for the navigation bar.  Default is the same as html_title.
+#html_short_title = None
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+#html_logo = None
+
+# The name of an image file (within the static path) to use as favicon of the
+# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+#html_favicon = None
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+#html_last_updated_fmt = '%b %d, %Y'
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+#html_use_smartypants = True
+
+# Custom sidebar templates, maps document names to template names.
+#html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+#html_additional_pages = {}
+
+# If false, no module index is generated.
+#html_domain_indices = True
+
+# If false, no index is generated.
+#html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+#html_split_index = False
+
+# If true, links to the reST sources are added to the pages.
+#html_show_sourcelink = True
+
+# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
+#html_show_sphinx = True
+
+# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
+#html_show_copyright = True
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> tag referring to it.  The value of this option must be the
+# base URL from which the finished HTML is served.
+#html_use_opensearch = ''
+
+# This is the file name suffix for HTML files (e.g. ".xhtml").
+#html_file_suffix = None
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'ns-3doc'
+
+
+# -- Options for LaTeX output --------------------------------------------------
+
+# The paper size ('letter' or 'a4').
+#latex_paper_size = 'letter'
+
+# The font size ('10pt', '11pt' or '12pt').
+#latex_font_size = '10pt'
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, documentclass [howto/manual]).
+latex_documents = [
+  ('index', 'ns-3-manual.tex', u'ns-3 Manual',
+   u'ns-3 project', 'manual'),
+]
+
+# The name of an image file (relative to this directory) to place at the top of
+# the title page.
+#latex_logo = None
+
+# For "manual" documents, if this is true, then toplevel headings are parts,
+# not chapters.
+#latex_use_parts = False
+
+# If true, show page references after internal links.
+#latex_show_pagerefs = False
+
+# If true, show URL addresses after external links.
+#latex_show_urls = False
+
+# Additional stuff for the LaTeX preamble.
+#latex_preamble = ''
+
+# Documents to append as an appendix to all manuals.
+#latex_appendices = []
+
+# If false, no module index is generated.
+#latex_domain_indices = True
+
+
+# -- Options for manual page output --------------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    ('index', 'ns-3-manual', u'ns-3 Manual',
+     [u'ns-3 project'], 1)
+]
@@ -0,0 +1,137 @@
+.. include:: replace.txt
+
+Enabling Subsets of |ns3| Modules
+---------------------------------
+
+As with most software projects, |ns3| is ever growing larger in terms of number of modules, lines of code, and memory footprint.  Users, however, may only use a few of those modules at a time.  For this reason, users may want to explicitly enable only the subset of the possible |ns3| modules that they actually need for their research.  
+
+This chapter discusses how to enable only the |ns3| modules that you are intersted in using.
+
+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: ::
+
+  libns3-modulename.so
+
+If the module has a test library and test libraries are being built, then ::
+
+  libns3-modulename-test.so
+
+will be built, too.  Other modules that the module depends on and their test libraries will also be built.  
+
+By default, all modules are built in |ns3|.  There are two ways to enable a subset of these modules:
+
+#. Using waf's --enable-modules option
+#. Using the |ns3| configuration file
+
+Enable modules using waf's --enable-modules option
++++++++++++++++++++++++++++++++++++++++++++++++++
+
+To enable only the core module with example and tests, for example,
+try these commands: ::
+
+  ./waf clean
+  ./waf configure --enable-examples --enable-tests --enable-modules=core
+  ./waf build
+  cd build/debug/
+  ls
+
+and the following libraries should be present: ::
+
+  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: ::
+ 
+  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: ::
+
+  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: ::
+
+  31 of 31 tests passed (31 passed, 0 skipped, 0 failed, 0 crashed, 0 valgrind errors)
+
+Enable modules using the |ns3| configuration file
+++++++++++++++++++++++++++++++++++++++++++++++++
+
+A configuration file, .ns3rc, has been added to |ns3| that allows users to specify which modules are to be included in the build.
+
+When enabling a subset of |ns3| modules, the precedence rules are as follows:
+
+#. the --enable-modules configure string overrides any .ns3rc file
+#. the .ns3rc file in the top level |ns3| directory is next consulted, if present
+#. the system searches for ~/.ns3rc if the above two are unspecified
+
+If none of the above limits the modules to be built, all modules that waf knows about will be built.
+
+The maintained version of the .ns3rc file in the |ns3| source code repository resides in the ``utils`` directory.  The reason for this is if it were in the top-level directory of the repository, it would be prone to accidental checkins from maintainers that enable the modules they want to use.  Therefore, users need to manually copy the .ns3rc from the ``utils`` directory to their preferred place (top level directory or their home directory) to enable persistent modular build configuration.
+
+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 .
+
+The .ns3rc file should now be in your top level |ns3| directory, and it contains the following: ::
+
+  #! /usr/bin/env python
+  
+  # A list of the modules that will be enabled when ns-3 is run.
+  # Modules that depend on the listed modules will be enabled also.
+  #
+  # All modules can be enabled by choosing 'all_modules'.
+  modules_enabled = ['all_modules']
+  
+  # Set this equal to true if you want examples to be run.
+  examples_enabled = False
+  
+  # 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: ::
+
+  #! /usr/bin/env python
+  
+  # A list of the modules that will be enabled when ns-3 is run.
+  # Modules that depend on the listed modules will be enabled also.
+  #
+  # All modules can be enabled by choosing 'all_modules'.
+  modules_enabled = ['core']
+  
+  # Set this equal to true if you want examples to be run.
+  examples_enabled = True
+  
+  # Set this equal to true if you want tests to be run.
+  tests_enabled = True
+
+Only the core module will be enabled now if you try these commands: ::
+
+  ./waf clean
+  ./waf configure
+  ./waf build
+  cd build/debug/
+  ls
+
+and the following libraries should be present: ::
+
+  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: ::
+ 
+  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: ::
+
+  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: ::
+
+  31 of 31 tests passed (31 passed, 0 skipped, 0 failed, 0 crashed, 0 valgrind errors)
@@ -0,0 +1,141 @@
+.. include:: replace.txt
+
+Enabling/disabling |ns3| Tests and Examples
+-------------------------------------------
+
+The |ns3| distribution includes many examples and tests that are used to validate the |ns3| system.  Users, however, may not always want these examples and tests to be run for their installation of |ns3|.
+
+This chapter discusses how to build |ns3| with or without its examples and tests.
+
+How to enable/disable examples and tests in |ns3|
+*************************************************
+
+There are 3 ways to enable/disable examples and tests in |ns3|:
+
+#. Using build.py when |ns3| is built for the first time
+#. Using waf once |ns3| has been built
+#. Using the |ns3| configuration file once |ns3| has been built
+
+Enable/disable examples and tests using build.py
++++++++++++++++++++++++++++++++++++++++++++++++
+
+You can use build.py to enable/disable examples and tests when |ns3| is built for the first time.
+
+By default, examples and tests are not built in |ns3|.  
+
+From the ns-3-allinone directory, you can build |ns3| without any
+examples or tests simply by doing: ::
+
+  ./build.py
+
+Running test.py in the top level |ns3| directory now will cause no examples or tests to be run: ::
+ 
+  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
+
+Running test.py in the top level |ns3| directory will cause all of the examples and tests to be run: ::
+ 
+  170 of 170 tests passed (170 passed, 0 skipped, 0 failed, 0 crashed, 0 valgrind errors)
+
+Enable/disable examples and tests using waf
+++++++++++++++++++++++++++++++++++++++++++
+
+You can use waf to enable/disable examples and tests once |ns3| has been built.
+
+By default, examples and tests are not built in |ns3|.  
+
+From the top level |ns3| directory, you can build |ns3| without any
+examples or tests simply by doing: ::
+
+  ./waf configure
+  ./waf build
+
+Running test.py now will cause no examples or tests to be run: ::
+ 
+  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
+
+Running test.py will cause all of the examples and tests to be run: ::
+ 
+  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
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+A configuration file, .ns3rc, has been added to |ns3| that allows users to specify whether examples and tests should be built or not.  You can use this file to enable/disable examples and tests once |ns3| has been built.
+
+When enabling disabling examples and tests, the precedence rules are as follows:
+
+#. the --enable-examples/--disable-examples configure strings override any .ns3rc file
+#. the --enable-tests/--disable-tests configure strings override any .ns3rc file
+#. the .ns3rc file in the top level |ns3| directory is next consulted, if present
+#. the system searches for ~/.ns3rc if the .ns3rc file was not found in the previous step
+
+If none of the above exists, then examples and tests will not be built.
+
+The maintained version of the .ns3rc file in the |ns3| source code repository resides in the ``utils`` directory.  The reason for this is if it were in the top-level directory of the repository, it would be prone to accidental checkins from maintainers that enable the modules they want to use.  Therefore, users need to manually copy the .ns3rc from the ``utils`` directory to their preferred place (top level directory or their home directory) to enable persistent enabling of examples and tests.
+
+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 .
+
+The .ns3rc file should now be in your top level |ns3| directory, and it contains the following: ::
+
+  #! /usr/bin/env python
+  
+  # A list of the modules that will be enabled when ns-3 is run.
+  # Modules that depend on the listed modules will be enabled also.
+  #
+  # All modules can be enabled by choosing 'all_modules'.
+  modules_enabled = ['all_modules']
+  
+  # Set this equal to true if you want examples to be run.
+  examples_enabled = False
+  
+  # Set this equal to true if you want tests to be run.
+  tests_enabled = False
+
+From the top level |ns3| directory, you can build |ns3| without any
+examples or tests simply by doing: ::
+
+  ./waf configure
+  ./waf build
+
+Running test.py now will cause no examples or tests to be run: ::
+ 
+  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: ::
+
+  #! /usr/bin/env python
+  
+  # A list of the modules that will be enabled when ns-3 is run.
+  # Modules that depend on the listed modules will be enabled also.
+  #
+  # All modules can be enabled by choosing 'all_modules'.
+  modules_enabled = ['all_modules']
+  
+  # Set this equal to true if you want examples to be run.
+  examples_enabled = True
+  
+  # Set this equal to true if you want tests to be run.
+  tests_enabled = True
+
+From the top level |ns3| directory, you can build |ns3| with examples
+and tests simply by doing: ::
+
+  ./waf configure
+  ./waf build
+
+Running test.py will cause all of the examples and tests to be run: ::
+ 
+  170 of 170 tests passed (170 passed, 0 skipped, 0 failed, 0 crashed, 0 valgrind errors)
@@ -0,0 +1 @@
+../figures
@@ -0,0 +1,294 @@
+.. include:: replace.txt
+
+Making Plots using the Gnuplot Class
+------------------------------------
+
+There are 2 common methods to make a plot using |ns3| and gnuplot (http://www.gnuplot.info):
+
+#. Create a gnuplot control file using |ns3|'s Gnuplot class.
+#. Create a gnuplot data file using values generated by |ns3|.
+
+This section is about method 1, i.e. it is about how to make a plot using |ns3|'s Gnuplot class.  If you are interested in method 2, see the "A Real Example" subsection under the "Tracing" section in the |ns3| `Tutorial <http://www.nsnam.org/tutorials.html>`_.
+
+Creating Plots Using the Gnuplot Class
+**************************************
+
+The following steps must be taken in order to create a plot using |ns3|'s Gnuplot class:
+
+#. Modify your code so that is uses the Gnuplot class and its functions. 
+#. Run your code so that it creates a gnuplot control file.
+#. Call gnuplot with the name of the gnuplot control file.
+#. View the graphics file that was produced in your favorite graphics viewer.
+
+See the code from the example plots that are discussed below for details on step 1.
+
+An Example Program that Uses the Gnuplot Class
+**********************************************
+
+An example program that uses |ns3|'s Gnuplot class can be found here: ::
+
+  src/tools/examples/gnuplot-example.cc
+
+In order to run this example, do the following: ::
+
+  ./waf shell
+  cd build/debug/src/tools/examples
+  ./gnuplot-example 
+
+This should produce the following gnuplot control files in the directory where the example is located: ::
+
+  plot-2d.plt 
+  plot-2d-with-error-bars.plt
+  plot-3d.plt 
+
+In order to process these gnuplot control files, do the following: ::
+
+  gnuplot plot-2d.plt 
+  gnuplot plot-2d-with-error-bars.plt
+  gnuplot plot-3d.plt 
+
+This should produce the following graphics files in the directory where the example is located: ::
+
+  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: ::
+
+  gimp plot-2d.png 
+  gimp plot-2d-with-error-bars.png
+  gimp plot-3d.png 
+
+An Example 2-Dimensional Plot
+*****************************
+
+The following 2-Dimensional plot 
+
+.. _plot-2d:
+
+.. figure:: figures/plot-2d.*
+
+was created using the following code from gnuplot-example.cc: ::
+
+  using namespace std;
+
+  string fileNameWithNoExtension = "plot-2d";
+  string graphicsFileName        = fileNameWithNoExtension + ".png";
+  string plotFileName            = fileNameWithNoExtension + ".plt";
+  string plotTitle               = "2-D Plot";
+  string dataTitle               = "2-D Data";
+
+  // Instantiate the plot and set its title.
+  Gnuplot plot (graphicsFileName);
+  plot.SetTitle (plotTitle);
+
+  // Make the graphics file, which the plot file will create when it
+  // is used with Gnuplot, be a PNG file.
+  plot.SetTerminal ("png");
+
+  // Set the labels for each axis.
+  plot.SetLegend ("X Values", "Y Values");
+
+  // Set the range for the x axis.
+  plot.AppendExtra ("set xrange [-6:+6]");
+
+  // Instantiate the dataset, set its title, and make the points be
+  // plotted along with connecting lines.
+  Gnuplot2dDataset dataset;
+  dataset.SetTitle (dataTitle);
+  dataset.SetStyle (Gnuplot2dDataset::LINES_POINTS);
+
+  double x;
+  double y;
+
+  // Create the 2-D dataset.
+  for (x = -5.0; x <= +5.0; x += 1.0)
+    {
+      // Calculate the 2-D curve
+      // 
+      //            2
+      //     y  =  x   .
+      //  
+      y = x * x;
+
+      // Add this point.
+      dataset.Add (x, y);
+    }
+
+  // Add the dataset to the plot.
+  plot.AddDataset (dataset);
+
+  // Open the plot file.
+  ofstream plotFile (plotFileName.c_str());
+
+  // Write the plot file.
+  plot.GenerateOutput (plotFile);
+
+  // Close the plot file.
+  plotFile.close ();
+  
+An Example 2-Dimensional Plot with Error Bars
+*********************************************
+
+The following 2-Dimensional plot with error bars in the x and y directions
+
+.. _plot-2d-with-error-bars:
+
+.. figure:: figures/plot-2d-with-error-bars.*
+
+was created using the following code from gnuplot-example.cc: ::
+
+  using namespace std;
+
+  string fileNameWithNoExtension = "plot-2d-with-error-bars";
+  string graphicsFileName        = fileNameWithNoExtension + ".png";
+  string plotFileName            = fileNameWithNoExtension + ".plt";
+  string plotTitle               = "2-D Plot With Error Bars";
+  string dataTitle               = "2-D Data With Error Bars";
+
+  // Instantiate the plot and set its title.
+  Gnuplot plot (graphicsFileName);
+  plot.SetTitle (plotTitle);
+
+  // Make the graphics file, which the plot file will create when it
+  // is used with Gnuplot, be a PNG file.
+  plot.SetTerminal ("png");
+
+  // Set the labels for each axis.
+  plot.SetLegend ("X Values", "Y Values");
+
+  // Set the range for the x axis.
+  plot.AppendExtra ("set xrange [-6:+6]");
+
+  // Instantiate the dataset, set its title, and make the points be
+  // plotted with no connecting lines.
+  Gnuplot2dDataset dataset;
+  dataset.SetTitle (dataTitle);
+  dataset.SetStyle (Gnuplot2dDataset::POINTS);
+
+  // Make the dataset have error bars in both the x and y directions.
+  dataset.SetErrorBars (Gnuplot2dDataset::XY);
+
+  double x;
+  double xErrorDelta;
+  double y;
+  double yErrorDelta;
+
+  // Create the 2-D dataset.
+  for (x = -5.0; x <= +5.0; x += 1.0)
+    {
+      // Calculate the 2-D curve
+      // 
+      //            2
+      //     y  =  x   .
+      //  
+      y = x * x;
+
+      // Make the uncertainty in the x direction be constant and make
+      // the uncertainty in the y direction be a constant fraction of
+      // y's value.
+      xErrorDelta = 0.25;
+      yErrorDelta = 0.1 * y;
+
+      // Add this point with uncertainties in both the x and y
+      // direction.
+      dataset.Add (x, y, xErrorDelta, yErrorDelta);
+    }
+
+  // Add the dataset to the plot.
+  plot.AddDataset (dataset);
+
+  // Open the plot file.
+  ofstream plotFile (plotFileName.c_str());
+
+  // Write the plot file.
+  plot.GenerateOutput (plotFile);
+
+  // Close the plot file.
+  plotFile.close ();
+
+An Example 3-Dimensional Plot
+*****************************
+
+The following 3-Dimensional plot 
+
+.. _plot-3d:
+
+.. figure:: figures/plot-3d.*
+
+was created using the following code from gnuplot-example.cc: ::
+
+  using namespace std;
+
+  string fileNameWithNoExtension = "plot-3d";
+  string graphicsFileName        = fileNameWithNoExtension + ".png";
+  string plotFileName            = fileNameWithNoExtension + ".plt";
+  string plotTitle               = "3-D Plot";
+  string dataTitle               = "3-D Data";
+
+  // Instantiate the plot and set its title.
+  Gnuplot plot (graphicsFileName);
+  plot.SetTitle (plotTitle);
+
+  // Make the graphics file, which the plot file will create when it
+  // is used with Gnuplot, be a PNG file.
+  plot.SetTerminal ("png");
+
+  // Rotate the plot 30 degrees around the x axis and then rotate the
+  // plot 120 degrees around the new z axis.
+  plot.AppendExtra ("set view 30, 120, 1.0, 1.0");
+
+  // Make the zero for the z-axis be in the x-axis and y-axis plane.
+  plot.AppendExtra ("set ticslevel 0");
+
+  // Set the labels for each axis.
+  plot.AppendExtra ("set xlabel 'X Values'");
+  plot.AppendExtra ("set ylabel 'Y Values'");
+  plot.AppendExtra ("set zlabel 'Z Values'");
+
+  // Set the ranges for the x and y axis.
+  plot.AppendExtra ("set xrange [-5:+5]");
+  plot.AppendExtra ("set yrange [-5:+5]");
+
+  // Instantiate the dataset, set its title, and make the points be
+  // connected by lines.
+  Gnuplot3dDataset dataset;
+  dataset.SetTitle (dataTitle);
+  dataset.SetStyle ("with lines");
+
+  double x;
+  double y;
+  double z;
+
+  // Create the 3-D dataset.
+  for (x = -5.0; x <= +5.0; x += 1.0)
+    {
+    for (y = -5.0; y <= +5.0; y += 1.0)
+	{
+	  // Calculate the 3-D surface
+	  // 
+	  //            2      2
+	  //     z  =  x   *  y   .
+	  //  
+	  z = x * x * y * y;
+
+	  // Add this point.
+	  dataset.Add (x, y, z);
+	}
+
+    // The blank line is necessary at the end of each x value's data
+    // points for the 3-D surface grid to work.
+    dataset.AddEmptyLine ();
+    }
+
+  // Add the dataset to the plot.
+  plot.AddDataset (dataset);
+
+  // Open the plot file.
+  ofstream plotFile (plotFileName.c_str());
+
+  // Write the plot file.
+  plot.GenerateOutput (plotFile);
+
+  // Close the plot file.
+  plotFile.close ();
@@ -0,0 +1,37 @@
+.. include:: replace.txt
+
+Helpers
+-------
+
+The above chapters introduced you to various |ns3| programming concepts such as
+smart pointers for reference-counted memory management, attributes, namespaces,
+callbacks, etc. Users who work at this low-level API can interconnect |ns3|
+objects with fine granulariy. However, a simulation program written entirely
+using the low-level API would be quite long and tedious to code. For this
+reason, a separate so-called "helper API" has been overlaid on the core |ns3|
+API. If you have read the |ns3| tutorial, you will already be familiar with the
+helper API, since it is the API that new users are typically introduced to
+first.  In this chapter, we introduce the design philosophy of the helper API
+and contrast it to the low-level API. If you become a heavy user of |ns3|, you
+will likely move back and forth between these APIs even in the same program.
+
+The helper API has a few goals:
+
+#. the rest of ``src/`` has no dependencies on the helper API; anything that can
+   be done with the helper API can be coded also at the low-level API
+#. **Containers:** Often simulations will need to do a number of identical
+   actions to groups of objects. The helper API makes heavy use of containers of
+   similar objects to which similar or identical operations can be performed.
+#. The helper API is not generic; it does not strive to maximize code reuse. So,
+   programming constructs such as polymorphism and templates that achieve code
+   reuse are not as prevalent. For instance, there are separate CsmaNetDevice
+   helpers and PointToPointNetDevice helpers but they do not derive from a
+   common NetDevice base class.
+#. The helper API typically works with stack-allocated (vs. heap-allocated)
+   objects. For some programs, |ns3| users may not need to worry about any low
+   level Object Create or Ptr handling; they can make do with containers of
+   objects and stack-allocated helpers that operate on them.
+
+The helper API is really all about making |ns3| programs easier to write and
+read, without taking away the power of the low-level interface. The rest of this
+chapter provides some examples of the programming conventions of the helper API.
@@ -0,0 +1,60 @@
+.. include:: replace.txt
+
+How to write tests
+------------------
+
+A primary goal of the ns-3 project is to help users to improve the 
+validity and credibility of their results.  There are many elements
+to obtaining valid models and simulations, and testing is a major
+component.  If you contribute models or examples to ns-3, you may
+be asked to contribute test code.  Models that you contribute will be
+used for many years by other people, who probably have no idea upon
+first glance whether the model is correct.  The test code that you
+write for your model will help to avoid future regressions in
+the output and will aid future users in understanding the validity
+and bounds of applicability of your models.
+
+There are many ways to test that a model is valid.  In this chapter,
+we hope to cover some common cases that can be used as a guide to
+writing new tests.
+
+Sample TestSuite skeleton
+*************************
+
+When starting from scratch (i.e. not adding a TestCase to an existing
+TestSuite), these things need to be decided up front:
+
+* What the test suite will be called 
+* What type of test it will be (Build Verification Test, Unit Test,
+  System Test, or Performance Test)
+* Where the test code will live (either in an existing ns-3 module or
+  separately in src/test/ directory).  You will have to edit the wscript
+  file in that directory to compile your new code, if it is a new file.
+
+See the file ``src/template/test/sample-test-suite.cc`` and corresponding
+wscript file in that directory for a simple example, and see the directories
+under ``src/test`` for more complicated examples.
+
+*The rest of this chapter remains to be written*
+
+How to add an example program to the test suite
+***********************************************
+
+Testing for boolean outcomes
+****************************
+
+Testing outcomes when randomness is involved
+********************************************
+
+Testing output data against a known distribution
+************************************************
+
+Providing non-trivial input vectors of data
+*******************************************
+
+Storing and referencing non-trivial output data
+***********************************************
+
+Presenting your output test data
+********************************
+
@@ -0,0 +1,32 @@
+.. only:: html or latex
+
+ns-3 Manual
+===========
+
+This is the *ns-3 Manual*. Primary documentation for the ns-3 project is 
+available in five forms:
+
+* `ns-3 Doxygen <http://www.nsnam.org/doxygen/index.html>`_: Documentation of the public APIs of the simulator
+* Tutorial, Manual *(this document)*, and Model Library for the `latest release <http://www.nsnam.org/documentation/latest/>`_ and `development tree <http://www.nsnam.org/ns-3-dev/documentation/>`_
+* `ns-3 wiki <http://www.nsnam.org/wiki/index.php/Main_Page>`_
+
+This document is written in `reStructuredText <http://docutils.sourceforge.net/rst.html>`_ for `Sphinx <http://sphinx.pocoo.org/>`_ and is maintained in the
+``doc/manual`` directory of ns-3's source code.
+
+.. toctree::
+   :maxdepth: 2
+
+   organization
+   random-variables
+   callbacks
+   object-model
+   attributes
+   object-names
+   logging
+   tracing
+   realtime
+   helpers
+   gnuplot
+   python
+   tests
+   support
@@ -0,0 +1,7 @@
+.. include:: replace.txt
+
+Logging
+-------
+
+*This chapter not yet written.  For now, the ns-3 tutorial contains logging
+information.*
@@ -0,0 +1,569 @@
+.. include:: replace.txt
+
+Creating a new ns-3 model
+-------------------------
+
+This chapter walks through the design process of an |ns3| model.  In many
+research cases, users will not be satisfied to merely adapt existing models, but
+may want to extend the core of the simulator in a novel way. We will use the
+example of adding an ErrorModel to a simple |ns3| link as a motivating example
+of how one might approach this problem and proceed through a design and
+implementation.
+
+Design-approach
+***************
+
+Consider how you want it to work; what should it do. Think about these things:
+
+* *functionality:*  What functionality should it have?  What attributes or
+  configuration is exposed to the user?
+* *reusability:*  How much should others be able to reuse my design?  Can I
+  reuse code from |ns2| to get started?  How does a user integrate the model
+  with the rest of another simulation?
+* *dependencies:*  How can I reduce the introduction of outside dependencies on
+  my new code as much as possible (to make it more modular)?  For instance,
+  should I avoid any dependence on IPv4 if I want it to also be used by IPv6?
+  Should I avoid any dependency on IP at all?
+
+Do not be hesitant to contact the ns-3-users or ns-developers list if you have
+questions. In particular, it is important to think about the public API of your
+new model and ask for feedback. It also helps to let others know of your work in
+case you are interested in collaborators.
+
+Example: ErrorModel
+++++++++++++++++++
+
+An error model exists in |ns2|. It allows packets to be passed to a stateful
+object that determines, based on a random variable, whether the packet is
+corrupted.  The caller can then decide what to do with the packet (drop it,
+etc.).
+
+The main API of the error model is a function to pass a packet to, and the
+return value of this function is a boolean that tells the caller whether any
+corruption occurred.  Note that depending on the error model, the packet data
+buffer may or may not be corrupted.  Let's call this function "IsCorrupt()".
+
+So far, in our design, we have:::
+
+    class ErrorModel
+    {
+    public:
+     /**
+      * \returns true if the Packet is to be considered as errored/corrupted
+      * \param pkt Packet to apply error model to
+      */
+      bool IsCorrupt (Ptr<Packet> pkt);
+    };
+
+Note that we do not pass a const pointer, thereby allowing the function to
+modify the packet if IsCorrupt() returns true. Not all error models will
+actually modify the packet; whether or not the packet data buffer is corrupted
+should be documented.
+
+We may also want specialized versions of this, such as in |ns2|, so although it
+is not the only design choice for polymorphism, we assume that we will subclass
+a base class ErrorModel for specialized classes, such as RateErrorModel,
+ListErrorModel, etc, such as is done in |ns2|.
+
+You may be thinking at this point, "Why not make IsCorrupt() a virtual method?".
+That is one approach; the other is to make the public non-virtual function
+indirect through a private virtual function (this in C++ is known as the non
+virtual interface idiom and is adopted in the |ns3| ErrorModel class).  
+
+Next, should this device have any dependencies on IP or other protocols?  We do
+not want to create dependencies on Internet protocols (the error model should be
+applicable to non-Internet protocols too), so we'll keep that in mind later.
+
+Another consideration is how objects will include this error model.  We envision
+putting an explicit setter in certain NetDevice implementations, for example.::
+
+  /**
+   * Attach a receive ErrorModel to the PointToPointNetDevice.
+   *
+   * The PointToPointNetDevice may optionally include an ErrorModel in
+   * the packet receive chain.
+   *
+   * @see ErrorModel
+   * @param em Ptr to the ErrorModel.
+   */
+  void PointToPointNetDevice::SetReceiveErrorModel(Ptr<ErrorModel> em);
+
+Again, this is not the only choice we have (error models could be aggregated to
+lots of other objects), but it satisfies our primary use case, which is to allow
+a user to force errors on otherwise successful packet transmissions, at the
+NetDevice level.
+
+After some thinking and looking at existing |ns2| code, here is a sample API of
+a base class and first subclass that could be posted for initial review:::
+
+    class ErrorModel 
+    {
+    public:
+      ErrorModel ();
+      virtual ~ErrorModel ();
+      bool IsCorrupt (Ptr<Packet> pkt);
+      void Reset (void);
+      void Enable (void);
+      void Disable (void);
+      bool IsEnabled (void) const;
+    private:
+      virtual bool DoCorrupt (Ptr<Packet> pkt) = 0;
+      virtual void DoReset (void) = 0;
+    };
+
+    enum ErrorUnit
+      {
+        EU_BIT,
+        EU_BYTE,
+        EU_PKT
+      };
+
+    // Determine which packets are errored corresponding to an underlying
+    // random variable distribution, an error rate, and unit for the rate.
+    class RateErrorModel : public ErrorModel
+    {
+    public:
+      RateErrorModel ();
+      virtual ~RateErrorModel ();
+      enum ErrorUnit GetUnit (void) const;
+      void SetUnit (enum ErrorUnit error_unit);
+      double GetRate (void) const;
+      void SetRate (double rate);
+      void SetRandomVariable (const RandomVariable &ranvar);
+    private:
+      virtual bool DoCorrupt (Ptr<Packet> pkt);
+      virtual void DoReset (void);
+    };
+
+
+Scaffolding
+***********
+
+Let's say that you are ready to start implementing; you have a fairly clear
+picture of what you want to build, and you may have solicited some initial
+review or suggestions from the list.  One way to approach the next step
+(implementation) is to create scaffolding and fill in the details as the design
+matures.  
+
+This section walks through many of the steps you should consider to define
+scaffolding, or a non-functional skeleton of what your model will eventually
+implement. It is usually good practice to not wait to get these details
+integrated at the end, but instead to plumb a skeleton of your model into the
+system early and then add functions later once the API and integration seems
+about right.  
+
+Note that you will want to modify a few things in the below presentation for
+your model since if you follow the error model verbatim, the code you produce
+will collide with the existing error model. The below is just an outline of how
+ErrorModel was built that you can adapt to other models.
+
+Review the ns-3 coding style document
+++++++++++++++++++++++++++++++++++++
+
+At this point, you may want to pause and read the |ns3| coding style document,
+especially if you are considering to contribute your code back to the project.
+The coding style document is linked off the main project page: `ns-3 coding
+style <http://www.nsnam.org/codingstyle.html>`_.
+
+Decide where in the source tree the model will reside in
++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+All of the |ns3| model source code is in the directory ``src/``.  You will need
+to choose which subdirectory it resides in. If it is new model code of some
+sort, it makes sense to put it into the ``src/`` directory somewhere,
+particularly for ease of integrating with the build system.
+
+In the case of the error model, it is very related to the packet class, so it
+makes sense to implement this in the ``src/network/model`` directory where |ns3|
+packets are implemented.  
+
+waf and wscript
+++++++++++++++
+
+|ns3| uses the `Waf <http://www.freehackers.org/~tnagy/waf.html>`_ build system.
+You will want to integrate your new |ns3| uses the Waf build system. You will
+want to integrate your new source files into this system. This requires that you
+add your files to the ``wscript`` file found in each directory.  
+
+Let's start with empty files error-model.h and error-model.cc, and add this to
+``src/network/wscript``. It is really just a matter of adding the .cc file to the
+rest of the source files, and the .h file to the list of the header files. 
+
+Now, pop up to the top level directory and type "./test.py".  You
+shouldn't have broken anything by this operation.
+
+include guards
++++++++++++++
+
+Next, let's add some `include guards
+<http://en.wikipedia.org/wiki/Include_guard>`_ in our header file.::
+
+    #ifndef ERROR_MODEL_H
+    #define ERROR_MODEL_H
+    ...
+    #endif
+
+namespace ns3
+++++++++++++
+
+|ns3| uses the |ns3| `namespace
+<http://en.wikipedia.org/wiki/Namespace_(computer_science)#Use_in_common_languages>`_
+to isolate its symbols from other namespaces. Typically, a user will next put
+an |ns3| namespace block in both the cc and h file.::
+
+    namespace ns3 {
+    ...
+    }
+
+At this point, we have some skeletal files in which we can start defining
+our new classes. The header file looks like this:::
+
+    #ifndef ERROR_MODEL_H
+    #define ERROR_MODEL_H
+
+    namespace ns3 {
+
+    } // namespace ns3
+    #endif
+
+while the ``error-model.cc`` file simply looks like this:::
+
+    #include "error-model.h"
+
+    namespace ns3 {
+
+    } // namespace ns3
+
+These files should compile since they don't really have any contents.  We're now
+ready to start adding classes.
+
+Initial Implementation
+**********************
+
+At this point, we're still working on some scaffolding, but we can begin to
+define our classes, with the functionality to be added later.
+
+use of class Object?
++++++++++++++++++++
+
+This is an important design step; whether to use class :cpp:class:`Object` as a
+base class for your new classes.
+
+As described in the chapter on the |ns3| :ref:`Object model`, classes that
+inherit from class :cpp:class:`Object` get special properties:
+
+* the |ns3| type and attribute system (see :ref:`Attributes`)
+* an object aggregation system
+* a smart-pointer reference counting system (class Ptr)
+
+Classes that derive from class :cpp:class:`ObjectBase`} get the first two
+properties above, but do not get smart pointers. Classes that derive from class
+:cpp:class:`RefCountBase` get only the smart-pointer reference counting system.
+
+In practice, class :cpp:class:`Object` is the variant of the three above that
+the |ns3| developer will most commonly encounter.
+
+In our case, we want to make use of the attribute system, and we will be passing
+instances of this object across the |ns3| public API, so class
+:cpp:class:`Object` is appropriate for us.
+
+initial classes
+++++++++++++++
+
+One way to proceed is to start by defining the bare minimum functions and see if
+they will compile. Let's review what all is needed to implement when we derive
+from class Object.::
+
+    #ifndef ERROR_MODEL_H
+    #define ERROR_MODEL_H
+
+    #include "ns3/object.h"
+
+    namespace ns3 {
+      
+    class ErrorModel : public Object
+    {
+    public:
+      static TypeId GetTypeId (void);
+
+      ErrorModel ();
+      virtual ~ErrorModel ();
+    };
+
+    class RateErrorModel : public ErrorModel
+    {
+    public:
+      static TypeId GetTypeId (void);
+     
+      RateErrorModel ();
+      virtual ~RateErrorModel ();
+    };
+    #endif
+
+
+A few things to note here. We need to include ``object.h``. The convention in
+|ns3| is that if the header file is co-located in the same directory, it may be
+included without any path prefix. Therefore, if we were implementing ErrorModel
+in ``src/core/model`` directory, we could have just said "``#include "object.h"``".
+But we are in ``src/network/model``, so we must include it as "``#include
+"ns3/object.h"``". Note also that this goes outside the namespace declaration.
+ 
+Second, each class must implement a static public member function called
+``GetTypeId (void)``.  
+
+Third, it is a good idea to implement constructors and destructors rather than
+to let the compiler generate them, and to make the destructor virtual. In C++,
+note also that copy assignment operator and copy constructors are auto-generated
+if they are not defined, so if you do not want those, you should implement those
+as private members. This aspect of C++ is discussed in Scott Meyers' Effective
+C++ book. item 45. 
+
+Let's now look at some corresponding skeletal implementation code in the .cc 
+file.::
+
+    #include "error-model.h"
+
+    namespace ns3 {
+
+    NS_OBJECT_ENSURE_REGISTERED (ErrorModel);
+
+    TypeId ErrorModel::GetTypeId (void)
+    {
+      static TypeId tid = TypeId ("ns3::ErrorModel")
+        .SetParent<Object> ()
+        ;
+      return tid;
+    }
+
+    ErrorModel::ErrorModel ()
+    { 
+    }
+
+    ErrorModel::~ErrorModel ()
+    { 
+    }
+
+    NS_OBJECT_ENSURE_REGISTERED (RateErrorModel);
+
+    TypeId RateErrorModel::GetTypeId (void)
+    {
+      static TypeId tid = TypeId ("ns3::RateErrorModel")
+        .SetParent<ErrorModel> ()
+        .AddConstructor<RateErrorModel> ()
+        ;
+      return tid;
+    }
+
+    RateErrorModel::RateErrorModel ()
+    {
+    } 
+
+    RateErrorModel::~RateErrorModel ()
+    {
+    }
+
+What is the ``GetTypeId (void)`` function? This function does a few things.  It
+registers a unique string into the TypeId system. It establishes  the hierarchy
+of objects in the attribute system (via ``SetParent``). It also declares that
+certain objects can be created via the object creation framework
+(``AddConstructor``).  
+
+The macro ``NS_OBJECT_ENSURE_REGISTERED (classname)`` is needed also once for
+every class that defines a new GetTypeId method, and it does the actual
+registration of the class into the system.  The :ref:`Object model` chapter
+discusses this in more detail.
+
+how to include files from elsewhere
+++++++++++++++++++++++++++++++++++
+
+log component 
+++++++++++++
+
+*Here, write a bit about adding |ns3| logging macros. Note that
+LOG_COMPONENT_DEFINE is done outside the namespace ns3*
+
+constructor, empty function prototypes
++++++++++++++++++++++++++++++++++++++
+
+key variables (default values, attributes)
++++++++++++++++++++++++++++++++++++++++++
+
+test program 1
++++++++++++++
+
+Object Framework
++++++++++++++++
+
+::
+    static const ClassId cid;
+
+    const InterfaceId ErrorModel::iid =
+      MakeInterfaceId ("ErrorModel", Object::iid);
+
+    const ClassId ErrorModel::cid =
+      MakeClassId<ErrorModel> ("ErrorModel", ErrorModel::iid);
+
+Adding-a-sample-script
+**********************
+
+At this point, one may want to try to take the basic scaffolding defined above
+and add it into the system. Performing this step now allows one to use a simpler
+model when plumbing into the system and may also reveal whether any design or
+API modifications need to be made. Once this is done, we will return to building
+out the functionality of the ErrorModels themselves.
+
+Add basic support in the class
++++++++++++++++++++++++++++++
+
+::
+
+    point-to-point-net-device.h
+      class ErrorModel;
+      
+      /**
+       * Error model for receive packet events
+       */
+      Ptr<ErrorModel> m_receiveErrorModel;
+      
+Add Accessor
++++++++++++
+
+::
+
+    void
+    PointToPointNetDevice::SetReceiveErrorModel (Ptr<ErrorModel> em)
+    {
+      NS_LOG_FUNCTION (this << em);
+      m_receiveErrorModel = em;
+    } 
+
+       .AddAttribute ("ReceiveErrorModel",
+                       "The receiver error model used to simulate packet loss",
+                       PointerValue (),
+                       MakePointerAccessor (&PointToPointNetDevice::m_receiveErrorModel),
+                       MakePointerChecker<ErrorModel> ())
+
+Plumb into the system
+++++++++++++++++++++
+
+::
+
+    void PointToPointNetDevice::Receive (Ptr<Packet> packet)
+    {
+      NS_LOG_FUNCTION (this << packet);
+      uint16_t protocol = 0;
+      
+      if (m_receiveErrorModel && m_receiveErrorModel->IsCorrupt (packet) )
+        {
+    //  
+    // If we have an error model and it indicates that it is time to lose a
+    // corrupted packet, don't forward this packet up, let it go. 
+    // 
+          m_dropTrace (packet);
+        } 
+      else
+        {
+    //  
+    // Hit the receive trace hook, strip off the point-to-point protocol header
+    // and forward this packet up the protocol stack.
+    //     
+          m_rxTrace (packet);
+          ProcessHeader(packet, protocol);
+          m_rxCallback (this, packet, protocol, GetRemote ());
+          if (!m_promiscCallback.IsNull ())
+            {           m_promiscCallback (this, packet, protocol, GetRemote (), 
+                          GetAddress (), NetDevice::PACKET_HOST);
+            }
+        }
+    }
+
+Create null functional script
+++++++++++++++++++++++++++++
+
+::
+
+    simple-error-model.cc
+
+      // Error model
+      // We want to add an error model to node 3's NetDevice
+      // We can obtain a handle to the NetDevice via the channel and node
+      // pointers
+      Ptr<PointToPointNetDevice> nd3 = PointToPointTopology::GetNetDevice
+        (n3, channel2);
+      Ptr<ErrorModel> em = Create<ErrorModel> ();
+      nd3->SetReceiveErrorModel (em);
+
+
+    bool
+    ErrorModel::DoCorrupt (Packet& p)
+    {
+      NS_LOG_FUNCTION;
+      NS_LOG_UNCOND("Corrupt!");
+      return false;
+    }
+
+At this point, we can run the program with our trivial ErrorModel plumbed into
+the receive path of the PointToPointNetDevice. It prints out the string
+"Corrupt!" for each packet received at node n3. Next, we return to the error
+model to add in a subclass that performs more interesting error modeling.
+
+Add subclass
+************
+
+The trivial base class ErrorModel does not do anything interesting, but it
+provides a useful base class interface (Corrupt () and Reset ()), forwarded to
+virtual functions that can be subclassed. Let's next consider what we call a
+BasicErrorModel which is based on the |ns2| ErrorModel class (in
+``ns-2/queue/errmodel.{cc,h}``).
+
+What properties do we want this to have, from a user interface perspective? We
+would like for the user to be able to trivially swap out the type of ErrorModel
+used in the NetDevice. We would also like the capability to set configurable
+parameters.
+
+Here are a few simple requirements we will consider:
+
+* Ability to set the random variable that governs the losses (default is
+  UniformVariable)
+* Ability to set the unit (bit, byte, packet, time) of granularity over which
+  errors are applied.
+* Ability to set the rate of errors (e.g. 10^-3) corresponding to the above unit
+  of granularity.
+* Ability to enable/disable (default is enabled)
+
+How to subclass
+++++++++++++++
+
+We declare BasicErrorModel to be a subclass of ErrorModel as follows,::
+
+    class BasicErrorModel : public ErrorModel
+    {
+    public:
+      static TypeId GetTypeId (void);
+      ...
+    private:
+      // Implement base class pure virtual functions
+      virtual bool DoCorrupt (Ptr<Packet> p);
+      virtual bool DoReset (void);
+      ...
+    }
+
+and configure the subclass GetTypeId function by setting a unique TypeId string
+and setting the Parent to ErrorModel:::
+
+    TypeId RateErrorModel::GetTypeId (void)
+    {
+      static TypeId tid = TypeId ("ns3::RateErrorModel")
+        .SetParent<ErrorModel> ()
+        .AddConstructor<RateErrorModel> ()
+      ...
+
+Build-core-functions-and-unit-tests
+***********************************
+
+assert macros
+++++++++++++
+
+Writing unit tests
++++++++++++++++++
+
@@ -0,0 +1,285 @@
+.. include:: replace.txt
+
+Adding a New Module to |ns3|
+----------------------------
+
+When you have created a group of related classes, examples, and tests,
+they can be combined together into an |ns3| module so that they can be
+used with existing |ns3| modules and by other researchers.
+
+This chapter walks you through the steps necessary to add a new module
+to |ns3|.
+
+Step 1 - Familiarize yourself with the module layout
+****************************************************
+
+All modules can be found in the ``src`` directory.  Each module can be
+found in a directory that has the same name as the module.  For
+example, the spectrum module can be found here: ::
+
+  src/spectrum
+
+A prototypical module has the following directory structure and
+required files: ::
+
+  src/
+        module-name/
+                bindings/
+                doc/
+                examples/
+                        wscript
+                helper/
+                model/
+                test/
+                        examples-to-run.py
+                wscript
+
+Not all directories will be present in each module.
+
+Step 2 - Create your new module based on the template module
+************************************************************
+
+A python program is provided in the source directory that will create a skeleton for a new module ::
+
+  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: ::
+
+  ./create-module.py new-module
+
+Next, cd into ``new-module``; you will find this directory layout: ::
+
+  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: ::
+
+  def build(bld):
+      module = bld.create_ns3_module('new-module', ['core'])
+
+and after editing: ::
+
+  def build(bld):
+      module = bld.create_ns3_module('new-module', ['internet', 'mobility', 'aodv'])
+
+Your module will most likely have model source files.  Initial skeletons (which will compile successfully) are created in ``model/new-module.cc`` and ``model/new-module.h``.  
+
+If your module will have helper source files, then they will go into the helper/ directory; again, initial skeletons are created in that directory.
+
+Finally, it is good practice to write tests.  A skeleton test suite and test case is created in the test/ directory.  The below constructor specifies that it will be a unit test named 'new-module':  ::
+
+  New-moduleTestSuite::New-moduleTestSuite ()
+    : TestSuite ("new-module", UNIT)
+  {
+    AddTestCase (new New-moduleTestCase1);
+  }
+
+Step 3 - Adding to your module's source files
+*********************************************
+
+If your new module has model and/or helper source files, then they
+must be specified in your  ::
+
+  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 ::
+
+  src/spectrum/wscript
+
+with the following list of source files: ::
+
+    module.source = [
+        'model/spectrum-model.cc',
+        'model/spectrum-value.cc',
+               .
+	       .
+	       .
+        'model/microwave-oven-spectrum-value-helper.cc',
+        'helper/spectrum-helper.cc',
+        'helper/adhoc-aloha-noack-ideal-phy-helper.cc',
+        'helper/waveform-generator-helper.cc',
+        'helper/spectrum-analyzer-helper.cc',
+        ]
+
+Step 4 - Specify your module's header files
+*******************************************
+
+If your new module has model and/or helper header files, then they
+must be specified in your  ::
+
+  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  ::
+
+  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: ::
+
+    headers = bld.new_task_gen(features=['ns3header'])
+
+    headers.module = 'spectrum'
+
+    headers.source = [
+        'model/spectrum-model.h',
+        'model/spectrum-value.h',
+               .
+	       .
+	       .
+        'model/microwave-oven-spectrum-value-helper.h',
+        'helper/spectrum-helper.h',
+        'helper/adhoc-aloha-noack-ideal-phy-helper.h',
+        'helper/waveform-generator-helper.h',
+        'helper/spectrum-analyzer-helper.h',
+        ]
+
+Step 5 - Specify your module's tests
+************************************
+
+If your new module has tests, then they must be specified in your ::
+
+  src/new-module/wscript
+
+file by modifying it with your text editor.
+
+As an example, the tests for the spectrum module are specified in ::
+
+  src/spectrum/wscript
+
+with the following function call and list of test suites: ::
+
+    module_test = bld.create_ns3_module_test_library('spectrum')
+
+    module_test.source = [
+        'test/spectrum-interference-test.cc',
+        'test/spectrum-value-test.cc',
+        ]
+
+
+Step 6 - Specify your module's examples
+***************************************
+
+If your new module has examples, then they must be specified in your ::
+
+  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 ::
+
+  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: ::
+
+    obj = bld.create_ns3_program('main-callback', ['core'])
+    obj.source = 'main-callback.cc'
+
+    obj = bld.create_ns3_program('sample-simulator', ['core'])
+    obj.source = 'sample-simulator.cc'
+
+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: ::
+
+    bld.register_ns3_script('sample-simulator.py', ['core'])
+
+Step 7 - Specify which of your module's examples should be run as tests
+***********************************************************************
+
+The test framework can also be instrumented to run example programs to
+try to catch regressions in the examples.  However, not all examples
+are suitable for regression tests.  A file called ``examples-to-run.py``
+that exists in each module's test directory can control the invocation
+of the examples when the test framework runs.
+
+As an example, the examples that are run by ``test.py`` for the core module are specified in  ::
+
+  src/core/test/examples-to-run.py
+
+using the following two lists of C++ and Python examples: ::
+
+  # 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
+  #
+  #     (example_name, do_run, do_valgrind_run).
+  #
+  # See test.py for more information.
+  cpp_examples = [
+      ("main-attribute-value", "True", "True"),
+      ("main-callback", "True", "True"),
+      ("sample-simulator", "True", "True"),
+      ("main-ptr", "True", "True"),
+      ("main-random-variable", "True", "True"),
+      ("sample-random-variable", "True", "True"),
+  ]
+  
+  # A list of Python examples to run in order to ensure that they remain
+  # runnable over time.  Each tuple in the list contains
+  #
+  #     (example_name, do_run).
+  #
+  # See test.py for more information.
+  python_examples = [
+      ("sample-simulator.py", "True"),
+  ]
+
+Each tuple in the C++ list of examples to run contains ::
+
+    (example_name, do_run, do_valgrind_run)
+
+where example_name is the executable to be run, do_run is a
+condition under which to run the example, and do_valgrind_run is
+a condition under which to run the example under valgrind.  This
+is needed because NSC causes illegal instruction crashes with
+some tests when they are run under valgrind.
+
+Note that the two conditions are Python statements that
+can depend on waf configuration variables.  For example, ::
+
+    ("tcp-nsc-lfn", "NSC_ENABLED == True", "NSC_ENABLED == False"),
+
+Each tuple in the Python list of examples to run contains ::
+
+    (example_name, do_run)
+
+where example_name is the Python script to be run and
+do_run is a condition under which to run the example.
+
+Note that the condition is a Python statement that can
+depend on waf configuration variables.  For example, ::
+
+    ("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 ::
+
+  src/new-module/test/examples-to-run.py
+
+file by modifying it with your text editor.  These examples are run by
+test.py.
+
+Step 8 - Build and test your new module
+***************************************
+
+You can now build and test your module as normal: ::
+
+  ./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.
@@ -0,0 +1,290 @@
+.. include:: replace.txt
+
+Object model
+------------
+
+|ns3| is fundamentally a C++ object system. Objects can be declared and
+instantiated as usual, per C++ rules. |ns3| also adds some features to
+traditional C++ objects, as described below, to provide greater functionality
+and features. This manual chapter is intended to introduce the reader to the
+|ns3| object model.
+
+This section describes the C++ class design for |ns3| objects. In brief,
+several design patterns in use include classic object-oriented design
+(polymorphic interfaces and implementations), separation of interface and
+implementation, the non-virtual public interface design pattern, an object
+aggregation facility, and reference counting for memory management. Those
+familiar with component models such as COM or Bonobo will recognize elements of
+the design in the |ns3| object aggregation model, although the |ns3| design is
+not strictly in accordance with either.
+
+Object-oriented behavior
+************************
+
+C++ objects, in general, provide common object-oriented capabilities 
+(abstraction, encapsulation, inheritance, and polymorphism) that are part 
+of classic object-oriented design. |ns3| objects make use of these 
+properties; for instance:::
+
+    class Address
+    {
+    public:
+      Address ();
+      Address (uint8_t type, const uint8_t *buffer, uint8_t len);
+      Address (const Address & address);
+      Address &operator = (const Address &address);
+      ...
+    private:
+      uint8_t m_type;
+      uint8_t m_len;
+      ...
+    };
+
+Object base classes
+*******************
+
+There are three special base classes used in |ns3|. Classes that inherit
+from these base classes can instantiate objects with special properties.
+These base classes are:
+
+* class :cpp:class:`Object`
+* class :cpp:class:`ObjectBase`
+* class :cpp:class:`SimpleRefCount`
+
+It is not required that |ns3| objects inherit from these class, but 
+those that do get special properties. Classes deriving from 
+class :cpp:class:`Object` get the following properties.
+
+* the |ns3| type and attribute system (see :ref:`Attributes`)
+* an object aggregation system
+* a smart-pointer reference counting system (class Ptr)
+
+Classes that derive from class :cpp:class:`ObjectBase` get the first two
+properties above, but do not get smart pointers. Classes that derive from class
+:cpp:class:`SimpleRefCount`: get only the smart-pointer reference counting
+system.
+
+In practice, class :cpp:class:`Object` is the variant of the three above that
+the |ns3| developer will most commonly encounter.
+
+Memory management and class Ptr
+*******************************
+
+Memory management in a C++ program is a complex process, and is often done
+incorrectly or inconsistently. We have settled on a reference counting design
+described as follows.
+
+All objects using reference counting maintain an internal reference count to
+determine when an object can safely delete itself. Each time that a pointer is
+obtained to an interface, the object's reference count is incremented by calling
+``Ref()``. It is the obligation of the user of the pointer to explicitly
+``Unref()`` the pointer when done. When the reference count falls to zero, the
+object is deleted.
+
+* When the client code obtains a pointer from the object itself through object
+  creation, or via GetObject, it does not have to increment the reference count.   
+* When client code obtains a pointer from another source (e.g., copying a
+  pointer) it must call ``Ref()`` to increment the reference count.
+* All users of the object pointer must call ``Unref()`` to release the
+  reference.
+
+The burden for calling :cpp:func:`Unref()` is somewhat relieved by the use of
+the reference counting smart pointer class described below. 
+
+Users using a low-level API who wish to explicitly allocate
+non-reference-counted objects on the heap, using operator new, are responsible
+for deleting such objects.
+
+Reference counting smart pointer (Ptr)
++++++++++++++++++++++++++++++++++++++
+
+Calling ``Ref()`` and ``Unref()`` all the time would be cumbersome, so |ns3|
+provides a smart pointer class :cpp:class:`Ptr` similar to
+:cpp:class:`Boost::intrusive_ptr`. This smart-pointer class assumes that the
+underlying type provides a pair of ``Ref`` and ``Unref`` methods that are
+expected to increment and decrement the internal refcount of the object
+instance.  
+
+This implementation allows you to manipulate the smart pointer as if it was a
+normal pointer: you can compare it with zero, compare it against other pointers,
+assign zero to it, etc.
+
+It is possible to extract the raw pointer from this smart pointer with the
+:cpp:func:`GetPointer` and :cpp:func:`PeekPointer` methods.
+
+If you want to store a newed object into a smart pointer, we recommend you to
+use the CreateObject template functions to create the object and store it in a
+smart pointer to avoid memory leaks. These functions are really small
+convenience functions and their goal is just to save you a small bit of typing.
+
+CreateObject and Create
+++++++++++++++++++++++
+
+Objects in C++ may be statically, dynamically, or automatically created.  This
+holds true for |ns3| also, but some objects in the system have some additional
+frameworks available. Specifically, reference counted objects are usually
+allocated using a templated Create or CreateObject method, as follows.
+
+For objects deriving from class :cpp:class:`Object`:::
+
+    Ptr<WifiNetDevice> device = CreateObject<WifiNetDevice> ();
+
+Please do not create such objects using ``operator new``; create them using
+:cpp:func:`CreateObject()` instead.
+
+For objects deriving from class :cpp:class:`SimpleRefCount`, or other objects
+that support usage of the smart pointer class, a templated helper function is
+available and recommended to be used:::
+
+    Ptr<B> b = Create<B> ();
+
+This is simply a wrapper around operator new that correctly handles the
+reference counting system.
+
+In summary, use ``Create<B>`` if B is not an object but just uses reference
+counting (e.g. :cpp:class:`Packet`), and use ``CreateObject<B>`` if B derives
+from :cpp:class:`ns3::Object`.
+
+Aggregation
+++++++++++
+
+The |ns3| object aggregation system is motivated in strong part by a recognition
+that a common use case for |ns2| has been the use of inheritance and
+polymorphism to extend protocol models. For instance, specialized versions of
+TCP such as RenoTcpAgent derive from (and override functions from) class
+TcpAgent.  
+
+However, two problems that have arisen in the |ns2| model are downcasts and
+"weak base class." Downcasting refers to the procedure of using a base class
+pointer to an object and querying it at run time to find out type information,
+used to explicitly cast the pointer to a subclass pointer so that the subclass
+API can be used. Weak base class refers to the problems that arise when a class
+cannot be effectively reused (derived from) because it lacks necessary
+functionality, leading the developer to have to modify the base class and
+causing proliferation of base class API calls, some of which may not be
+semantically correct for all subclasses.
+
+|ns3| is using a version of the query interface design pattern to avoid these
+problems. This design is based on elements of the `Component Object Model
+<http://en.wikipedia.org/wiki/Component_Object_Model>`_ and `GNOME Bonobo
+<http://en.wikipedia.org/wiki/Bonobo_(component_model)>`_ although full
+binary-level compatibility of replaceable components is not supported and we
+have tried to simplify the syntax and impact on model developers.  
+
+Aggregation example
+++++++++++++++++++
+
+:cpp:class:`Node` is a good example of the use of aggregation in |ns3|.  Note
+that there are not derived classes of Nodes in |ns3| such as class
+:cpp:class:`InternetNode`.  Instead, components (protocols) are aggregated to a
+node. Let's look at how some Ipv4 protocols are added to a node.::
+
+    static void
+    AddIpv4Stack(Ptr<Node> node)
+    {
+      Ptr<Ipv4L3Protocol> ipv4 = CreateObject<Ipv4L3Protocol> ();
+      ipv4->SetNode (node);
+      node->AggregateObject (ipv4);
+      Ptr<Ipv4Impl> ipv4Impl = CreateObject<Ipv4Impl> ();
+      ipv4Impl->SetIpv4 (ipv4);
+      node->AggregateObject (ipv4Impl);
+    }
+
+Note that the Ipv4 protocols are created using :cpp:func:`CreateObject()`.
+Then, they are aggregated to the node. In this manner, the Node base class does
+not need to be edited to allow users with a base class Node pointer to access
+the Ipv4 interface; users may ask the node for a pointer to its Ipv4 interface
+at runtime. How the user asks the node is described in the next subsection.
+
+Note that it is a programming error to aggregate more than one object of the
+same type to an :cpp:class:`ns3::Object`. So, for instance, aggregation is not
+an option for storing all of the active sockets of a node.
+
+GetObject example
+++++++++++++++++
+
+GetObject is a type-safe way to achieve a safe downcasting and to allow
+interfaces to be found on an object.  
+
+Consider a node pointer ``m_node`` that points to a Node object that has an
+implementation of IPv4 previously aggregated to it. The client code wishes to
+configure a default route. To do so, it must access an object within the node
+that has an interface to the IP forwarding configuration. It performs the
+following:::
+
+    Ptr<Ipv4> ipv4 = m_node->GetObject<Ipv4> ();
+
+If the node in fact does not have an Ipv4 object aggregated to it, then the
+method will return null. Therefore, it is good practice to check the return
+value from such a function call. If successful, the user can now use the Ptr to
+the Ipv4 object that was previously aggregated to the node.
+
+Another example of how one might use aggregation is to add optional models to
+objects. For instance, an existing Node object may have an "Energy Model" object
+aggregated to it at run time (without modifying and recompiling the node class).
+An existing model (such as a wireless net device) can then later "GetObject" for
+the energy model and act appropriately if the interface has been either built in
+to the underlying Node object or aggregated to it at run time.  However, other
+nodes need not know anything about energy models.
+
+We hope that this mode of programming will require much less need for developers
+to modify the base classes.
+
+Object factories
+****************
+
+A common use case is to create lots of similarly configured objects. One can
+repeatedly call :cpp:func:`CreateObject` but there is also a factory design
+pattern in use in the |ns3| system. It is heavily used in the "helper" API. 
+
+Class :cpp:class:`ObjectFactory` can be used to instantiate objects and to
+configure the attributes on those objects::
+
+    void SetTypeId (TypeId tid);
+    void Set (std::string name, const AttributeValue &value);
+    Ptr<T> Create (void) const;
+
+The first method allows one to use the |ns3| TypeId system to specify the type
+of objects created. The second allows one to set attributes on the objects to be
+created, and the third allows one to create the objects themselves. 
+
+For example: ::
+
+    ObjectFactory factory;
+    // Make this factory create objects of type FriisPropagationLossModel
+    factory.SetTypeId ("ns3::FriisPropagationLossModel")
+    // Make this factory object change a default value of an attribute, for
+    // subsequently created objects
+    factory.Set ("SystemLoss", DoubleValue (2.0));
+    // Create one such object
+    Ptr<Object> object = factory.Create (); 
+    factory.Set ("SystemLoss", DoubleValue (3.0));
+    // Create another object with a different SystemLoss
+    Ptr<Object> object = factory.Create (); 
+
+Downcasting
+***********
+
+A question that has arisen several times is, "If I have a base class pointer
+(Ptr) to an object and I want the derived class pointer, should I downcast (via
+C++ dynamic cast) to get the derived pointer, or should I use the object
+aggregation system to :cpp:func:`GetObject\<> ()` to find a Ptr to the interface
+to the subclass API?"
+
+The answer to this is that in many situations, both techniques will work.
+|ns3| provides a templated function for making the syntax of Object
+dynamic casting much more user friendly:::
+
+    template <typename T1, typename T2>
+    Ptr<T1>
+    DynamicCast (Ptr<T2> const&p)
+    {
+      return Ptr<T1> (dynamic_cast<T1 *> (PeekPointer (p)));
+    }
+
+DynamicCast works when the programmer has a base type pointer and is testing
+against a subclass pointer. GetObject works when looking for different objects
+aggregated, but also works with subclasses, in the same way as DynamicCast. If
+unsure, the programmer should use GetObject, as it works in all cases. If the
+programmer knows the class hierarchy of the object under consideration, it is
+more direct to just use DynamicCast.
@@ -0,0 +1,6 @@
+.. include:: replace.txt
+
+Object names
+------------
+
+*Placeholder chapter*
@@ -0,0 +1,60 @@
+.. include:: replace.txt
+
+
+Organization
+------------
+
+This chapter describes the overall |ns3| software organization and the
+corresponding organization of this manual.
+
+|ns3| is a discrete-event network simulator in which the simulation core
+and models are implemented in C++. |ns3| is built as a library which may be
+statically or dynamically linked to a C++ main program that defines the
+simulation topology and starts the simulator. |ns3| also exports nearly all
+of its API to Python, allowing Python programs to import an "ns3" module in
+much the same way as the |ns3| library is linked by executables in C++.  
+
+.. _software-organization:
+
+.. figure:: figures/software-organization.*
+   
+   Software organization of |ns3|
+
+The source code for |ns3| is mostly organized in the ``src`` directory and
+can be described by the diagram in :ref:`software-organization`. We will
+work our way from the bottom up; in general, modules only have dependencies
+on modules beneath them in the figure.
+
+We first describe the core of the simulator; those components that are 
+common across all protocol, hardware, and environmental models. 
+The simulation core is implemented in ``src/core``. Packets are 
+fundamental objects in a network simulator
+and are implemented in ``src/network``. These two simulation modules by
+themselves are intended to comprise a generic simulation core that can be
+used by different kinds of networks, not just Internet-based networks.  The
+above modules of |ns3| are independent of specific network and device
+models, which are covered in subsequent parts of this manual.
+
+In addition to the above |ns3| core, we introduce, also in the initial 
+portion of the manual, two other modules that supplement the core C++-based 
+API.  |ns3| programs may access
+all of the API directly or may make use of a so-called *helper API* that
+provides convenient wrappers or encapsulation of low-level API calls. The
+fact that |ns3| programs can be written to two APIs (or a combination
+thereof) is a fundamental aspect of the simulator.
+We also describe how Python is supported in |ns3| before moving onto
+specific models of relevance to network simulation.
+
+The remainder of the manual is focused on documenting the models and
+supporting capabilities.  The next part focuses on two fundamental objects in
+|ns3|:  the ``Node`` and ``NetDevice``. Two special NetDevice types are
+designed to support network emulation use cases, and emulation is described
+next.  The following chapter is devoted to Internet-related models, 
+including the
+sockets API used by Internet applications. The next chapter covers 
+applications, and the following chapter describes additional support for 
+simulation, such as animators and statistics.
+
+The project maintains a separate manual devoted to testing and validation
+of |ns3| code (see the `ns-3 Testing and Validation manual
+<http://www.nsnam.org/tutorials.html>`_).
@@ -0,0 +1,315 @@
+.. include:: replace.txt
+
+Using Python to Run |ns3|
+-------------------------
+
+Python bindings allow the C++ code in |ns3| to be called from Python.
+
+This chapter shows you how to create a Python script that can run |ns3| and also the process of creating Python bindings for a C++ |ns3| module.
+
+Introduction
+************
+
+The goal of Python bindings for |ns3| are two fold:
+
+#. Allow the programmer to write complete simulation scripts in Python (http://www.python.org);
+#. Prototype new models (e.g. routing protocols).
+
+For the time being, the primary focus of the bindings is the first goal, but the second goal will eventually be supported as well.
+Python bindings for |ns3| are being developed using a new tool called PyBindGen (http://code.google.com/p/pybindgen).
+
+An Example Python Script that Runs |ns3|
+****************************************
+
+Here is some example code that is written in Python and that runs |ns3|, which is written in C++.  This Python example can be found in ``examples/tutorial/first.py``:
+
+::
+
+  import ns.applications
+  import ns.core
+  import ns.internet
+  import ns.network
+  import ns.point_to_point
+  
+  ns.core.LogComponentEnable("UdpEchoClientApplication", ns.core.LOG_LEVEL_INFO)
+  ns.core.LogComponentEnable("UdpEchoServerApplication", ns.core.LOG_LEVEL_INFO)
+  
+  nodes = ns.network.NodeContainer()
+  nodes.Create(2)
+  
+  pointToPoint = ns.point_to_point.PointToPointHelper()
+  pointToPoint.SetDeviceAttribute("DataRate", ns.core.StringValue("5Mbps"))
+  pointToPoint.SetChannelAttribute("Delay", ns.core.StringValue("2ms"))
+  
+  devices = pointToPoint.Install(nodes)
+  
+  stack = ns.internet.InternetStackHelper()
+  stack.Install(nodes)
+  
+  address = ns.internet.Ipv4AddressHelper()
+  address.SetBase(ns.network.Ipv4Address("10.1.1.0"), ns.network.Ipv4Mask("255.255.255.0"))
+  
+  interfaces = address.Assign (devices);
+  
+  echoServer = ns.applications.UdpEchoServerHelper(9)
+  
+  serverApps = echoServer.Install(nodes.Get(1))
+  serverApps.Start(ns.core.Seconds(1.0))
+  serverApps.Stop(ns.core.Seconds(10.0))
+  
+  echoClient = ns.applications.UdpEchoClientHelper(interfaces.GetAddress(1), 9)
+  echoClient.SetAttribute("MaxPackets", ns.core.UintegerValue(1))
+  echoClient.SetAttribute("Interval", ns.core.TimeValue(ns.core.Seconds (1.0)))
+  echoClient.SetAttribute("PacketSize", ns.core.UintegerValue(1024))
+  
+  clientApps = echoClient.Install(nodes.Get(0))
+  clientApps.Start(ns.core.Seconds(2.0))
+  clientApps.Stop(ns.core.Seconds(10.0))
+  
+  ns.core.Simulator.Run()
+  ns.core.Simulator.Destroy()
+
+Running Python Scripts
+**********************
+
+waf contains some options that automatically update the python path to find the ns3 module.  To run example programs, there are two ways to use waf to take care of this.  One is to run a waf shell; e.g.:
+
+::
+
+ ./waf --shell
+ python examples/mixed-wireless.py
+
+and the other is to use the --pyrun option to waf:
+
+::
+
+ ./waf --pyrun examples/mixed-wireless.py
+
+To run a python script under the C debugger:
+
+::
+
+ ./waf --shell
+ gdb --args python examples/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:
+
+::
+
+ ./waf --shell
+ python /path/to/your/example/my-script.py
+
+Caveats
+*******
+
+Python bindings for |ns3| are a work in progress, and some limitations are known by developers.  Some of these limitations (not all) are listed here.
+
+Incomplete Coverage
+++++++++++++++++++
+
+First of all, keep in mind that not 100% of the API is supported in Python.  Some of the reasons are:
+
+#. some of the APIs involve pointers, which require knowledge of what kind of memory passing semantics (who owns what memory). Such knowledge is not part of the function signatures, and is either documented or sometimes not even documented.  Annotations are needed to bind those functions;
+#. Sometimes a unusual fundamental data type or C++ construct is used which is not yet supported by PyBindGen;
+#. GCC-XML does not report template based classes unless they are instantiated.
+
+Most of the missing APIs can be wrapped, given enough time, patience, and expertise, and will likely be wrapped if bug reports are submitted.  However, don't file a bug report saying "bindings are incomplete", because we do not have manpower to complete 100% of the bindings.
+
+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:
+
+::
+
+ Ipv4AddressHelper ipAddrs;
+ ipAddrs.SetBase ("192.168.0.0", "255.255.255.0");
+ ipAddrs.Assign (backboneDevices);
+
+In Python, for the time being you have to do:
+
+::
+
+ ipAddrs = ns3.Ipv4AddressHelper()
+ ipAddrs.SetBase(ns3.Ipv4Address("192.168.0.0"), ns3.Ipv4Mask("255.255.255.0"))
+ ipAddrs.Assign(backboneDevices)
+
+CommandLine
+++++++++++
+
+:cpp:func:`CommandLine::AddValue` works differently in Python than it does in |ns3|.  In Python, the first parameter is a string that represents the command-line option name.  When the option is set, an attribute with the same name as the option name is set on the :cpp:func:`CommandLine` object.  Example:
+
+::
+
+    NUM_NODES_SIDE_DEFAULT = 3
+
+    cmd = ns3.CommandLine()
+
+    cmd.NumNodesSide = None
+    cmd.AddValue("NumNodesSide", "Grid side number of nodes (total number of nodes will be this number squared)")
+
+    cmd.Parse(argv)
+
+    [...]
+
+    if cmd.NumNodesSide is None:
+        num_nodes_side = NUM_NODES_SIDE_DEFAULT
+    else:
+        num_nodes_side = int(cmd.NumNodesSide)
+
+Tracing
+++++++
+
+Callback based tracing is not yet properly supported for Python, as new |ns3| API needs to be provided for this to be supported.
+
+Pcap file writing is supported via the normal API.
+
+Ascii tracing is supported since |ns3|.4 via the normal C++ API translated to Python.  However, ascii tracing requires the creation of an ostream object to pass into the ascii tracing methods.  In Python, the C++ std::ofstream has been minimally wrapped to allow this.  For example:
+
+::
+
+    ascii = ns3.ofstream("wifi-ap.tr") # create the file
+    ns3.YansWifiPhyHelper.EnableAsciiAll(ascii)
+    ns3.Simulator.Run()
+    ns3.Simulator.Destroy()
+    ascii.close() # close the file
+
+There is one caveat: you must not allow the file object to be garbage collected while |ns3| is still using it.  That means that the 'ascii' variable above must not be allowed to go out of scope or else the program will crash.
+
+Cygwin limitation
+++++++++++++++++
+
+Python bindings do not work on Cygwin.  This is due to a gccxml bug.
+
+You might get away with it by re-scanning API definitions from within the
+cygwin environment (./waf --python-scan).  However the most likely solution
+will probably have to be that we disable python bindings in CygWin.
+
+If you really care about Python bindings on Windows, try building with mingw and native
+python instead.  Or else, to build without python bindings, disable python bindings in the configuration stage:  
+
+::
+
+  ./waf configure --disable-python
+
+Working with Python Bindings
+****************************
+
+There are currently two kinds of Python bindings in |ns3|:
+
+#. Monolithic bindings contain API definitions for all of the modules and can be found in a single directory, ``bindings/python``.
+#. Modular bindings contain API definitions for a single module and can be found in each module's  ``bindings`` directory. 
+
+Python Bindings Workflow
++++++++++++++++++++++++
+
+The process by which Python bindings are handled is the following:
+
+#. Periodically a developer uses a GCC-XML (http://www.gccxml.org) based API scanning script, which saves the scanned API definition as ``bindings/python/ns3_module_*.py`` files or as Python files in each modules' ``bindings`` directory.  These files are kept under version control in the main |ns3| repository;
+#. Other developers clone the repository and use the already scanned API definitions;
+#. When configuring |ns3|, pybindgen will be automatically downloaded if not already installed.  Released |ns3| tarballs will ship a copy of pybindgen.
+
+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:
+
+::
+
+ ./waf --disable-python
+
+Instructions for Handling New Files or Changed API's
+****************************************************
+
+So you have been changing existing |ns3| APIs and Python bindings no longer compile?  Do not despair, you can rescan the bindings to create new bindings that reflect the changes to the |ns3| API.
+
+Depending on if you are using monolithic or modular bindings, see the discussions below to learn how to rescan your Python bindings. 
+
+Monolithic Python Bindings
+**************************
+
+Scanning the Monolithic Python Bindings
+++++++++++++++++++++++++++++++++++++++
+
+To scan the monolithic Python bindings do the following:
+
+::
+
+  ./waf --python-scan  
+
+Organization of the Monolithic Python Bindings
++++++++++++++++++++++++++++++++++++++++++++++
+
+The monolithic Python API definitions are organized as follows. For each |ns3| module <name>, the file ``bindings/python/ns3_module_<name>.py`` describes its API.  Each of those files have 3 toplevel functions:
+
+#. :cpp:func:`def register_types(module)`: this function takes care of registering new types (e.g. C++ classes, enums) that are defined in tha module;
+#. :cpp:func:`def register_methods(module)`: this function calls, for each class <name>, another function register_methods_Ns3<name>(module).  These latter functions add method definitions for each class;
+#. :cpp:func:`def register_functions(module)`: this function registers |ns3| functions that belong to that module.
+
+Modular Python Bindings
+***********************
+
+Overview
++++++++
+
+Since ns 3.11, the modular bindings are being added, in parallel to the old monolithic bindings.  
+
+The new python bindings are generated into an 'ns' namespace, instead of 'ns3' for the old bindings.  Example:
+
+::
+
+  from ns.network import Node
+  n1 = Node()
+
+With modular Python bindings:
+
+#. There is one separate Python extension module for each |ns3| module;
+#. Scanning API definitions (apidefs) is done on a per ns- module basis;
+#. Each module's apidefs files are stored in a 'bindings' subdirectory of the module directory;
+
+Scanning the Modular Python Bindings
+++++++++++++++++++++++++++++++++++++++
+
+To scan the modular Python bindings for the core module, for example, do the following:
+
+::
+
+  ./waf --apiscan=core
+
+To scan the modular Python bindings for all of the modules, do the following:
+
+::
+
+  ./waf --apiscan=all
+
+Creating a New Module
+++++++++++++++++++++
+
+If you are adding a new module, Python bindings will continue to compile but will not cover the new module.  
+
+To cover a new module, you have to create a ``bindings/python/ns3_module_<name>.py`` file, similar to the what is described in the previous sections, and register it in the variable :cpp:func:`LOCAL_MODULES` in ``bindings/python/ns3modulegen.py``
+
+Adding Modular Bindings To A Existing Module
++++++++++++++++++++++++++++++++++++++++++++
+
+To add support for modular bindings to an existing |ns3| module, simply add the following line to its wscript build() function:
+
+::
+
+    bld.ns3_python_bindings()
+
+Organization of the Modular Python Bindings
+++++++++++++++++++++++++++++++++++++++++++
+
+The ``src/<module>/bindings`` directory may contain the following files, some of them optional:
+
+* ``callbacks_list.py``: this is a scanned file, DO NOT TOUCH.  Contains a list of Callback<...> template instances found in the scanned headers;
+* ``modulegen__gcc_LP64.py``: this is a scanned file, DO NOT TOUCH.  Scanned API definitions for the GCC, LP64 architecture (64-bit)
+* ``modulegen__gcc_ILP32.py``: this is a scanned file, DO NOT TOUCH.  Scanned API definitions for the GCC, ILP32 architecture (32-bit)
+* ``modulegen_customizations.py``: you may optionally add this file in order to customize the pybindgen code generation
+* ``scan-header.h``: you may optionally add this file to customize what header file is scanned for the module.  Basically this file is scanned instead of ns3/<module>-module.h.  Typically, the first statement is #include "ns3/<module>-module.h", plus some other stuff to force template instantiations;
+* ``module_helpers.cc``: you may add additional files, such as this, to be linked to python extension module, but they have to be registered in the wscript. Look at src/core/wscript for an example of how to do so;
+* ``<module>.py``: if this file exists, it becomes the "frontend" python module for the ns3 module, and the extension module (.so file) becomes _<module>.so instead of <module>.so.  The <module>.py file has to import all symbols from the module _<module> (this is more tricky than it sounds, see src/core/bindings/core.py for an example), and then can add some additional pure-python definitions.   
+
+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>`_.
@@ -0,0 +1,289 @@
+.. include:: replace.txt
+
+Random Variables
+----------------
+
+|ns3| contains a built-in pseudo-random number generator (PRNG). It is important
+for serious users of the simulator to understand the functionality,
+configuration, and usage of this PRNG, and to decide whether it is sufficient
+for his or her research use.  
+
+Quick Overview
+**************
+
+|ns3| random numbers are provided via instances of
+:cpp:class:`ns3::RandomVariable`.
+
+* by default, |ns3| simulations use a fixed seed; if there is any randomness in
+  the simulation, each run of the program will yield identical results unless
+  the seed and/or run number is changed.  
+
+* in *ns-3.3* and earlier, |ns3| simulations used a random seed by default; this
+  marks a change in policy starting with *ns-3.4*.
+
+* to obtain randomness across multiple simulation runs, you must either set the
+  seed differently or set the run number differently.  To set a seed, call
+  :cpp:func:`ns3::SeedManager::SetSeed` at the beginning of the program; to set
+  a run number with the same seed, call :cpp:func:`ns3::SeedManager::SetRun` at
+  the beginning of the program; see :ref:`seeding-and-independent-replications`.
+
+* each RandomVariable used in |ns3| has a virtual random number generator
+  associated with it; all random variables use either a fixed or random seed
+  based on the use of the global seed (previous bullet);
+
+* if you intend to perform multiple runs of the same scenario, with different
+  random numbers, please be sure to read the section on how to perform
+  independent replications: :ref:`seeding-and-independent-replications`.
+
+Read further for more explanation about the random number facility for |ns3|.
+
+Background
+**********
+
+Simulations use a lot of random numbers; one study 
+found that most network simulations spend as much as 50% 
+of the CPU generating random numbers.  Simulation users need
+to be concerned with the quality of the (pseudo) random numbers and
+the independence between different streams of random numbers.  
+
+Users need to be concerned with a few issues, such as:
+
+* the seeding of the random number generator and whether a 
+  simulation outcome is deterministic or not,
+* how to acquire different streams of random numbers that are 
+  independent from one another, and 
+* how long it takes for streams to cycle
+
+We will introduce a few terms here:  a RNG provides a long sequence
+of (pseudo) random numbers.
+The length of this sequence is called the *cycle length*
+or *period*, after which the RNG will repeat itself.  
+This sequence can
+be  partitioned into disjoint *streams*.  A stream of a
+RNG is a contiguous subset or block of the RNG sequence.
+For instance, if the
+RNG period is of length N, and two streams are provided from this
+RNG, then
+the first stream might use the first N/2 values and the second
+stream might produce the second N/2 values.  An important property
+here is that the two streams are uncorrelated.  Likewise, each
+stream can be partitioned disjointedly to a number of 
+uncorrelated *substreams*.  The underlying RNG hopefully
+produces a pseudo-random sequence of numbers with a very long
+cycle length, and partitions this into streams and substreams in an 
+efficient manner.
+
+|ns3| uses the same underlying random number generator as does |ns2|:  the
+MRG32k3a generator from Pierre L'Ecuyer.  A detailed description can be found in
+http://www.iro.umontreal.ca/~lecuyer/myftp/papers/streams00.pdf.  The MRG32k3a
+generator provides :math:`1.8x10^{19}` independent streams of random numbers,
+each of which consists of :math:`2.3x10^{15}` substreams. Each substream has a
+period (*i.e.*, the number of random numbers before overlap) of
+:math:`7.6x10^{22}`. The period of the entire generator is :math:`3.1x10^{57}`. 
+
+
+Class :cpp:class:`ns3::RandomVariable` is the public interface to this
+underlying random number generator.  When users create new ``RandomVariables``
+(such as :cpp:class:`ns3::UniformVariable`,
+:cpp:class:`ns3::ExponentialVariable`, etc.), they create an object that uses
+one of the distinct, independent streams of the random number generator.
+Therefore, each object of type :cpp:class:`ns3::RandomVariable` has,
+conceptually, its own "virtual" RNG.  Furthermore, each
+:cpp:class:`ns3::RandomVariable` can be configured to use one of the set of
+substreams drawn from the main stream.
+
+An alternate implementation would be to allow each RandomVariable to have its
+own (differently seeded) RNG.  However, we cannot guarantee as strongly that the
+different sequences would be uncorrelated in such a case; hence, we prefer to
+use a single RNG and streams and substreams from it.
+
+.. _seeding-and-independent-replications:
+
+Seeding and independent replications
+************************************
+
+|ns3| simulations can be configured to produce deterministic or random results.
+If the |ns3| simulation is configured to use a fixed, deterministic seed with
+the same run number, it should give the same output each time it is run.
+
+By default, |ns3| simulations use a fixed seed and run number.  These values
+are stored in two :cpp:class:`ns3::GlobalValue` instances: ``g_rngSeed`` and
+``g_rngRun``.
+
+A typical use case is to run a simulation as a sequence of independent trials,
+so as to compute statistics on a large number of independent runs.  The user can
+either change the global seed and rerun the simulation, or can advance the
+substream state of the RNG, which is referred to as incrementing the run number.
+
+A class :cpp:class:`ns3::SeedManager` provides an API to control the seeding and
+run number behavior.  This seeding and substream state setting must be called
+before any random variables are created; e.g::
+
+  SeedManager::SetSeed (3);  // Changes seed from default of 1 to 3
+  SeedManager::SetRun (7);  // Changes run number from default of 1 to 7
+  // Now, create random variables
+  UniformVariable x(0,10);
+  ExponentialVariable y(2902);
+  ...
+
+Which is better, setting a new seed or advancing the substream state?  There is
+no guarantee that the streams produced by two random seeds will not overlap.
+The only way to guarantee that two streams do not overlap is to use the
+substream capability provided by the RNG implementation.  *Therefore, use the
+substream capability to produce multiple independent runs of the same
+simulation.* In other words, the more statistically rigorous way to configure
+multiple independent replications is to use a fixed seed and to advance the run
+number.  This implementation allows for a maximum of :math:`2.3x10^{15}`
+independent replications using the substreams. 
+
+For ease of use, it is not necessary to control the seed and run number from
+within the program; the user can set the ``NS_GLOBAL_VALUE`` environment
+variable as follows::
+
+  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::
+
+  ./waf --command-template="%s --RngRun=3" --run program-name
+
+or, if you are running programs directly outside of waf::
+
+  ./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.
+
+Class RandomVariable
+********************
+
+All random variables should derive from class :cpp:class:`RandomVariable`. This
+base class provides a few static methods for globally configuring the behavior
+of the random number generator. Derived classes provide API for drawing random
+variates from the particular distribution being supported.
+
+Each RandomVariable created in the simulation is given a generator that is a new
+RNGStream from the underlying PRNG. Used in this manner, the L'Ecuyer
+implementation allows for a maximum of :math:`1.8x10^19` random variables.  Each
+random variable in a single replication can produce up to :math:`7.6x10^22`
+random numbers before overlapping.
+
+Base class public API
+*********************
+
+Below are excerpted a few public methods of class :cpp:class:`RandomVariable`
+that access the next value in the substream.::
+
+  /**
+   * \brief Returns a random double from the underlying distribution
+   * \return A floating point random value
+   */
+  double GetValue (void) const;
+  
+  /**
+   * \brief Returns a random integer integer from the underlying distribution
+   * \return  Integer cast of ::GetValue()
+   */
+  uint32_t GetInteger (void) const;
+
+We have already described the seeding configuration above. Different
+RandomVariable subclasses may have additional API.
+
+Types of RandomVariables
+************************
+
+The following types of random variables are provided, and are documented in the
+|ns3| Doxygen or by reading ``src/core/model/random-variable.h``.  Users can also
+create their own custom random variables by deriving from class
+:cpp:class:`RandomVariable`.
+
+* class :cpp:class:`UniformVariable`
+* class :cpp:class:`ConstantVariable`
+* class :cpp:class:`SequentialVariable`
+* class :cpp:class:`ExponentialVariable`
+* class :cpp:class:`ParetoVariable`
+* class :cpp:class:`WeibullVariable`
+* class :cpp:class:`NormalVariable`
+* class :cpp:class:`EmpiricalVariable`
+* class :cpp:class:`IntEmpiricalVariable`
+* class :cpp:class:`DeterministicVariable`
+* class :cpp:class:`LogNormalVariable`
+* class :cpp:class:`TriangularVariable`
+* class :cpp:class:`GammaVariable`
+* class :cpp:class:`ErlangVariable`
+* class :cpp:class:`ZipfVariable`
+
+Semantics of RandomVariable objects
+***********************************
+
+RandomVariable objects have value semantics. This means that they can be passed
+by value to functions.  The can also be passed by reference to const.
+RandomVariables do not derive from :cpp:class:`ns3::Object` and we do not use
+smart pointers to manage them; they are either allocated on the stack or else
+users explicitly manage any heap-allocated RandomVariables.
+
+RandomVariable objects 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:::
+
+    TypeId
+    RandomPropagationDelayModel::GetTypeId (void)
+    { 
+      static TypeId tid = TypeId ("ns3::RandomPropagationDelayModel")
+        .SetParent<PropagationDelayModel> ()
+        .AddConstructor<RandomPropagationDelayModel> ()
+        .AddAttribute ("Variable",
+                       "The random variable which generates random delays (s).",
+                       RandomVariableValue (UniformVariable (0.0, 1.0)),
+             MakeRandomVariableAccessor (&RandomPropagationDelayModel::m_variable), 
+                       MakeRandomVariableChecker ())
+        ;
+      return tid;
+    }
+
+Here, the |ns3| user can change the default random variable for this
+delay model (which is a UniformVariable ranging from 0 to 1) through
+the attribute system.
+
+Using other PRNG
+****************
+
+There is presently no support for substituting a different underlying
+random number generator (e.g., the GNU Scientific Library or the Akaroa
+package).  Patches are welcome.
+
+More advanced usage
+*******************
+
+*To be completed.*
+
+Publishing your results
+***********************
+
+When you publish simulation results, a key piece of configuration 
+information that you should always state is how you used the
+the random number generator.
+
+* what seeds you used,
+* what RNG you used if not the default,
+* how were independent runs performed,
+* for large simulations, how did you check that you did not cycle.
+
+It is incumbent on the researcher publishing results to include enough
+information to allow others to reproduce his or her results. It is also
+incumbent on the researcher to convince oneself that the random numbers used
+were statistically valid, and to state in the paper why such confidence is
+assumed.
+
+Summary
+*******
+
+Let's review what things you should do when creating a simulation.
+
+* Decide whether you are running with a fixed seed or random seed; a fixed seed
+  is the default, 
+* Decide how you are going to manage independent replications, if applicable, 
+* Convince yourself that you are not drawing more random values than the cycle
+  length, if you are running a very long simulation, and
+* When you publish, follow the guidelines above about documenting your use of
+  the random number generator.
@@ -0,0 +1,93 @@
+.. include:: replace.txt
+
+RealTime
+--------
+
+|ns3| has been designed for integration into testbed and virtual machine
+environments. To integrate with real network stacks and emit/consume packets, a
+real-time scheduler is needed to try to lock the simulation clock with the
+hardware clock. We describe here a component of this: the RealTime scheduler. 
+
+The purpose of the realtime scheduler is to cause the progression of the
+simulation clock to occur synchronously with respect to some external time base.
+Without the presence of an external time base (wall clock), simulation time
+jumps instantly from one simulated time to the next.
+
+Behavior
+********
+
+When using a non-realtime scheduler (the default in |ns3|), the simulator
+advances the simulation time to the next scheduled event. During event
+execution, simulation time is frozen. With the realtime scheduler, the behavior
+is similar from the perspective of simulation models (i.e., simulation time is
+frozen during event execution), but between events, the simulator will attempt
+to keep the simulation clock aligned with the machine clock.
+
+When an event is finished executing, and the scheduler moves to the next event,
+the scheduler compares the next event execution time with the machine clock.  If
+the next event is scheduled for a future time, the simulator sleeps until that
+realtime is reached and then executes the next event.
+
+It may happen that, due to the processing inherent in the execution of
+simulation events, that the simulator cannot keep up with realtime.  In such a
+case, it is up to the user configuration what to do. There are two |ns3|
+attributes that govern the behavior. The first is
+``ns3::RealTimeSimulatorImpl::SynchronizationMode``. The two entries possible
+for this attribute are ``BestEffort`` (the default) or ``HardLimit``. In
+"BestEffort" mode, the simulator will just try to catch up to realtime by
+executing events until it reaches a point where the next event is in the
+(realtime) future, or else the simulation ends. In BestEffort mode, then, it is
+possible for the simulation to consume more time than the wall clock time. The
+other option "HardLimit" will cause the simulation to abort if the tolerance
+threshold is exceeded.  This attribute is
+``ns3::RealTimeSimulatorImpl::HardLimit`` and the default is 0.1 seconds.   
+
+A different mode of operation is one in which simulated time is **not** frozen
+during an event execution. This mode of realtime simulation was implemented but
+removed from the |ns3| tree because of questions of whether it would be useful.
+If users are interested in a realtime simulator for which simulation time does
+not freeze during event execution (i.e., every call to ``Simulator::Now()``
+returns the current wall clock time, not the time at which the event started
+executing), please contact the ns-developers mailing list.
+
+Usage
+*****
+
+The usage of the realtime simulator is straightforward, from a scripting
+perspective.  Users just need to set the attribute 
+``SimulatorImplementationType`` to the Realtime simulator, such as follows: ::
+
+  GlobalValue::Bind ("SimulatorImplementationType",
+    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: ::
+
+    ./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.
+
+Implementation
+**************
+
+The implementation is contained in the following files:
+
+* ``src/core/model/realtime-simulator-impl.{cc,h}``
+* ``src/core/model/wall-clock-synchronizer.{cc,h}``
+
+In order to create a realtime scheduler, to a first approximation you just want
+to cause simulation time jumps to consume real time. We propose doing this using
+a combination of sleep- and busy- waits. Sleep-waits cause the calling process
+(thread) to yield the processor for some amount of time. Even though this
+specified amount of time can be passed to nanosecond resolution, it is actually
+converted to an OS-specific granularity. In Linux, the granularity is called a
+Jiffy. Typically this resolution is insufficient for our needs (on the order of
+a ten milliseconds), so we round down and sleep for some smaller number of
+Jiffies. The process is then awakened after the specified number of Jiffies has
+passed. At this time, we have some residual time to wait. This time is generally
+smaller than the minimum sleep time, so we busy-wait for the remainder of the
+time. This means that the thread just sits in a for loop consuming cycles until
+the desired time arrives. After the combination of sleep- and busy-waits, the
+elapsed realtime (wall) clock should agree with the simulation time of the next
+event and the simulation proceeds. 
@@ -0,0 +1,3 @@
+.. |ns3| replace:: *ns-3*
+
+.. |ns2| replace:: *ns-2*
@@ -0,0 +1,10 @@
+Support
+-------
+
+.. toctree::
+
+   new-models
+   new-modules
+   enable-modules
+   enable-tests
+   troubleshoot
@@ -0,0 +1,219 @@
+.. include:: replace.txt
+
+Background
+----------
+
+**This chapter may be skipped by readers familiar with the basics of
+software testing.**
+
+Writing defect-free software is a difficult proposition.  There are many
+dimensions to the problem and there is much confusion regarding what is 
+meant by different terms in different contexts.  We have found it worthwhile
+to spend a little time reviewing the subject and defining some terms.
+
+Software testing may be loosely defined as the process of executing a program
+with the intent of finding errors.  When one enters a discussion regarding 
+software testing, it quickly becomes apparent that there are many distinct 
+mind-sets with which one can approach the subject.
+
+For example, one could break the process into broad functional categories 
+like ''correctness testing,'' ''performance testing,'' ''robustness testing''
+and ''security testing.''  Another way to look at the problem is by life-cycle:
+''requirements testing,'' ''design testing,'' ''acceptance testing,'' and 
+''maintenance testing.''  Yet another view is by the scope of the tested system.
+In this case one may speak of ''unit testing,'' ''component testing,'' 
+''integration testing,'' and ''system testing.''  These terms are also not
+standardized in any way, and so ''maintenance testing'' and ''regression
+testing'' may be heard interchangeably.  Additionally, these terms are often
+misused.
+
+There are also a number of different philosophical approaches to software 
+testing.  For example, some organizations advocate writing test programs
+before actually implementing the desired software, yielding ''test-driven 
+development.''  Some organizations advocate testing from a customer perspective
+as soon as possible, following a parallel with the agile development process:
+''test early and test often.''  This is sometimes called ''agile testing.''  It
+seems that there is at least one approach to testing for every development 
+methodology.
+
+The |ns3| project is not in the business of advocating for any one of
+these processes, but the project as a whole has requirements that help inform
+the test process.
+
+Like all major software products, |ns3| has a number of qualities that
+must be present for the product to succeed.  From a testing perspective, some
+of these qualities that must be addressed are that |ns3| must be 
+''correct,'' ''robust,''  ''performant'' and ''maintainable.''  Ideally there
+should be metrics for each of these dimensions that are checked by the tests
+to identify when the product fails to meet its expectations / requirements.
+
+Correctness
+***********
+
+The essential purpose of testing is to determine that a piece of software 
+behaves ''correctly.''  For |ns3| this means that if we simulate 
+something, the simulation should faithfully represent some physical entity or 
+process to a specified accuracy and precision.
+
+It turns out that there are two perspectives from which one can view 
+correctness.  Verifying that a particular model is implemented according 
+to its specification is generically called *verification*.  The process of 
+deciding that the model is correct for its intended use is generically called 
+*validation*.
+
+Validation and Verification
+***************************
+
+A computer model is a mathematical or logical representation of something. It 
+can represent a vehicle, an elephant (see 
+`David Harel's talk about modeling an elephant at SIMUTools 2009 <http://simutools.org/2009/>`_, or a networking card.  Models can also represent
+processes such as global warming, freeway traffic flow or a specification of a 
+networking protocol.  Models can be completely faithful representations of a 
+logical process specification, but they necessarily can never completely 
+simulate a physical object or process.  In most cases, a number of 
+simplifications are made to the model to make simulation computationally 
+tractable. 
+
+Every model has a *target system* that it is attempting to simulate.  The 
+first step in creating a simulation model is to identify this target system and
+the level of detail and accuracy that the simulation is desired to reproduce. 
+In the case of a logical process, the target system may be identified as ''TCP 
+as defined by RFC 793.''  In this case, it will probably be desirable to create
+a model that completely and faithfully reproduces RFC 793.  In the case of a 
+physical process this will not be possible. If, for example, you would like to 
+simulate a wireless networking card, you may determine that you need,  ''an 
+accurate MAC-level implementation of the 802.11 specification and [...] a 
+not-so-slow PHY-level model of the 802.11a specification.'' 
+
+Once this is done, one can develop an abstract model of the target system.  This
+is typically an exercise in managing the tradeoffs between complexity, resource
+requirements and accuracy.  The process of developing an abstract model has been
+called *model qualification* in the literature.  In the case of a TCP 
+protocol, this process results in a design for a collection of objects, 
+interactions and behaviors that will fully implement RFC 793 in |ns3|.
+In the case of the wireless card, this process results in a number of tradeoffs
+to allow the physical layer to be simulated and the design of a network device 
+and channel for ns-3, along with the desired objects, interactions and behaviors. 
+
+This abstract model is then developed into an |ns3| model that 
+implements the abstract model as a computer program.  The process of getting the
+implementation to agree with the abstract model is called *model 
+verification* in the literature. 
+
+The process so far is open loop. What remains is to make a determination that a
+given ns-3 model has some connection to some reality -- that a model is an 
+accurate representation of a real system, whether a logical process or a physical
+entity. 
+
+If one is going to use a simulation model to try and predict how some real 
+system is going to behave, there must be some reason to believe your results -- 
+i.e., can one trust that an inference made from the model translates into a 
+correct prediction for the real system.  The process of getting the ns-3 model
+behavior to agree with the desired target system behavior as defined by the model
+qualification process is called *model validation* in the literature. In the
+case of a TCP implementation, you may want to compare the behavior of your ns-3 
+TCP model to some reference implementation in order to validate your model.  In 
+the case of a wireless physical layer simulation, you may want to compare the 
+behavior of your model to that of real hardware in a controlled setting,
+
+The |ns3| testing environment provides tools to allow for both model
+validation and testing, and encourages the publication of validation results.
+
+Robustness
+**********
+
+Robustness is the quality of being able to withstand stresses, or changes in 
+environments, inputs or calculations, etc.  A system or design is ''robust''
+if it can deal with such changes with minimal loss of functionality.
+
+This kind of testing is usually done with a particular focus.  For example, the 
+system as a whole can be run on many different system configurations to 
+demonstrate that it can perform correctly in a large number of environments.
+
+The system can be also be stressed by operating close to or beyond capacity by 
+generating or simulating resource exhaustion of various kinds.  This genre of
+testing is called ''stress testing.''
+
+The system and its components may be exposed to so-called ''clean tests'' that
+demonstrate a positive result -- that is that the system operates correctly in 
+response to a large variation of expected configurations.  
+
+The system and its components may also be exposed to ''dirty tests'' which 
+provide inputs outside the expected range.  For example, if a module expects a 
+zero-terminated string representation of an integer, a dirty test might provide
+an unterminated string of random characters to verify that the system does not
+crash as a result of this unexpected input.  Unfortunately, detecting such 
+''dirty'' input and taking preventive measures to ensure the system does not
+fail catastrophically can require a huge amount of development overhead.  In
+order to reduce development time, a decision was taken early on in the project
+to minimize the amount of parameter validation and error handling in the 
+|ns3| codebase.  For this reason, we do not spend much time on dirty
+testing -- it would just uncover the results of the design decision we know
+we took.
+
+We do want to demonstrate that |ns3| software does work across some set
+of conditions.  We borrow a couple of definitions to narrow this down a bit.  
+The *domain of applicability* is a set of prescribed conditions for which
+the model has been tested, compared against reality to the extent possible, and 
+judged  suitable for use.  The *range of accuracy* is an agreement between 
+the computerized model and reality within a domain of applicability. 
+
+The |ns3| testing environment provides tools to allow for setting up 
+and running test environments over multiple systems (buildbot) and provides 
+classes to encourage clean tests to verify the operation of the system over the
+expected ''domain of applicability'' and ''range of accuracy.''
+
+Performant
+**********
+
+Okay, ''performant'' isn't a real English word.  It is, however, a very concise 
+neologism that is quite often used to describe what we want |ns3| to 
+be: powerful and fast enough to get the job done.
+
+This is really about the broad subject of software performance testing.  One of
+the key things that is done is to compare two systems to find which performs 
+better (cf benchmarks).  This is used to demonstrate that, for example, 
+|ns3| can perform a basic kind of simulation at least as fast as a 
+competing tool, or can be used to identify parts of the system that perform
+badly.
+
+In the |ns3| test framework, we provide support for timing various kinds
+of tests.
+
+Maintainability
+***************
+
+A software product must be maintainable.  This is, again, a very broad 
+statement, but a testing framework can help with the task.  Once a model has
+been developed, validated and verified, we can repeatedly execute the suite
+of tests for the entire system to ensure that it remains valid and verified
+over its lifetime.
+
+When a feature stops functioning as intended after some kind of change to the
+system is integrated, it is called generically a *regression*.  
+Originally the 
+term regression referred to a change that caused a previously fixed bug to
+reappear, but the term has evolved to describe any kind of change that breaks
+existing functionality.  There are many kinds of regressions that may occur
+in practice.
+
+A *local regression* is one in which a change affects the changed component
+directly.  For example, if a component is modified to allocate and free memory
+but stale pointers are used, the component itself fails.
+
+A *remote regression* is one in which a change to one component breaks
+functionality in another component.  This reflects violation of an implied but
+possibly unrecognized contract between components.
+
+An *unmasked regression* is one that creates a situation where a previously
+existing bug that had no affect is suddenly exposed in the system.  This may
+be as simple as exercising a code path for the first time.
+
+A *performance regression* is one that causes the performance requirements
+of the system to be violated.  For example, doing some work in a low level 
+function that may be repeated large numbers of times may suddenly render the
+system unusable from certain perspectives.
+
+The |ns3| testing framework provides tools for automating the process
+used to validate and verify the code in nightly test suites to help quickly
+identify possible regressions.
@@ -0,0 +1,750 @@
+.. include:: replace.txt
+
+Testing framework
+-----------------
+
+ns-3 consists of a simulation core engine, a set of models, example programs, 
+and tests.  Over time, new contributors contribute models, tests, and 
+examples.  A Python test program ``test.py`` serves as the test
+execution manager; ``test.py`` can run test code and examples to
+look for regressions, can output the results into a number of forms, and
+can manage code coverage analysis tools.  On top of this, we layer 
+*Buildbots* that are automated build robots that perform
+robustness testing by running the test framework on different systems
+and with different configuration options.
+
+BuildBots
+*********
+
+At the highest level of ns-3 testing are the buildbots (build robots).  
+If you are unfamiliar with
+this system look at `<http://djmitche.github.com/buildbot/docs/0.7.11/>`_.  
+This is an open-source automated system that allows |ns3| to be rebuilt
+and tested each time something has changed.  By running the buildbots on a number
+of different systems we can ensure that |ns3| builds and executes
+properly on all of its supported systems.
+
+Users (and developers) typically will not interact with the buildbot system other 
+than to read its messages regarding test results.  If a failure is detected in 
+one of the automated build and test jobs, the buildbot will send an email to the
+*ns-developers* mailing list.  This email will look something like::
+
+  The Buildbot has detected a new failure of osx-ppc-g++-4.2 on NsNam.
+  Full details are available at:
+   http://ns-regression.ee.washington.edu:8010/builders/osx-ppc-g%2B%2B-4.2/builds/0
+  
+  Buildbot URL: http://ns-regression.ee.washington.edu:8010/
+  
+  Buildslave for this Build: darwin-ppc
+  
+  Build Reason: The web-page 'force build' button was pressed by 'ww': ww
+  
+  Build Source Stamp: HEAD
+  Blamelist: 
+  
+  BUILD FAILED: failed shell_5 shell_6 shell_7 shell_8 shell_9 shell_10 shell_11 shell_12 
+  
+  sincerely,
+  -The Buildbot
+
+In the full details URL shown in the email, one can search for the keyword 
+``failed`` and select the ``stdio`` link for the corresponding step to see
+the reason for the failure.
+
+The buildbot will do its job quietly if there are no errors, and the system will
+undergo build and test cycles every day to verify that all is well.
+
+Test.py
+*******
+The buildbots use a Python program, ``test.py``, that is responsible for 
+running all of the tests and collecting the resulting reports into a human-
+readable form.  This program is also available for use by users and developers
+as well.
+
+``test.py`` is very flexible in allowing the user to specify the number
+and kind of tests to run; and also the amount and kind of output to generate.
+
+Before running ``test.py``, make sure that ns3's examples and tests
+have been built by doing the following
+
+::
+
+  ./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
+
+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.
+ 
+::
+
+  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'
+  'build' finished successfully (0.939s)
+  FAIL: TestSuite ns3-wifi-propagation-loss-models
+  PASS: TestSuite object-name-service
+  PASS: TestSuite pcap-file-object
+  PASS: TestSuite ns3-tcp-cwnd
+  ...
+  PASS: TestSuite ns3-tcp-interoperability
+  PASS: Example csma-broadcast
+  PASS: Example csma-multicast
+
+This mode is intended to be used by users who are interested in determining if
+their distribution is working correctly, and by developers who are interested
+in determining if changes they have made have caused any regressions.
+
+There are a number of options available to control the behavior of ``test.py``.
+if you run ``test.py --help`` you should see a command summary like:
+
+::
+
+  Usage: test.py [options]
+  
+  Options:
+    -h, --help            show this help message and exit
+    -b BUILDPATH, --buildpath=BUILDPATH
+                          specify the path where ns-3 was built (defaults to the
+                          build directory for the current variant)
+    -c KIND, --constrain=KIND
+                          constrain the test-runner by kind of test
+    -e EXAMPLE, --example=EXAMPLE
+                          specify a single example to run (with relative path)
+    -g, --grind           run the test suites and examples using valgrind
+    -k, --kinds           print the kinds of tests available
+    -l, --list            print the list of known tests
+    -m, --multiple        report multiple failures from test suites and test
+                          cases
+    -n, --nowaf           do not run waf before starting testing
+    -p PYEXAMPLE, --pyexample=PYEXAMPLE
+                          specify a single python example to run (with relative
+                          path)
+    -r, --retain          retain all temporary files (which are normally
+                          deleted)
+    -s TEST-SUITE, --suite=TEST-SUITE
+                          specify a single test suite to run
+    -t TEXT-FILE, --text=TEXT-FILE
+                          write detailed test results into TEXT-FILE.txt
+    -v, --verbose         print progress and informational messages
+    -w HTML-FILE, --web=HTML-FILE, --html=HTML-FILE
+                          write detailed test results into HTML-FILE.html
+    -x XML-FILE, --xml=XML-FILE
+                          write detailed test results into XML-FILE.xml
+
+If one specifies an optional output style, one can generate detailed descriptions
+of the tests and status.  Available styles are ``text`` and ``HTML``.
+The buildbots will select the HTML option to generate HTML test reports for the
+nightly builds using
+
+::
+
+  ./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
+interested in the details.
+
+::
+
+  ./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
+provided.
+
+To further explore the failure, ``test.py`` allows a single test suite
+to be specified.  Running the command
+
+::
+
+  ./test.py --suite=ns3-wifi-propagation-loss-models
+
+results in that single test suite being run.
+
+::
+
+  FAIL: TestSuite ns3-wifi-propagation-loss-models
+
+To find detailed information regarding the failure, one must specify the kind
+of output desired.  For example, most people will probably be interested in
+a text file::
+
+  ./test.py --suite=ns3-wifi-propagation-loss-models --text=results.txt
+
+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::
+
+
+  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)
+  FAIL: Test Case "Check ... Log Distance ... model" (real 0.01 user 0.01 system 0.00)
+    Details:
+      Message:   Got unexpected SNR value
+      Condition: [long description of what actually failed]
+      Actual:    176.395
+      Limit:     176.407 +- 0.0005
+      File:      ../src/test/ns3wifi/propagation-loss-models-test-suite.cc
+      Line:      360
+
+Notice that the Test Suite is composed of two Test Cases.  The first test case
+checked the Friis propagation loss model and passed.  The second test case 
+failed checking the Log Distance propagation model.  In this case, an SNR of
+176.395 was found, and the test expected a value of 176.407 correct to three
+decimal places.  The file which implemented the failing test is listed as well
+as the line of code which triggered the failure.
+
+If you desire, you could just as easily have written an HTML file using the 
+``--html`` option as described above.
+
+Typically a user will run all tests at least once after downloading 
+|ns3| to ensure that his or her environment has been built correctly
+and is generating correct results according to the test suites.  Developers
+will typically run the test suites before and after making a change to ensure
+that they have not introduced a regression with their changes.  In this case,
+developers may not want to run all tests, but only a subset.  For example,
+the developer might only want to run the unit tests periodically while making
+changes to a repository.  In this case, ``test.py`` can be told to constrain
+the types of tests being run to a particular class of tests.  The following
+command will result in only the unit tests being run::
+
+  ./test.py --constrain=unit
+
+Similarly, the following command will result in only the example smoke tests
+being run::
+
+  ./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
+
+will result in the following list being displayed::
+
+  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'
+  'build' finished successfully (0.939s)Waf: Entering directory `/home/craigdo/repos/ns-3-allinone-test/ns-3-dev/build'
+  bvt:         Build Verification Tests (to see if build completed successfully)
+  core:        Run all TestSuite-based tests (exclude examples)
+  example:     Examples (to see if example programs run successfully)
+  performance: Performance Tests (check to see if the system is as fast as expected)
+  system:      System Tests (spans modules to check integration of modules)
+  unit:        Unit Tests (within modules to check basic functionality)
+
+Any of these kinds of test can be provided as a constraint using the ``--constraint`` 
+option.
+
+To see a quick list of all of the test suites available, you can ask for them
+to be listed.  The following command,
+
+::
+
+  ./test.py --list
+
+will result in a list of the test suite being displayed, similar to::
+
+  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'
+  'build' finished successfully (0.939s)
+  histogram
+  ns3-wifi-interference
+  ns3-tcp-cwnd
+  ns3-tcp-interoperability
+  sample
+  devices-mesh-flame
+  devices-mesh-dot11s
+  devices-mesh
+  ...
+  object-name-service
+  callback
+  attributes
+  config
+  global-value
+  command-line
+  basic-random-number
+  object
+
+Any of these listed suites can be selected to be run by itself using the 
+``--suite`` option as shown above.
+
+Similarly to test suites, one can run a single C++ example program
+using the ``--example`` option.  Note that the relative path for the
+example must be included and that the executables built for C++
+examples do not have extensions.  Entering
+
+::
+
+  ./test.py --example=examples/udp/udp-echo
+
+results in that single example being run.
+
+::
+
+  PASS: Example examples/udp/udp-echo
+
+You can specify the directory where ns-3 was built using the
+``--buildpath`` option as follows.
+
+::
+
+  ./test.py --buildpath=/home/craigdo/repos/ns-3-allinone-test/ns-3-dev/build/debug --example=examples/wireless/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
+and that Python examples do need their extensions.  Entering
+
+::
+
+  ./test.py --pyexample=examples/tutorial/first.py
+
+results in that single example being run.
+
+::
+
+  PASS: Example examples/tutorial/first.py
+
+Because Python examples are not built, you do not need to specify the
+directory where ns-3 was built to run them.
+
+Normally when example programs are executed, they write a large amount of trace 
+file data.  This is normally saved to the base directory of the distribution 
+(e.g., /home/user/ns-3-dev).  When ``test.py`` runs an example, it really
+is completely unconcerned with the trace files.  It just wants to to determine
+if the example can be built and run without error.  Since this is the case, the
+trace files are written into a ``/tmp/unchecked-traces`` directory.  If you 
+run the above example, you should be able to find the associated 
+``udp-echo.tr`` and ``udp-echo-n-1.pcap`` files there.
+
+The list of available examples is defined by the contents of the ''examples''
+directory in the distribution.  If you select an example for execution using
+the ``--example`` option, ``test.py`` will not make any attempt to decide
+if the example has been configured or not, it will just try to run it and
+report the result of the attempt.
+
+When ``test.py`` runs, by default it will first ensure that the system has
+been completely built.  This can be defeated by selecting the ``--nowaf``
+option.
+
+::
+
+  ./test.py --list --nowaf
+
+will result in a list of the currently built test suites being displayed, similar to::
+
+  ns3-wifi-propagation-loss-models
+  ns3-tcp-cwnd
+  ns3-tcp-interoperability
+  pcap-file-object
+  object-name-service
+  random-number-generators
+
+Note the absence of the ``Waf`` build messages.
+
+``test.py`` also supports running the test suites and examples under valgrind.
+Valgrind is a flexible program for debugging and profiling Linux executables.  By
+default, valgrind runs a tool called memcheck, which performs a range of memory-
+checking functions, including detecting accesses to uninitialised memory, misuse 
+of allocated memory (double frees, access after free, etc.) and detecting memory 
+leaks.  This can be selected by using the ``--grind`` option.
+
+::
+
+  ./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,
+however in some cases it can be useful (for debugging purposes) to view these files.
+``test.py`` provides a ``--retain`` option which will cause these temporary
+files to be kept after the run is completed.  The files are saved in a directory 
+named ``testpy-output`` under a subdirectory named according to the current Coordinated
+Universal Time (also known as Greenwich Mean Time).
+
+::
+
+  ./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
+will be terribly useful unless there is an error.  In this case, you can get
+access to the standard output and standard error reported by running test suites
+and examples.  Select verbose in the following way::
+
+  ./test.py --verbose
+
+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 
+
+TestTaxonomy
+************
+
+As mentioned above, tests are grouped into a number of broadly defined 
+classifications to allow users to selectively run tests to address the different
+kinds of testing that need to be done.
+
+* Build Verification Tests
+* Unit Tests 
+* System Tests
+* Examples
+* Performance Tests
+
+BuildVerificationTests
++++++++++++++++++++++
+
+These are relatively simple tests that are built along with the distribution
+and are used to make sure that the build is pretty much working.  Our
+current unit tests live in the source files of the code they test and are
+built into the ns-3 modules; and so fit the description of BVTs.  BVTs live
+in the same source code that is built into the ns-3 code.  Our current tests
+are examples of this kind of test.
+
+Unit Tests
++++++++++
+
+Unit tests are more involved tests that go into detail to make sure that a
+piece of code works as advertised in isolation.  There is really no reason
+for this kind of test to be built into an ns-3 module.  It turns out, for
+example, that the unit tests for the object name service are about the same
+size as the object name service code itself.  Unit tests are tests that
+check a single bit of functionality that are not built into the ns-3 code,
+but live in the same directory as the code it tests.  It is possible that
+these tests check integration of multiple implementation files in a module
+as well.  The file src/core/test/names-test-suite.cc is an example of this kind
+of test.  The file src/network/test/pcap-file-test-suite.cc is another example
+that uses a known good pcap file as a test vector file.  This file is stored
+locally in the src/network directory.
+
+System Tests
++++++++++++
+
+System tests are those that involve more than one module in the system.  We
+have lots of this kind of test running in our current regression framework,
+but they are typically overloaded examples.  We provide a new place 
+for this kind of test in the directory ``src/test``.  The file
+src/test/ns3tcp/ns3-interop-test-suite.cc is an example of this kind of
+test.  It uses NSC TCP to test the ns-3 TCP implementation.  Often there
+will be test vectors required for this kind of test, and they are stored in
+the directory where the test lives.  For example,
+ns3tcp-interop-response-vectors.pcap is a file consisting of a number of TCP
+headers that are used as the expected responses of the ns-3 TCP under test
+to a stimulus generated by the NSC TCP which is used as a ''known good''
+implementation.
+
+Examples
++++++++
+
+The examples are tested by the framework to make sure they built and will
+run.  Nothing is checked, and currently the pcap files are just written off
+into /tmp to be discarded.  If the examples run (don't crash) they pass this
+smoke test.
+
+Performance Tests
+++++++++++++++++
+
+Performance tests are those which exercise a particular part of the system
+and determine if the tests have executed to completion in a reasonable time.
+
+Running Tests
+++++++++++++
+
+Tests are typically run using the high level ``test.py`` program. To get a list of the available command-line options, run ``test.py --help``
+ 
+
+Debugging Tests
+***************
+
+The debugging of the test programs is best performed running the low-level test-runner program. The test-runner is the bridge from generic Python code to |ns3| code. It is written in C++ and uses the automatic test discovery process in the 
+|ns3| code to find and allow execution of all of the various tests.
+
+The main reason why ``test.py`` is not suitable for debugging is that it is not allowed for logging to be turned on using the ``NS_LOG`` environmental variable when test.py runs.  This limitation does not apply to the test-runner executable. Hence, if you want to see logging output from your tests, you have to run them using the test-runner directly.
+
+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"
+
+You should see something like the following::
+
+  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'
+  'build' finished successfully (0.353s)
+  --assert:               Tell tests to segfault (like assert) if an error is detected
+  --basedir=dir:          Set the base directory (where to find src) to ''dir''
+  --tempdir=dir:          Set the temporary directory (where to find data files) to ''dir''
+  --constrain=test-type:  Constrain checks to test suites of type ''test-type''
+  --help:                 Print this message
+  --kinds:                List all of the available kinds of tests
+  --list:                 List all of the test suites (optionally constrained by test-type)
+  --out=file-name:        Set the test status output file to ''file-name''
+  --suite=suite-name:     Run the test suite named ''suite-name''
+  --verbose:              Turn on messages in the run test suites
+
+There are a number of things available to you which will be familiar to you if
+you have looked at ``test.py``.  This should be expected since the test-
+runner is just an interface between ``test.py`` and |ns3|.  You 
+may notice that example-related commands are missing here.  That is because 
+the examples are really not |ns3| tests.  ``test.py`` runs them
+as if they were to present a unified testing environment, but they are really
+completely different and not to be found here.
+
+The first new option that appears here, but not in test.py is the ``--assert``
+option.  This option is useful when debugging a test case when running under a 
+debugger like ``gdb``.  When selected, this option tells the underlying
+test case to cause a segmentation violation if an error is detected.  This has
+the nice side-effect of causing program execution to stop (break into the 
+debugger) when an error is detected.  If you are using gdb, you could use this
+option something like,
+
+::
+
+  ./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``
+that detected the error.
+
+Another new option that appears here is the ``--basedir`` option.  It turns out
+that some tests may need to reference the source directory of the |ns3|  
+distribution to find local data, so a base directory is always required to run
+a test.
+
+If you run a test from test.py, the Python program will provide the basedir 
+option for you.  To run one of the tests directly from the test-runner 
+using ``waf``, you will need to specify the test suite to run along with 
+the base directory.  So you could use the shell and do::
+
+  ./waf --run "test-runner --basedir=`pwd` --suite=pcap-file-object"
+
+Note the ''backward'' quotation marks on the ``pwd`` command.  
+
+If you are running the test suite out of a debugger, it can be quite painful 
+to remember and constantly type the absolute path of the distribution base 
+directory.
+Because of this, if you omit the basedir, the test-runner will try to figure one
+out for you.  It begins in the current working directory and walks up the 
+directory tree looking for a directory file with files named ``VERSION`` and
+``LICENSE.``  If it finds one, it assumes that must be the basedir and provides
+it for you.
+
+Similarly, many test suites need to write temporary files (such as pcap files)
+in the process of running the tests.  The tests then need a temporary directory
+to write to.  The Python test utility (test.py) will provide a temporary file
+automatically, but if run stand-alone this temporary directory must be provided.
+Just as in the basedir case, it can be annoying to continually have to provide
+a ``--tempdir``, so the test runner will figure one out for you if you don't
+provide one.  It first looks for environment variables named ``TMP`` and 
+``TEMP`` and uses those.  If neither ``TMP`` nor ``TEMP`` are defined
+it picks ``/tmp``.  The code then tacks on an identifier indicating what 
+created the directory (ns-3) then the time (hh.mm.ss) followed by a large random
+number.  The test runner creates a directory of that name to be used as the
+temporary directory.  Temporary files then go into a directory that will be
+named something like
+
+::
+
+  /tmp/ns-3.10.25.37.61537845
+
+The time is provided as a hint so that you can relatively easily reconstruct
+what directory was used if you need to go back and look at the files that were
+placed in that directory.
+
+When you run a test suite using the test-runner it will run the test quietly
+by default.  The only indication that you will get that the test passed is 
+the *absence* of a message from ``waf`` saying that the program 
+returned something other than a zero exit code.  To get some output from the
+test, you need to specify an output file to which the tests will write their 
+XML status using the ``--out`` option.  You need to be careful interpreting
+the results because the test suites will *append* results onto this file.
+Try,
+
+::
+
+  ./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,
+
+::
+
+  <TestSuite>
+    <SuiteName>pcap-file-object</SuiteName>
+    <TestCase>
+      <CaseName>Check to see that PcapFile::Open with mode ''w'' works</CaseName>
+      <CaseResult>PASS</CaseResult>
+      <CaseTime>real 0.00 user 0.00 system 0.00</CaseTime>
+    </TestCase>
+    <TestCase>
+      <CaseName>Check to see that PcapFile::Open with mode ''r'' works</CaseName>
+      <CaseResult>PASS</CaseResult>
+      <CaseTime>real 0.00 user 0.00 system 0.00</CaseTime>
+    </TestCase>
+    <TestCase>
+      <CaseName>Check to see that PcapFile::Open with mode ''a'' works</CaseName>
+      <CaseResult>PASS</CaseResult>
+      <CaseTime>real 0.00 user 0.00 system 0.00</CaseTime>
+    </TestCase>
+    <TestCase>
+      <CaseName>Check to see that PcapFileHeader is managed correctly</CaseName>
+      <CaseResult>PASS</CaseResult>
+      <CaseTime>real 0.00 user 0.00 system 0.00</CaseTime>
+    </TestCase>
+    <TestCase>
+      <CaseName>Check to see that PcapRecordHeader is managed correctly</CaseName>
+      <CaseResult>PASS</CaseResult>
+      <CaseTime>real 0.00 user 0.00 system 0.00</CaseTime>
+    </TestCase>
+    <TestCase>
+      <CaseName>Check to see that PcapFile can read out a known good pcap file</CaseName>
+      <CaseResult>PASS</CaseResult>
+      <CaseTime>real 0.00 user 0.00 system 0.00</CaseTime>
+    </TestCase>
+    <SuiteResult>PASS</SuiteResult>
+    <SuiteTime>real 0.00 user 0.00 system 0.00</SuiteTime>
+  </TestSuite>
+
+If you are familiar with XML this should be fairly self-explanatory.  It is 
+also not a complete XML file since test suites are designed to have their
+output appended to a master XML status file as described in the ``test.py``
+section.
+
+Class TestRunner
+****************
+
+The executables that run dedicated test programs use a TestRunner class.  This
+class provides for automatic test registration and listing, as well as a way to
+execute the individual tests.  Individual test suites use C++ global 
+constructors
+to add themselves to a collection of test suites managed by the test runner.
+The test runner is used to list all of the available tests and to select a test
+to be run.  This is a quite simple class that provides three static methods to
+provide or Adding and Getting test suites to a collection of tests.  See the 
+doxygen for class ``ns3::TestRunner`` for details.
+
+Test Suite
+**********
+
+All |ns3| tests are classified into Test Suites and Test Cases.  A 
+test suite is a collection of test cases that completely exercise a given kind
+of functionality.  As described above, test suites can be classified as,
+
+* Build Verification Tests
+* Unit Tests 
+* System Tests
+* Examples
+* Performance Tests
+
+This classification is exported from the TestSuite class.  This class is quite
+simple, existing only as a place to export this type and to accumulate test
+cases.  From a user perspective, in order to create a new TestSuite in the 
+system one only has to define a new class that inherits from class ``TestSuite``
+and perform these two duties.
+
+The following code will define a new class that can be run by ``test.py``
+as a ''unit'' test with the display name, ``my-test-suite-name``.
+
+::
+
+  class MySuite : public TestSuite
+  {
+  public:
+    MyTestSuite ();
+  };
+  
+  MyTestSuite::MyTestSuite ()
+    : TestSuite ("my-test-suite-name", UNIT)
+  {
+    AddTestCase (new MyTestCase);
+  }
+  
+  MyTestSuite myTestSuite;
+
+The base class takes care of all of the registration and reporting required to
+be a good citizen in the test framework.
+
+Test Case
+*********
+
+Individual tests are created using a TestCase class.  Common models for the use
+of a test case include "one test case per feature", and "one test case per method."
+Mixtures of these models may be used.
+
+In order to create a new test case in the system, all one has to do is to inherit
+from the  ``TestCase`` base class, override the constructor to give the test 
+case a name and override the ``DoRun`` method to run the test.
+
+::
+
+  class MyTestCase : public TestCase
+  {
+    MyTestCase ();
+    virtual void DoRun (void);
+  };
+  
+  MyTestCase::MyTestCase ()
+    : TestCase ("Check some bit of functionality")
+  {
+  }
+  
+  void
+  MyTestCase::DoRun (void)
+  {
+    NS_TEST_ASSERT_MSG_EQ (true, true, "Some failure message");
+  }
+
+Utilities
+++++++++
+
+There are a number of utilities of various kinds that are also part of the 
+testing framework.  Examples include a generalized pcap file useful for
+storing test vectors; a generic container useful for transient storage of
+test vectors during test execution; and tools for generating presentations
+based on validation and verification testing results.
+
+Debugging test suite failures
+++++++++++++++++++++++++++++
+
+To debug test crashes, such as::
+
+  CRASH: TestSuite ns3-wifi-interference
+
+You can access the underlying test-runner program via gdb as follows, and
+then pass the "--basedir=`pwd`" argument to run (you can also pass other
+arguments as needed, but basedir is the minimum needed)::
+
+  ./waf --command-template="gdb %s" --run "test-runner"
+  Waf: 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)
+  GNU gdb 6.8-debian
+  Copyright (C) 2008 Free Software Foundation, Inc.
+  L cense GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
+  This is free software: you are free to change and redistribute it.
+  There is NO WARRANTY, to the extent permitted by law.  Type "show copying"
+  and "show warranty" for details.
+  This GDB was configured as "x86_64-linux-gnu"...
+  (gdb) r --basedir=`pwd`
+  Starting program: <..>/build/debug/utils/test-runner --basedir=`pwd`
+  [Thread debugging using libthread_db enabled]
+  assert failed. file=../src/core/model/type-id.cc, line=138, cond="uid <= m_information.size () && uid != 0"
+  ...
+
+Here is another example of how to use valgrind to debug a memory problem
+such as::
+
+  VALGR: TestSuite devices-mesh-dot11s-regression
+
+  ./waf --command-template="valgrind %s --basedir=`pwd` --suite=devices-mesh-dot11s-regression" --run test-runner
@@ -0,0 +1,18 @@
+.. include:: replace.txt
+
+Overview
+--------
+
+This document is concerned with the testing and validation of |ns3| software.
+
+This document provides
+
+* background about terminology and software testing (Chapter 2);
+* a description of the ns-3 testing framework (Chapter 3);
+* a guide to model developers or new model contributors for how to write tests (Chapter 4);
+
+In brief, the first three chapters should be read by ns developers and 
+contributors who need to understand how to contribute test code and
+validated programs, and
+the remainder of the document provides space for people to report on what
+aspects of selected models have been validated.
@@ -0,0 +1,9 @@
+Tests
+-----
+
+.. toctree::
+
+   test-overview
+   test-background
+   test-framework
+   how-to-write-tests
@@ -0,0 +1,82 @@
+.. include:: replace.txt
+
+Troubleshooting
+---------------
+
+This chapter posts some information about possibly common errors in building
+or running |ns3| programs.
+
+Please note that the wiki
+(`<http://www.nsnam.org/wiki/index.php/Troubleshooting>`_) may have contributed
+items.
+
+Build errors
+************
+
+Run-time errors
+***************
+
+Sometimes, errors can occur with a program after a successful build. These are
+run-time errors, and can commonly occur when memory is corrupted or pointer
+values are unexpectedly null.
+
+Here is an example of what might occur:::
+
+    ns-old:~/ns-3-nsc$ ./waf --run tcp-point-to-point
+    Entering directory `/home/tomh/ns-3-nsc/build'
+    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/>`_:::
+
+    ns-old:~/ns-3-nsc$ ./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.
+    GDB is free software, covered by the GNU General Public License, and you are
+    welcome to change it and/or distribute copies of it under certain conditions.
+    Type "show copying" to see the conditions.
+    There is absolutely no warranty for GDB.  Type "show warranty" for details.
+    This GDB was configured as "i386-redhat-linux-gnu"...Using host libthread_db 
+    library "/lib/libthread_db.so.1".
+
+    (gdb) run
+    Starting program: /home/tomh/ns-3-nsc/build/debug/examples/tcp-point-to-point 
+    Reading symbols from shared object read from target memory...done.
+    Loaded system supplied DSO at 0xf5c000
+
+    Program received signal SIGSEGV, Segmentation fault.
+    0x0804aa12 in main (argc=1, argv=0xbfdfefa4)
+        at ../examples/tcp-point-to-point.cc:136
+    136       Ptr<Socket> localSocket = socketFactory->CreateSocket ();
+    (gdb) p localSocket
+    $1 = {m_ptr = 0x3c5d65}
+    (gdb) p socketFactory
+    $2 = {m_ptr = 0x0}
+    (gdb) quit
+    The program is running.  Exit anyway? (y or n) y
+
+Note first the way the program was invoked-- pass the command to run as an
+argument to the command template "gdb %s".  
+
+This tells us that there was an attempt to dereference a null pointer
+socketFactory.
+
+Let's look around line 136 of tcp-point-to-point, as gdb suggests:::
+
+  Ptr<SocketFactory> socketFactory = n2->GetObject<SocketFactory> (Tcp::iid);
+  Ptr<Socket> localSocket = socketFactory->CreateSocket ();
+  localSocket->Bind ();
+
+The culprit here is that the return value of GetObject is not being checked and
+may be null.  
+
+Sometimes you may need to use the `valgrind memory checker
+<http://valgrind.org>`_ for more subtle errors. Again, you invoke the use of
+valgrind similarly:::
+
+    ns-old:~/ns-3-nsc$ ./waf --run tcp-point-to-point --command-template="valgrind %s"
@@ -0,0 +1,264 @@
+EPSTOPDF = epstopdf
+DIA = dia
+CONVERT = convert
+
+SRC = ../../src
+# Temporary source directory, for build
+SOURCETEMP = source-temp
+FIGURES = $(SOURCETEMP)/figures
+
+# list all model library .rst files that need to be copied to $SOURCETEMP
+SOURCES = \
+	source/conf.py \
+	source/_static \
+	source/index.rst \
+	source/replace.txt \
+	source/organization.rst \
+	source/internet-models.rst \
+	source/network.rst \
+	source/emulation-overview.rst \
+	$(SRC)/aodv/doc/aodv.rst \
+	$(SRC)/applications/doc/applications.rst \
+	$(SRC)/bridge/doc/bridge.rst \
+	$(SRC)/click/doc/click.rst \
+	$(SRC)/csma/doc/csma.rst \
+	$(SRC)/dsdv/doc/dsdv.rst \
+	$(SRC)/mpi/doc/distributed.rst \
+	$(SRC)/energy/doc/energy.rst \
+	$(SRC)/emu/doc/emu.rst \
+	$(SRC)/tap-bridge/doc/tap.rst \
+	$(SRC)/mesh/doc/mesh.rst \
+	$(SRC)/lte/doc/lte.rst \
+	$(SRC)/propagation/doc/propagation.rst \
+	$(SRC)/network/doc/network-overview.rst \
+	$(SRC)/network/doc/packets.rst \
+	$(SRC)/network/doc/sockets-api.rst \
+	$(SRC)/network/doc/simple.rst \
+	$(SRC)/internet/doc/internet-stack.rst \
+	$(SRC)/internet/doc/ipv4.rst \
+	$(SRC)/internet/doc/ipv6.rst \
+	$(SRC)/internet/doc/routing-overview.rst \
+	$(SRC)/internet/doc/tcp.rst \
+	$(SRC)/olsr/doc/olsr.rst \
+	$(SRC)/openflow/doc/openflow-switch.rst \
+	$(SRC)/point-to-point/doc/point-to-point.rst \
+	$(SRC)/wifi/doc/wifi.rst \
+	$(SRC)/wimax/doc/wimax.rst \
+	$(SRC)/uan/doc/uan.rst \
+	$(SRC)/stats/doc/statistics.rst \
+	$(SRC)/netanim/doc/animation.rst \
+	$(SRC)/flow-monitor/doc/flow-monitor.rst \
+
+# list all model library figure files that need to be copied to 
+# $SOURCETEMP/figures.  For each figure to be included in all
+# documentation formats (html, latex...) the following formats are supported: 
+#  1) a single .dia file (preferred option, because it can be edited)
+#  2) a single .eps file
+#  3) both a .pdf and .png file
+SOURCEFIGS = \
+	figures/testbed.dia \
+	figures/emulated-channel.dia \
+	$(SRC)/network/doc/packet.dia \
+	$(SRC)/network/doc/node.dia \
+	$(SRC)/network/doc/buffer.dia \
+	$(SRC)/network/doc/sockets-overview.dia \
+	$(SRC)/internet/doc/internet-node-send.dia \
+	$(SRC)/internet/doc/internet-node-recv.dia \
+	$(SRC)/internet/doc/routing.dia \
+	$(SRC)/internet/doc/routing-specialization.dia \
+	$(SRC)/wifi/doc/WifiArchitecture.dia \
+	$(SRC)/wifi/doc/snir.dia \
+	$(SRC)/wimax/doc/WimaxArchitecture.dia \
+	$(SRC)/lte/doc/lte-transmission.png \
+	$(SRC)/lte/doc/lte-transmission.pdf \
+	$(SRC)/uan/doc/auvmobility-classes.dia \
+	$(SRC)/stats/doc/Stat-framework-arch.png \
+	$(SRC)/stats/doc/Wifi-default.png \
+	$(SRC)/netanim/doc/animation-dumbbell.png \
+	$(SRC)/netanim/doc/animation-dumbbell.pdf \
+
+# specify figures from which .png and .pdf figures need to be
+# generated (all dia and eps figures)
+IMAGES_EPS = \
+	$(FIGURES)/testbed.eps \
+	$(FIGURES)/emulated-channel.eps \
+	$(FIGURES)/packet.eps \
+	$(FIGURES)/node.eps \
+	$(FIGURES)/buffer.eps \
+	$(FIGURES)/sockets-overview.eps \
+	$(FIGURES)/internet-node-send.eps \
+	$(FIGURES)/internet-node-recv.eps \
+	$(FIGURES)/routing.eps \
+	$(FIGURES)/routing-specialization.eps \
+	$(FIGURES)/WifiArchitecture.eps \
+	$(FIGURES)/snir.eps \
+	$(FIGURES)/WimaxArchitecture.eps \
+        $(FIGURES)/auvmobility-classes.eps \
+
+# rescale pdf figures as necessary
+$(FIGURES)/testbed.pdf_width = 5in
+$(FIGURES)/emulated-channel.pdf_width = 6in
+$(FIGURES)/node.pdf_width = 5in
+$(FIGURES)/packet.pdf_width = 4in
+$(FIGURES)/buffer.pdf_width = 15cm
+$(FIGURES)/sockets-overview.pdf_width = 10cm
+$(FIGURES)/internet-node-send.pdf_width = 5in
+$(FIGURES)/internet-node-recv.pdf_width = 5in
+$(FIGURES)/routing.pdf_width = 6in
+$(FIGURES)/routing-specialization.pdf_width = 5in
+$(FIGURES)/snir.pdf_width = 3in
+$(FIGURES)/lte-transmission.pdf_width = 3in
+$(FIGURES)/auvmobility-classes.pdf_width = 10cm
+
+IMAGES_PNG = ${IMAGES_EPS:.eps=.png}
+IMAGES_PDF = ${IMAGES_EPS:.eps=.pdf}
+
+IMAGES = $(IMAGES_EPS) $(IMAGES_PNG) $(IMAGES_PDF)
+
+%.eps : %.dia; $(DIA) -t eps $< -e $@
+%.png : %.dia; $(DIA) -t png $< -e $@
+%.png : %.eps; $(CONVERT) $< $@
+%.pdf : %.eps; $(EPSTOPDF) $< -o=$@; if test x$($@_width) != x; then TMPFILE=`mktemp`; ./rescale-pdf.sh $($@_width) $@ $${TMPFILE} && mv $${TMPFILE} $@; fi
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+PAPER         =
+BUILDDIR      = build
+
+# Internal variables.
+PAPEROPT_a4     = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(SOURCETEMP) 
+
+.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest
+
+help:
+	@echo "Please use \`make <target>' where <target> is one of"
+	@echo "  html       to make standalone HTML files"
+	@echo "  dirhtml    to make HTML files named index.html in directories"
+	@echo "  singlehtml to make a single large HTML file"
+	@echo "  pickle     to make pickle files"
+	@echo "  json       to make JSON files"
+	@echo "  htmlhelp   to make HTML files and a HTML help project"
+	@echo "  qthelp     to make HTML files and a qthelp project"
+	@echo "  devhelp    to make HTML files and a Devhelp project"
+	@echo "  epub       to make an epub"
+	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"
+	@echo "  text       to make text files"
+	@echo "  man        to make manual pages"
+	@echo "  changes    to make an overview of all changed/added/deprecated items"
+	@echo "  linkcheck  to check all external links for integrity"
+	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
+
+copy-sources:  $(SOURCES)
+	@rm -rf $(SOURCETEMP)
+	@mkdir -p $(SOURCETEMP) 
+	@mkdir -p $(FIGURES) 
+	@cp -r $(SOURCES) $(SOURCETEMP)
+	@cp -r $(SOURCEFIGS) $(FIGURES)
+
+clean:
+	-rm -rf $(BUILDDIR)/*
+	-rm -rf $(SOURCETEMP)
+
+frag: pickle
+	@if test ! -d $(BUILDDIR)/frag; then mkdir $(BUILDDIR)/frag; fi
+	pushd $(BUILDDIR)/frag && ../../pickle-to-xml.py ../pickle/index.fpickle  > navigation.xml && popd
+	cp -r $(BUILDDIR)/pickle/_images $(BUILDDIR)/frag
+
+html: copy-sources $(IMAGES) 
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+dirhtml: copy-sources $(IMAGES)
+	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+
+singlehtml: copy-sources $(IMAGES)
+	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
+	@echo
+	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
+
+pickle: copy-sources $(IMAGES)
+	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
+	@echo
+	@echo "Build finished; now you can process the pickle files."
+
+json: copy-sources $(IMAGES)
+	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
+	@echo
+	@echo "Build finished; now you can process the JSON files."
+
+htmlhelp: copy-sources $(IMAGES)
+	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
+	@echo
+	@echo "Build finished; now you can run HTML Help Workshop with the" \
+	      ".hhp project file in $(BUILDDIR)/htmlhelp."
+
+qthelp: copy-sources $(IMAGES)
+	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
+	@echo
+	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
+	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
+	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/ns-3.qhcp"
+	@echo "To view the help file:"
+	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/ns-3.qhc"
+
+devhelp: copy-sources $(IMAGES)
+	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
+	@echo
+	@echo "Build finished."
+	@echo "To view the help file:"
+	@echo "# mkdir -p $$HOME/.local/share/devhelp/ns-3"
+	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/ns-3"
+	@echo "# devhelp"
+
+epub: copy-sources $(IMAGES)
+	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
+	@echo
+	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
+
+latex: copy-sources $(IMAGES)
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo
+	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
+	@echo "Run \`make' in that directory to run these through (pdf)latex" \
+	      "(use \`make latexpdf' here to do that automatically)."
+
+latexpdf: copy-sources $(IMAGES)
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo "Running LaTeX files through pdflatex..."
+	make -C $(BUILDDIR)/latex all-pdf
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+text: copy-sources $(IMAGES)
+	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
+	@echo
+	@echo "Build finished. The text files are in $(BUILDDIR)/text."
+
+man: copy-sources $(IMAGES)
+	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
+	@echo
+	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
+
+changes: copy-sources $(IMAGES)
+	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
+	@echo
+	@echo "The overview file is in $(BUILDDIR)/changes."
+
+linkcheck: copy-sources $(IMAGEs)
+	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+	@echo
+	@echo "Link check complete; look for any errors in the above output " \
+	      "or in $(BUILDDIR)/linkcheck/output.txt."
+
+doctest: copy-sources $(IMAGES)
+	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
+	@echo "Testing of doctests in the sources finished, look at the " \
+	      "results in $(BUILDDIR)/doctest/output.txt."
+
+
@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+
+TMPFILE=`mktemp`
+
+echo "\documentclass{book}
+\usepackage{pdfpages}
+\begin{document}
+\includepdf[width=${1},fitpaper]{${2}}
+\end{document}" >${TMPFILE}.tex
+pdflatex -output-directory /tmp ${TMPFILE}.tex >/dev/null 2>/dev/null
+cp ${TMPFILE}.pdf ${3}
+
@@ -0,0 +1,2 @@
+This directory stores .rst files that are used to build the model library
+documentation but that are not stored with a particular module.
@@ -0,0 +1,216 @@
+# -*- coding: utf-8 -*-
+#
+# ns-3 documentation build configuration file, created by
+# sphinx-quickstart on Tue Dec 14 09:00:39 2010.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys, os
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#sys.path.insert(0, os.path.abspath('.'))
+
+# -- General configuration -----------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be extensions
+# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
+extensions = ['sphinx.ext.pngmath']
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+# The encoding of source files.
+#source_encoding = 'utf-8-sig'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = u'ns-3'
+copyright = u'2011, ns-3 project'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = 'ns-3-dev'
+# The full version, including alpha/beta/rc tags.
+release = 'ns-3-dev'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#language = None
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+#today = ''
+# Else, today_fmt is used as the format for a strftime call.
+#today_fmt = '%B %d, %Y'
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+exclude_patterns = []
+
+# The reST default role (used for this markup: `text`) to use for all documents.
+#default_role = None
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+#add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+#add_module_names = True
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+#show_authors = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# A list of ignored prefixes for module index sorting.
+#modindex_common_prefix = []
+
+
+# -- Options for HTML output ---------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+html_theme = 'default'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+#html_theme_options = {}
+
+# Add any paths that contain custom themes here, relative to this directory.
+#html_theme_path = []
+
+# The name for this set of Sphinx documents.  If None, it defaults to
+# "<project> v<release> documentation".
+#html_title = None
+
+# A shorter title for the navigation bar.  Default is the same as html_title.
+#html_short_title = None
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+#html_logo = None
+
+# The name of an image file (within the static path) to use as favicon of the
+# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+#html_favicon = None
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+#html_last_updated_fmt = '%b %d, %Y'
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+#html_use_smartypants = True
+
+# Custom sidebar templates, maps document names to template names.
+#html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+#html_additional_pages = {}
+
+# If false, no module index is generated.
+#html_domain_indices = True
+
+# If false, no index is generated.
+#html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+#html_split_index = False
+
+# If true, links to the reST sources are added to the pages.
+#html_show_sourcelink = True
+
+# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
+#html_show_sphinx = True
+
+# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
+#html_show_copyright = True
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> tag referring to it.  The value of this option must be the
+# base URL from which the finished HTML is served.
+#html_use_opensearch = ''
+
+# This is the file name suffix for HTML files (e.g. ".xhtml").
+#html_file_suffix = None
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'ns-3doc'
+
+
+# -- Options for LaTeX output --------------------------------------------------
+
+# The paper size ('letter' or 'a4').
+#latex_paper_size = 'letter'
+
+# The font size ('10pt', '11pt' or '12pt').
+#latex_font_size = '10pt'
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, documentclass [howto/manual]).
+latex_documents = [
+  ('index', 'ns-3-model-library.tex', u'ns-3 Model Library',
+   u'ns-3 project', 'manual'),
+]
+
+# The name of an image file (relative to this directory) to place at the top of
+# the title page.
+#latex_logo = None
+
+# For "manual" documents, if this is true, then toplevel headings are parts,
+# not chapters.
+#latex_use_parts = False
+
+# If true, show page references after internal links.
+#latex_show_pagerefs = False
+
+# If true, show URL addresses after external links.
+#latex_show_urls = False
+
+# Additional stuff for the LaTeX preamble.
+#latex_preamble = ''
+
+# Documents to append as an appendix to all manuals.
+#latex_appendices = []
+
+# If false, no module index is generated.
+#latex_domain_indices = True
+
+
+# -- Options for manual page output --------------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    ('index', 'ns-3-model-library', u'ns-3 Model Library',
+     [u'ns-3 project'], 1)
+]
@@ -0,0 +1,76 @@
+.. include:: replace.txt
+
+Emulation Overview
+------------------
+
+|ns3| has been designed for integration into testbed and virtual machine
+environments. We have addressed this need by providing two kinds of net devices.
+The first kind, which we call an ``Emu`` ``NetDevice`` allows |ns3| simulations
+to send data on a "real" network. The second kind, called a ``Tap``
+``NetDevice`` allows a "real" host to participate in an |ns3| simulation as if
+it were one of the simulated nodes. An |ns3| simulation may be constructed with
+any combination of simulated, ``Emu``, or ``Tap`` devices.
+
+One of the use-cases we want to support is that of a testbed. A concrete example
+of an environment of this kind is the ORBIT testbed. ORBIT is a laboratory
+emulator/field trial network arranged as a two dimensional grid of 400 802.11
+radio nodes. We integrate with ORBIT by using their "imaging" process to load
+and run |ns3| simulations on the ORBIT array. We use our ``Emu`` ``NetDevice``
+to drive the hardware in the testbed and we can accumulate results either using
+the |ns3| tracing and logging functions, or the native ORBIT data gathering
+techniques. See `<http://www.orbit-lab.org/>`_ for details on the ORBIT
+testbed.
+
+A simulation of this kind is shown in the following figure:
+
+.. _testbed:
+
+.. figure:: figures/testbed.*
+   
+   Example Implementation of Testbed Emulation.
+
+You can see that there are separate hosts, each running a subset of a "global"
+simulation. Instead of an |ns3| channel connecting the hosts, we use real
+hardware provided by the testbed. This allows |ns3| applications and protocol
+stacks attached to a simulation node to communicate over real hardware.
+
+We expect the primary use for this configuration will be to generate repeatable
+experimental results in a real-world network environment that includes all of
+the |ns3| tracing, logging, visualization and statistics gathering tools.
+
+In what can be viewed as essentially an inverse configuration, we allow "real"
+machines running native applications and protocol stacks to integrate with an
+|ns3| simulation. This allows for the simulation of large networks connected to
+a real machine, and also enables virtualization. A simulation of this kind is
+shown in the following figure:
+
+.. _emulated-channel:
+
+.. figure:: figures/emulated-channel.*
+
+    Implementation overview of emulated channel.
+
+Here, you will see that there is a single host with a number of virtual machines
+running on it. An |ns3| simulation is shown running in the virtual machine shown
+in the center of the figure. This simulation has a number of nodes with
+associated |ns3| applications and protocol stacks that are talking to an |ns3|
+channel through native simulated |ns3| net devices.
+
+There are also two virtual machines shown at the far left and far right of the
+figure. These VMs are running native (Linux) applications and protocol stacks.
+The VM is connected into the simulation by a Linux Tap net device. The user-mode
+handler for the Tap device is instantiated in the simulation and attached to a
+proxy node that represents the native VM in the simulation. These handlers allow
+the Tap devices on the native VMs to behave as if they were |ns3| net devices in
+the simulation VM. This, in turn, allows the native software and protocol suites
+in the native VMs to believe that they are connected to the simulated |ns3|
+channel.
+
+We expect the typical use case for this environment will be to analyze the
+behavior of native applications and protocol suites in the presence of large
+simulated |ns3| networks.
+
+.. toctree::
+
+  emu
+  tap
@@ -0,0 +1,44 @@
+.. only:: html or latex
+
+ns-3 Model Library
+==================
+
+This is the *ns-3 Model Library* documentation. Primary documentation for the ns-3 project is 
+available in five forms:
+
+* `ns-3 Doxygen <http://www.nsnam.org/doxygen/index.html>`_: Documentation of the public APIs of the simulator
+* Tutorial, Manual, and Model Library *(this document)* for the `latest release <http://www.nsnam.org/documentation/latest/>`_ and `development tree <http://www.nsnam.org/ns-3-dev/documentation/>`_
+* `ns-3 wiki <http://www.nsnam.org/wiki/index.php/Main_Page>`_ 
+
+This document is written in `reStructuredText <http://docutils.sourceforge.net/rst.html>`_ for `Sphinx <http://sphinx.pocoo.org/>`_ and is maintained in the
+``doc/models`` directory of ns-3's source code.
+
+.. toctree::
+   :maxdepth: 2
+
+   organization
+   animation
+   aodv
+   applications
+   bridge
+   click
+   csma
+   dsdv
+   emulation-overview
+   energy
+   flow-monitor
+   internet-models
+   lte
+   mesh
+   distributed
+   network
+   olsr
+   openflow-switch
+   point-to-point
+   propagation
+   simple
+   statistics
+   topology
+   uan
+   wifi
+   wimax
@@ -0,0 +1,10 @@
+Internet Models
+---------------
+
+.. toctree::
+
+   internet-stack
+   ipv4
+   ipv6
+   routing-overview
+   tcp
@@ -0,0 +1,9 @@
+Network Module
+--------------
+
+.. toctree::
+
+    packets
+    network-overview
+    sockets-api
+    simple
@@ -0,0 +1,47 @@
+.. include:: replace.txt
+
+Organization
+------------
+
+This manual compiles documentation for |ns3| models and supporting
+software that enable users to construct network simulations.
+It is important to distinguish between **modules** and **models**:
+
+* |ns3| software is organized into separate *modules* that are each
+  built as a separate software library.  Individual ns-3 programs can link
+  the modules (libraries) they need to conduct their simulation.
+
+* |ns3| *models* are abstract representations of real-world objects,
+  protocols, devices, etc.  
+
+An |ns3| module may consist of more than one model (for instance, the
+:mod:`internet` module contains models for both TCP and UDP).  In general,
+ns-3 models do not span multiple software modules, however.  
+
+This manual provides documentation about the models of |ns3|.  It 
+complements two other sources of documentation concerning models:
+
+* the model APIs are documented, from a programming perspective, using
+  `Doxygen <http://www.doxygen.org>`_.  Doxygen for ns-3 models is available
+  `on the project web server <http://www.nsnam.org/docs/doxygen/index.html>`_. 
+
+* the |ns3| core is documented in the developer's manual.  |ns3| models make
+  use of the facilities of the core, such as attributes, default values, 
+  random numbers, test frameworks, etc.  Consult the 
+  `main web site <http://www.nsnam.org>`_ to find copies of the manual.
+
+Finally, additional documentation about various aspects of |ns3| may
+exist on the `project wiki <http://www.nsnam.org/wiki>`_.
+
+A sample outline of how to write model library documentation can be
+found in :mod:`src/template/doc`.
+
+The remainder of this document is organized alphabetically by module name.
+
+If you are new to |ns3|, you might first want to read below about the network
+module, which contains some fundamental models for the simulator.
+The packet model, models for different address formats, and abstract 
+base classes for objects such as nodes, net devices, channels, sockets, and 
+applications are discussed there.
+
+
@@ -0,0 +1,3 @@
+.. |ns3| replace:: *ns-3*
+
+.. |ns2| replace:: *ns-2*
@@ -0,0 +1,33 @@
+/**
+ * @anchor modules_anchor
+ *
+ * @defgroup constructs C++ Constructs Used by All Modules
+ * \brief These are C++ constructs defined by the modules.
+ *
+ * @defgroup constants Constants
+ * @brief Constants you can change
+ *
+ * @defgroup utils Utils
+ * @brief The utils directory is for various programs and scripts related 
+ * to code coverage, test suites, style checking, and benchmarking.
+ *
+ * @defgroup core Core
+ * \brief The "core" module contains:
+ *    - a time management class to hold a time and convert between various time units: ns3::Time 
+ *    - a scheduler base class used to implement new simulation event schedulers:       
+ *      ns3::Scheduler and ns3::SchedulerFactory 
+ *    - a simulator class used to create, schedule and cancel events: ns3::Simulator
+ *    - a Functor class: ns3::Callback  
+ *    - an os-independent interface to get access to the elapsed wall clock time: ns3::SystemWallClockMs 
+ *    - a class to register regression tests with the test manager: ns3::Test and ns3::TestManager
+ *    - debugging facilities: \ref logging, \ref assert
+ *    - \ref randomvariable
+ *    - a base class for objects which need to support per-instance "attributes" and
+ *      trace sources: ns3::ObjectBase
+ *    - a base class for objects which need to support reference counting
+ *      and dynamic object aggregation: ns3::Object
+ *    - a smart-pointer class ns3::Ptr designed to work together with ns3::Object
+ *    - a configuration class used to set and control all attributes and trace sources
+ *      in a simulation: ns3::Config.
+ *
+ */
@@ -1,34 +1,199 @@
 Steps in doing an ns-3 release

-0. check out a clean ns-3-dev somewhere
-1. prepare the source files
+ns-3-dev preparation
+--------------------
+
+1. check out a clean ns-3-dev somewhere using ns-3-allinone (you will need it)
+   - hg clone http://code.nsnam.org/ns-3-allinone
+   - ./download.py
+   - ./build.py --enable-examples --enable-tests
+   - try building static, optimized, and debug versions
+   - try Python visualizer (not tested by buildbots)
+      -- ./waf --pyrun src/flow-monitor/examples/wifi-olsr-flowmon.py --vis
+   - cd ns-3-dev
+   - ensure that tests pass (./test.py -g) and make sure that the buildbots
+     are reporting greens based on the tip of the repository
+
+2. prepare the source files
   - revise and check in AUTHORS, if needed
-   - revise and check in RELEASE_NOTES
-   - update and check in VERSION to the latest release number
-   - confirm that Doxygen builds cleanly and without warnings
-     (./waf --doxygen), and check in any necessary changes 
-2. make a new "architecture.pdf" document and place it in the doc/ directory
-   of the ns-3-dev working directory
-3. ./waf configure; ./waf dist
-   - this will create a ns-3.0.x.tar.bz2 tarball
-4. test tarball on release platforms (waf check and maybe some other scripts)
-5. once you are happy with the tarball, tag ns-3-dev with "release ns-3.0.X"
-   - hg tag "release ns-3.0.x"
-   - hg push 
-6. clone the tagged ns-3-dev and place it on the repository
-   - ssh code.nsnam.org; sudo; su code;
-   - cp -r /home/code/repos/ns-3-dev /home/code/repos/ns-3.0.x
-   - cd /home/code/repos/ns-3.0.x/.hg and edit the hgrc appropriately
-7. upload "ns-3.0.x.tar.bz2" to the /var/www/html/releases/ directory on 
+   - revise and check in RELEASE_NOTES.  Make sure to edit the Availability 
+     section if this is a final release.
+   - DO NOT change VERSION at this time
+   - confirm that Doxygen builds cleanly (./waf doxygen), 
+     and check in any necessary changes. Currently, doxygen does not build
+     cleanly, we need to fix this over time.
+
+At this point, the ns-3-dev should be ready, except for changing the
+name of this repo from "3-dev" to the numbered release.  That will come
+in subsequent steps.
+
+ns-allinone-3.X.tar.bz2 dry run
+-------------------------------
+
+This phase is optional to dry-run a tarball before tagging.  You may skip
+to the next phase if you are ready to just make the release or release 
+candidate.  
+
+1. check out a clean ns-3-allinone again
+   - change into the allinone directory
+   - ./download.py
+   - cd ns-3-dev
+   - change VERSION to the appropriate string, either "3.X" (for a release) or
+     "3.X.RC1"  Do not commit this VERSION change to ns-3-dev.  It is used
+     by dist.py script to name the directory properly.
+   - cd into allinone directory and type "./dist.py"; you should see something
+     like this:
+
+NS-3 version: '3.12'
+Adding ns-3-dev as ns-allinone-3.12/ns-3.12
+Adding pybindgen as ns-allinone-3.12/pybindgen-0.15.0.795
+Adding nsc as ns-allinone-3.12/nsc-0.5.2
+Adding the build script files
+
+This will create an ns-allinone-3.X.tar.bz2 tarball
+
+2. test tarball on release platforms 
+   - optimized, debug, and static builds
+   - ./test.py -g
+   - make latexpdf in the doc/manual, doc/models, and doc/tutorial directories 
+   - ./waf --doxygen
+
+At this point, you are ready for final packaging and repository/site work
+
+tagging ns-3-dev and creating ns-3.X repositories
+-------------------------------------------------
+
+The steps here involve tagging ns-3-dev, copying over ns-3-dev to ns-3.X 
+on code.nsnam.org, cloning it locally, making changes from "3-dev" to "3.X" 
+in various places, and checking in those changes to the new ns-3.X repository.
+
+1. once you are happy with the tarball, tag ns-3-dev
+   - cd into ns-3-dev
+   - if release candidate
+     -- hg tag "ns-3.x-RCy"
+     -- hg push ssh://code@code.nsnam.org//home/code/repos/ns-3-dev
+   - else if final release
+     -- hg tag "ns-3.x"
+     -- hg push ssh://code@code.nsnam.org//home/code/repos/ns-3-dev
+
+2. copy the tagged ns-3-dev and place it on the repository
+   - ssh code.nsnam.org; sudo bash; su code;
+   - if release candidate
+     -- cp -r /home/code/repos/ns-3-dev /home/code/repos/ns-3.x-RCy
+     -- cd /home/code/repos/ns-3.x-RCy/.hg and edit the hgrc appropriately:
+       [paths]
+       default = /home/code/repos/ns-3.x-RCy
+       [web]
+       description = ns-3.x-RCy release
+       name = ns-3.x-RCy
+       contact = <ns-developers@isi.edu>
+   - else if final release
+     -- cp -r /home/code/repos/ns-3-dev /home/code/repos/ns-3.x
+     -- cd /home/code/repos/ns-3.x/.hg and edit the hgrc appropriately:
+       [paths]
+       default = /home/code/repos/ns-3.x
+       [web]
+       description = ns-3.x release
+       name = ns-3.x
+       contact = <ns-developers@isi.edu>
+
+3. If this is a final release (not RC)
+   - move (mv) ns-3.x RCs in /home/code/archived-repos
+
+4. check out a clean version of the new release (ns-3.x) or (ns-3.x-RCy) 
+   to your local machine 
+   - hg clone http://code.nsnam.org/ns-3.x or (-RCy)
+
+5. Update the VERSION for this new release
+   - change the string 3-dev in the VERSION file to the real version 
+     (e.g. 3.7 or 3.7-RC1)  This must agree with the version name you chose in the clone.
+   - change the version and release string for the documentation in 
+     doc/manual/source, doc/tutorial/source, and doc/models/source conf.py files
+     This should hopefully be updated in the future to simply pull from the
+     VERSION file.
+   - hg commit -m "update VERSION to ns-3.x" or (-RCy), you get the point
+   - hg push ssh://code@code.nsnam.org//home/code/repos/ns-3.x
+
+creating the distribution tarball
+---------------------------------
+
+1. Create final tarballs
+    You need to work with a clean ns-3-allinone-3.x directory
+   - hg clone http://code.nsnam.org/ns-3-allinone
+   - cd ns-3-allinone
+   - ./download.py -n ns-3.x
+   - ./dist.py (notice we did not build here)
+   - this will create an ns-allinone-3.x.tar.bz2 tarball
+   - sanity check this tarball just to make sure everything went ok
+
+2. upload "ns-allinone-3.x.tar.bz2" to the /var/www/html/releases/ directory on 
   the www.nsnam.org server
-8. update web page
-   - add link to news.html
-   - update getting_started.html
-   - update documents.html
-   - update roadmap on wiki
-   - build and update Doxygen directory on the server
-     -- ssh www.nsnam.org; sudo tcsh; su nsnam;
-     -- ~/bin/update-doxygen-release
-   - update and upload software architecture document (PDF, HTML)
-     -- note:  HTML image generation is not currently automatic
-9. announce to ns-developers, with summary of release notes
+   - scp ns-allinone-3.x.tar.bz2 www.nsnam.org:~
+   - ssh www.nsnam.org
+   - sudo cp ns-allinone-3.x.tar.bz2 /var/www/html/releases
+   - cd !$
+
+3. give it 644 file permissions, and user/group = apache if it is not already
+   - sudo chown apache:apache ns-allinone-3.x.tar.bz2
+   - sudo chmod 644 ns-allinone-3.x.tar.bz2
+
+4. if this is a final release (not RC)
+   - delete RC releases from /var/www/html/releases
+
+preparing the documentation
+----------------------------
+
+1. If final release, build release documentation
+   - sudo bash; su nsnam; cd /home/nsnam/bin 
+   ./update-doxygen-release ns-3.x
+   ./update-manual-release ns-3.x
+   ./update-tutorial-release ns-3.x
+
+2. Check if these new files are available on the website
+
+preparing the Wordpress-based main website
+------------------------------------------
+
+1. create a new ns-3.x page which should be visible from
+http://www.nsnam.org/ns-3.x
+- New Features
+- Download
+- Bugs Fixed
+- Documentation
+
+2. Repoint http://www.nsnam.org/releases/latest to the new page
+
+3. Update the Older Releases page to create an entry for the previous
+release (there are two such pages, one under Releases and one under
+Documentation)
+
+4. The main page http://www.nsnam.org should point to
+ns-3.x in the "Download" and "Documentation" boxes
+
+5. Create blog entry to announce release 
+
+ns-3 wiki edits
+---------------
+
+1. Create ns-3.(X+1) wiki page if not done already.
+
+2. edit front page and Roadmap
+
+Bugzilla
+--------
+
+1. Add a product version "ns-3.x" to the available versions.
+
+Announcing
+----------
+
+1. Final checks
+   - check manual, tutorial, model, and doxygen documentation links
+   - download tarball from web, build and run tests for as many
+     targets as you can
+   - download release from mercurial, build and run tests for as
+     many targets as you can
+   - test and verify until you're confident the release is solid.
+
+2. announce to ns-developers and ns-3-users, with summary of release notes
+
@@ -1,582 +0,0 @@
-/**
- * \defgroup TraceSourceList List of trace sources
- */
-
-/**
- * \defgroup tracing Tracing
- *
- * The flexibility of the ns-3 tracing system comes at the cost of quite
- * a bit of complexity so, before trying to use the low-level aspects
- * of the tracing API, it is important to focus on some basic definitions:
- *
- * - A trace source is an object instance which can report trace events
- *   to a set of listening trace sinks.
- *
- * - A trace sink is a user-provided callback (a function) which can
- *   be connected to a set of trace sources to receive the events generated
- *   by each trace source.
- *
- * - A trace resolver is an object which allows users to establish 
- *   connections between a set of trace sources and a set of trace sinks.
- *
- * \section TraceSource Generating Trace Events
- *
- * So, what does it look like in practice ? First, let's look at trace
- * sources. We have two types of trace sources: numeric, and, normal 
- * trace sources. Numeric trace sources behave as normal c++ integers 
- * or c++ floating point numbers except that they report as trace events 
- * each change of their value. For example:
- * \code
- * class MyModel 
- * {
- * public:
- *   void DoSomething (void) 
- *   {
- *     // use the "int" trace source just 
- *     // like any other "int" variable.
- *     m_cwnd *= 2;
- *     m_cwnd += 4;
- *     if (m_cwnd > 100)
- *       {
- *         // do something.
- *       }
- *   }
- * private:
- *   // declare an instance of a "int" trace source
- *   SVTraceSource<int> m_cwnd;
- * };
- * \endcode
- * Normal trace sources, on the other hand, allow you to trace the
- * call of arbitrary functions and methods, as shown below. They are
- * typically used to track "rx", "tx", or "drop" events but could
- * also be used to track route change events, or position change
- * events:
- * \code
- * class MyModel 
- * {
- * public:
- *   void DoSomething (Packet packet) 
- *   {
- *     // report this event on packet
- *     m_doSomething (packet);
- *     // do something
- *   }
- * private:
- *   // report every "something" function call.
- *   CallbackTraceSource<Packet> m_doSomething;
- * };
- * \endcode
- * Every type of trace source derives from the ns3::TraceSource base class.
- * As of today, the set of concrete subclasses is relatively short:
- * ns3::CallbackTraceSource, ns3::SvTraceSource, ns3::UvTraceSource, and,
- * ns3::FvTraceSource.
- *
- * \section TraceSink Receiving Trace Events
- *
- * To receive these trace events, a user should specify a set of trace sinks.
- * For example, to receive the "int" and the "something" events shown in the
- * examples above, a user would declare the following functions:
- * \code
- * // oldValue and newValue contain the previous and new values of 
- * // the connected SVTraceSource<int> trace source.
- * void 
- * CwndTraceSink (const TraceContext &context, int64_t oldValue, int64_t newValue)
- * {
- *   // for example, print the new value:
- *   std::cout << "cwnd=" << newValue << std::endl;
- * }
- * void 
- * DoSomethingTraceSink (const TraceContext &context, Packet packet)
- * {
- *   // for example, print the arguments
- *   std::cout << "packet " << packet << std::endl;
- * }
- * \endcode
- * Each of these sink function takes, as a first argument, a reference to a 
- * const TraceContext object. This context object contains information which
- * describes the instance of the connected trace source: that information is
- * setup during the connection process and does not change afterwards
- * The type and the number of the other arguments to each trace sink depends
- * on the type of the connected trace source: it conveys per-event information
- * from the trace source to the trace sink. For example, UVTraceSource and 
- * SVTraceSource trace sources require two extra arguments. The former requires
- * two unsigned 64 bit integers while the latter requires two signed 64 bit 
- * integers. More generally, users can consult the \ref TraceSourceList
- * to figure out the arguments which a trace sink is required to receive
- * for each trace source: a signature of the user trace sink must match 
- * _exactly_ the signature documented in the \ref TraceSourceList.
- *
- *
- * \section TraceSourceSimpleExport A simple way to connect Trace Sources with Trace Sinks
- *
- * The crux of the complexity of the ns-3 tracing system comes from its 
- * flexible system used to connect trace sources to trace sinks but what is really
- * nice about it is that it is not necessary to use it to setup simple traces.
- * 
- * The simplest way to export a set of trace sources to a user, for example, 
- * during the early prototyping phases of a system, is to add a set of public methods
- * to give to your users access to the trace source object instances you use to generate
- * trace events:
- * \code
- * class MyModel 
- * {
- * public:
- *   void DoSomething (Packet packet) 
- *   {
- *     // report this event on packet
- *     m_doSomething (packet);
- *     // do something
- *   }
- *   CallbackTraceSource<Packet> *PeekSomethingTraceSource (void) const 
- *   {
- *     return &m_doSomething
- *   }
- * private:
- *   // report every "something" function call.
- *   CallbackTraceSource<Packet> m_doSomething;
- * };
- * \endcode
- * If your users hold a pointer to an instance of MyModel, and if they want to connect
- * a MySomethingSink, they can simply do the following which invokes the 
- * TraceSource::AddCallback method and creates a Callback object from the user's
- * sink with the MakeCallback function.
- * \code
- * void 
- * MySomethingSink (const TraceContext &context, Packet packet)
- * {
- *   // do whatever you want.
- * }
- * MyModel *model = ...;
- * CallbackTraceSource<Packet> *source = model->PeekSomethingTraceSource ();
- * source->AddCallback (MakeCallback (&MySomethingSink));
- * \endcode
- *
- * The full power of the tracing system comes however from its ns3::NodeList::Connect
- * method which is described in the following sections.
- *
- * \section TraceConnection Connecting Trace Sources to Trace Sinks
- * 
- * If a trace source is integrated in the ns-3 trace connection facility, a user 
- * should call the ns3::NodeList::Connect method to establish a connection between
- * a trace sink and a set of matching trace sources. The second argument to that
- * method is a callback to the user's trace sink.
- * That callback is easy to construct: call ns3::MakeCallback and you are done. The
- * first argument is a string whose format is similar to a unix path and which is 
- * used to uniquely identify the set of trace sources you want to connect to.
- * The set of acceptable path strings is also documented in the \ref TraceSourceList.
- *
- * So, what does this look like from the perspective of a user ? If we wanted to 
- * connect to a trace source defined somewhere deep into the a set of NetDevice objects
- * located in some nodes of the system, we could write the following:
- * \code
- * void 
- * DoSomethingTraceSink (const TraceContext &context, Packet packet)
- * {
- *   // for example, print the arguments
- *   std::cout << "packet: " << packet << std::endl;
- * }
- * // connect the above sink to a matching trace source
- * NodeList::Connect ("/nodes/* /devices/* /rx", MakeCallback &DoSomethingTraceSink);
- * \endcode
- *
- * The connection path string "/nodes/* /devices/* /rx" matches the "rx" trace source
- * located in every netdevice located in every node. The syntax of that path string
- * is loosely based on regular expressions so, a user could conceivably connect
- * to the trace sources present in only one node identified by node index:
- * "/nodex/3/devices/* /rx".
- *
- * The matching algorithm used here is very useful since it allows you to connect
- * at once a large set of trace sources to a single sink but it introduces another 
- * problem: it becomes impossible when you receive an event in your trace sink to
- * know from _which_ trace source the event is coming from. In our example, the
- * trace source might be coming from the NetDevice number 2 of Node 10 or Netdevice
- * number 0 of Node 5. In both cases, you might need to know which of these NetDevice
- * is generating this event, if only to generate some ascii trace dump. Another 
- * similar use-case is that you might have connected the same trace sink to
- * multiple types of events which have the same signature: it is quite common
- * to receive all tx, rx, and drop events in the same trace sink and that would be
- * quite trivial to achieve with a string such as: "/nodes/* /devices/* /*"
- *
- * The source of a trace event can be retrieved from a trace sink using 
- * different means: the simplest
- * way to get this information is to use the builtin printing facility of
- * the TraceContext object:
- * \code
- * void 
- * DoSomethingTraceSink (const TraceContext &context, Packet packet)
- * {
- *   // for example, print the arguments
- *   std::cout << "context=\"" << context << "\" packet: " << packet << std::endl;
- * }
- * \endcode
- * The above code is going to generate output which looks like the following:
- * \code
- * context="nodeid=2 device=0 dev-rx" packet: IPV4(tos 0x0 ttl 64 id 0 offset ...
- * context="nodeid=1 device=0 dev-rx" packet: IPV4(tos 0x0 ttl 64 id 0 offset ...
- * ...
- * \endcode
- *
- * Another more advanced way to get information out of a TraceContext is to call its
- * ns3::TraceContext::GetElement method. This method takes as its first and only
- * argument an instance of the object we want to read and the list of available
- * object instances we can read from a TraceContext is documented, once again,
- * in the \ref TraceSourceList. For example, we could write the following to
- * generate adhoc trace output:
- * \code
- * void DeviceRxSink (const TraceContext &context, const Packet &packet)
- * {
- *   NodeListIndex nodeIndex;
- *   NodeNetDeviceIndex deviceIndex;
- *   context.GetElement (nodeIndex);
- *   context.GetElement (deviceIndex);
- *   std::cout << "node-index=" << nodeIndex.Get ();
- *   std::cout << ", device-index=" << deviceIndex.Get ();
- *   std::cout << ", packet: " << packet;
- *   std::cout << std::endl;
- * }
- * \endcode
- *
- * \section ExportingTraceSources Exporting new Trace Sources
- *
- * Using existing trace sources to connect them to a set of adhoc trace sinks
- * is not really complicated but, setting up new trace sources which can hook
- * in this automatic connection system is a bit more complicated.
- *
- * So far, we know that a model author can generate trace events really easily:
- * \code
- * class MyModel 
- * {
- * public:
- *   void DoSomething (Packet packet) 
- *   {
- *     // report this event on packet with value
- *     m_doSomething (packet);
- *     // do something
- *   }
- * private:
- *   // report every "something" function call.
- *   CallbackTraceSource<Packet> m_doSomething;
- * };
- * \endcode
- *
- * To make these new trace sources available to the rest of the connection system,
- * the first step is to make sure that your model object derives from the ns3::Object
- * base class either directly (as shown below) or indirectly through another base class:
- * \code
- * class MyModel : public Object {...};
- * // or:
- * class SomeOtherObject : public Object {...};
- * class MyModel : public SomeOtherObject {...};
- * \endcode
- *
- * This is pretty trivial and lays the ground for the second step: overriding the
- * ns3::Object::GetTraceResolver method:
- * \code
- * class MyModel : public MyParent
- * {
- * public:
- *   // declare overriden method
- *   virtual Ptr<TraceResolver> GetTraceResolver (void) const;
- * private:
- *   // the new trace source to export.
- *   CallbackTraceSource<Packet> m_rxSource;
- * };
- * \endcode
- *
- * To implement this method, you could attempt to implement a new subclass of
- * the ns3::TraceResolver base class and return an instance from this method but
- * this would be very hard. Instead, you should use the helper class
- * ns3::CompositeTraceResolver to register your trace sources and chain up to
- * your parent:
- * \code
- * Ptr<TraceResolver>
- * MyModel::GetTraceResolver (void) const
- * {
- *   // create an empty trace resolver
- *   Ptr<CompositeTraceResolver> resolver = Create<CompositeTraceResolver> ();
- *   // register m_rxSource
- *   resolver->AddSource ("rx", // the name of the trace source in the path string
- *                        TraceDoc ("some help text to explain the purpose of this trace source",
- *                                  "Packet", // the type of the first argument to the trace source
- *                                  "the purpose of the first argument",
- *                                  "type-of-second-argument", "purpose-of-second-argument"),
- *                        m_rxSource // the trace source itself is registered
- *                       );
- *   // make sure we include the trace sources implemented in the parent.
- *   resolver->SetParentResolver (MyParent::GetTraceResolver ());
- *   return resolver;
- * }
- * \endcode
- *
- * Once you have written that code, you must make sure that this new method GetTraceResolver
- * is going to be called at some point by the tracing system. If your model is located somewhere
- * deep in MAC or PHY layer, that is, it is part of a NetDevice implementation, all you
- * have to do is to make sure that your model is registered as a "composite" of your NetDevice
- * subclass:
- * \code
- * class MyNetDevice : public NetDevice
- * {
- * public:
- *   Ptr<TraceResolver> GetTraceResolver (void) const;
- * private:
- *   Ptr<MyModel> m_model;
- * };
- * 
- * Ptr<TraceResolver>
- * MyNetDevice::GetTraceResolver (void) const
- * {
- *   Ptr<CompositeTraceResolver> resolver = ...;
- *   // register other trace source
- *   ...
- *   // register now your model as a "composite"
- *   resolver->AddComposite ("my-model", m_model);
- *   // chain up to parent.
- *   resolver->SetParentResolver (NetDevice::GetTraceResolver ());
- *   return resolver;
- * }
- * \endcode
- * 
- * The code above will make your "rx" trace source appear under the
- * /nodes/xx/devices/xx/my-model/rx namespace path.
- *
- * If you have implemented a new layer 3 or 4 protocol object, the process to
- * export your trace sources is quite similar. You need to subclass from
- * ns3::Object, override the ns3::Object::GetTraceResolver method, make
- * sure you chain up to your parent's GetTraceResolver method, and, finally,
- * make sure that someone calls your new GetTraceResolver method. How to accomplish
- * the latter should be documented in the node's API documentation which describes
- * how to implement a new layer 3 or 4 protocol object.
- *
- * \section AdvancedTraceContext Creating new Trace Context Elements
- *
- * The last important feature which model developers need to understand
- * is how to provide extra context information to trace sinks. For example,
- * if your model exports both rx and tx trace sources which share the same 
- * signature, it is quite natural for a user to connect to a single trace sink
- * to both of them with a trace path string such as "/nodes/* /devices/* /(rx|tx)".
- * In this case, it becomes necessary to be able, from the trace sink function,
- * to tell which event triggered the call to the trace sink: a rx or a tx event.
- *
- * That example is detailed below with a TX, a RX, and a DROP source:
- * \code
- * class MyModel
- * {
- * private:
- *   CallbackTraceSource<Packet> m_rxSource;
- *   CallbackTraceSource<Packet> m_txSource;
- *   CallbackTraceSource<Packet> m_dropSource;
- * };
- * \endcode
- * When a single sink is connected to all 3 sources here, one might want
- * to write code like the following:
- * \code
- * void DeviceRxSink (const TraceContext &context, const Packet &packet)
- * {
- *   switch (type) {
- *     case RX:
- *       std::cout << "rx" << std::endl;
- *       break;
- *     case TX:
- *       std::cout << "tx" << std::endl;
- *       break;
- *     case DROP:
- *       std::cout << "drop" << std::endl;
- *       break;
- *   }
- * \endcode
- *
- * \subsection AdvancedTraceContextSimpleSolution The simple solution
- *
- * The simplest way to do achieve the result shown above is to include
- * in the trace source an extra explicit argument which describes the source event:
- *   - define a small enum with 3 values
- *   - change the signature of m_rxSource, m_txSource, and m_dropSource to include
- *     the enum
- *   - pass the enum value in each event
- *
- * The resulting code is shown below:
- * \code
- * class MyModel
- * {
- * public:
- *   // define the trace type enum.
- *   enum TraceType {
- *     RX,
- *     TX,
- *     DROP
- *   };
- * private:
- *   // generate events
- *   void NotifyRxPacket (Packet p) {
- *     m_rxSource (p, MyModel::RX);
- *   }
- *   void NotifyTxPacket (Packet p) {
- *     m_rxSource (p, MyModel::TX);
- *   }
- *   void NotifyDropPacket (Packet p) {
- *     m_rxSource (p, MyModel::DROP);
- *   }
- *   CallbackTraceSource<Packet,enum TraceType> m_rxSource;
- *   CallbackTraceSource<Packet,enum TraceType> m_txSource;
- *   CallbackTraceSource<Packet,enum TraceType> m_dropSource;
- * };
- * \endcode
- * These 3 new sources can be connected easily to a new trace sink:
- * \code
- * void ASimpleTraceSink (const TraceContext &context, const Packet &packet, enum MyModel::TraceType type)
- * {
- *   // here, read the "type" argument
- * }
- * \endcode
- *
- * This solution works but it makes it impossible to connect a single trace sink to a set
- * of trace sources which represent "rx" events in different NetDevice objects since
- * each of them will define a different enum type with different values: since the
- * trace sink signature must match exactly the trace source signature, it is impossible
- * to connect at the same time to all "rx" events of different NetDevice.
- *
- * \subsection AdvancedTraceContextFancySolution The more complex and generic solution
- *
- * There is, hopefully, a way to get the best of both worlds, that is, to allow a
- * user to connect to a lot of trace source events of the same kind but coming from different
- * implementations and to allow the user to differentiate between these different
- * implementations.
- *
- * Rather than define an adhoc enum type with a list of trace sources, you can also
- * define a new ns3::TraceContextElement for your source sources. For example, if you
- * define a new MyModelTraceType class which contains the type of trace, your users can
- * then write trace sink code which looks like this:
- * \code
- * void AFancyTraceSink (const TraceContext &context, const Packet &packet)
- * {
- *   MyModelTraceType type;
- *   if (context.GetElement (type))
- *     {
- *       switch (type.Get ())
- *         {
- *         case MyModelTraceType::RX:
- *           std::cout << "rx" << std::endl;
- *           break;
- *         case MyModelTraceType::TX:
- *           std::cout << "tx" << std::endl;
- *           break;
- *         case MyModelTraceType::DROP:
- *           std::cout << "drop" << std::endl;
- *           break;
- *         }
- *     }
- * }
- * \endcode
- *
- * Of course, since the type of trace is stored in the TraceContext, your users can
- * also take the shortcut which uses the printing functionality of the TraceContext:
- * \code
- * void ALessFancyTraceSink (const TraceContext &context, const Packet &packet)
- * {
- *   std::cout << "context=\"" << context << "\" packet: " << packet << std::endl;
- * }
- * \endcode
- * which will generate something like the following when the trace source comes
- * from MyModel:
- * \code
- * context="my-model-rx" packet: ...
- * \endcode
- *
- * The first step to achieve this is to define and implement a new
- * subclass of the ns3::TraceContextElement base class. The exact list of
- * public methods which must be implemented is described in the API
- * documentation of the ns3::TraceContextElement class. 
- * \code
- * class MyModelTraceType : public TraceContextElement
- * {
- * public:
- *   enum Type {
- *     RX,
- *     TX,
- *     DROP
- *   };
- *   // called from MyModel::GetTraceResolver
- *   MyModelTraceType (enum Type type);
- *   // needed for by the tracing subsystem.
- *   MyModelTraceType ();
- *   // called from trace sink
- *   enum Type Get (void) const;
- *   // needed by the tracing subsystem
- *   static uint16_t GetUid (void);
- *   // needed by the tracing subsystem to
- *   // print the content of a TraceContext
- *   void Print (std::ostream &os) const;
- *   // needed by the tracing subsystem to
- *   // generate the doxygen documentation.
- *   std::string GetTypeName (void) const;
- * private:
- *   enum Type m_type;
- * };
- * \endcode
- * The implementation does not require much thinking:
- * \code
- * MyModelTraceType::MyModelTraceType ()
- *  : m_type (RX)
- * {// an arbitrary default value.
- * }
- * MyModelTraceType::MyModelTraceType (enum Type type)
- *  : m_type (type)
- * {}
- * enum MyModelTraceType::Type 
- * MyModelTraceType::Get (void) const
- * {
- *   return m_type;
- * }
- * uint16_t 
- * MyModelTraceType::GetUid (void)
- * {
- *   // use protected TraceContextElement::AllocateUid method
- *   // the input string is used to uniquely identify this new subclass
- *   static uint16_t uid = AllocateUid<MyModelTraceType> ("ns3::MyModelTraceType");
- *   return uid;
- * }
- * void 
- * MyModelTraceType::Print (std::ostream &os) const
- * {
- *   // this method is invoked by the print function of a TraceContext
- *   // if it contains an instance of this TraceContextElement.
- *   switch (m_type) {
- *     case RX: os << "rx"; break;
- *     // ...
- *   }
- * }
- * std::string 
- * MyModelTraceType::GetTypeName (void) const
- * {
- *   // This method should return a fully-qualified c++ typename
- *   // This method is used only for documentation purposes to
- *   // generate the content of the Trace Source List.
- *   return "ns3::MyModelTraceType";
- * }
- * \endcode
- *
- * Once this subclass is implemented, the work is almost completed: you
- * just need to pass an instance of that class as the last argument of 
- * the ns3::CompositeTraceResolver::AddSource method as shown below:
- * \code
- * Ptr<TraceResolver>
- * MyModel::GetTraceResolver (void) const
- * {
- *   // create an empty trace resolver
- *   Ptr<CompositeTraceResolver> resolver = Create<CompositeTraceResolver> ();
- *   // register m_rxSource
- *   resolver->AddSource ("rx", // the name of the trace source in the path string
- *                        TraceDoc ("some help text to explain the purpose of this trace source",
- *                                  "Packet", // the type of the first argument to the trace source
- *                                  "the purpose of the first argument",
- *                                  "type-of-second-argument", "purpose-of-second-argument"),
- *                        m_rxSource, // the trace source itself is registered
- *                        // the TraceContextElement associated to this trace source.
- *                        MyModelTraceType (MyModelTraceType::RX) 
- *                       );
- *   // make sure we include the trace sources implemented in the parent.
- *   resolver->SetParentResolver (MyParent::GetTraceResolver ());
- *   return resolver;
- * }
- * \endcode
- */
@@ -0,0 +1,150 @@
+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+PAPER         =
+BUILDDIR      = build
+
+# Internal variables.
+PAPEROPT_a4     = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
+
+# Additional variables for figures, not sphinx default:
+DIA = dia
+EPSTOPDF = epstopdf
+FIGURES = source/figures
+IMAGES_EPS = \
+
+IMAGES_PNG = ${IMAGES_EPS:.eps=.png}
+IMAGES_PDF = ${IMAGES_EPS:.eps=.pdf}
+
+IMAGES = $(IMAGES_EPS) $(IMAGES_PNG) $(IMAGES_PDF)
+
+.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest
+
+%.eps : %.dia; $(DIA) -t eps $< -e $@
+%.png : %.dia; $(DIA) -t png $< -e $@
+%.pdf : %.eps; $(EPSTOPDF) $< -o=$@
+
+help:
+	@echo "Please use \`make <target>' where <target> is one of"
+	@echo "  html       to make standalone HTML files"
+	@echo "  dirhtml    to make HTML files named index.html in directories"
+	@echo "  singlehtml to make a single large HTML file"
+	@echo "  pickle     to make pickle files"
+	@echo "  json       to make JSON files"
+	@echo "  htmlhelp   to make HTML files and a HTML help project"
+	@echo "  qthelp     to make HTML files and a qthelp project"
+	@echo "  devhelp    to make HTML files and a Devhelp project"
+	@echo "  epub       to make an epub"
+	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"
+	@echo "  text       to make text files"
+	@echo "  man        to make manual pages"
+	@echo "  changes    to make an overview of all changed/added/deprecated items"
+	@echo "  linkcheck  to check all external links for integrity"
+	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
+
+clean:
+	-rm -rf $(BUILDDIR)/*
+
+frag: pickle
+	@if test ! -d $(BUILDDIR)/frag; then mkdir $(BUILDDIR)/frag; fi
+	pushd $(BUILDDIR)/frag && ../../pickle-to-xml.py ../pickle/index.fpickle  > navigation.xml && popd
+	cp -r $(BUILDDIR)/pickle/_images $(BUILDDIR)/frag
+
+html: $(IMAGES)
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+dirhtml: $(IMAGES)
+	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+
+singlehtml: $(IMAGES)
+	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
+	@echo
+	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
+
+pickle: $(IMAGES)
+	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
+	@echo
+	@echo "Build finished; now you can process the pickle files."
+
+json: $(IMAGES)
+	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
+	@echo
+	@echo "Build finished; now you can process the JSON files."
+
+htmlhelp: $(IMAGES)
+	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
+	@echo
+	@echo "Build finished; now you can run HTML Help Workshop with the" \
+	      ".hhp project file in $(BUILDDIR)/htmlhelp."
+
+qthelp: $(IMAGES)
+	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
+	@echo
+	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
+	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
+	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/ns-3.qhcp"
+	@echo "To view the help file:"
+	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/ns-3.qhc"
+
+devhelp: $(IMAGES)
+	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
+	@echo
+	@echo "Build finished."
+	@echo "To view the help file:"
+	@echo "# mkdir -p $$HOME/.local/share/devhelp/ns-3"
+	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/ns-3"
+	@echo "# devhelp"
+
+epub: $(IMAGES)
+	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
+	@echo
+	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
+
+latex: $(IMAGES)
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo
+	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
+	@echo "Run \`make' in that directory to run these through (pdf)latex" \
+	      "(use \`make latexpdf' here to do that automatically)."
+
+latexpdf: $(IMAGES)
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo "Running LaTeX files through pdflatex..."
+	make -C $(BUILDDIR)/latex all-pdf
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+text: $(IMAGES)
+	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
+	@echo
+	@echo "Build finished. The text files are in $(BUILDDIR)/text."
+
+man: $(IMAGES)
+	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
+	@echo
+	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
+
+changes: $(IMAGES)
+	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
+	@echo
+	@echo "The overview file is in $(BUILDDIR)/changes."
+
+linkcheck: $(IMAGEs)
+	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+	@echo
+	@echo "Link check complete; look for any errors in the above output " \
+	      "or in $(BUILDDIR)/linkcheck/output.txt."
+
+doctest: $(IMAGES)
+	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
+	@echo "Testing of doctests in the sources finished, look at the " \
+	      "results in $(BUILDDIR)/doctest/output.txt."
@@ -0,0 +1,18 @@
+Please write image files in a vector graphics format, when possible, and
+generate the .png and .pdf versions on the fly (see ../Makefile).  
+
+The currently supported tool is dia.  xfig could be added similarly
+if someone wants to add it.  The main requirement for adding another format
+is that the tool to edit it is freely available and that a cron script can 
+autogenerate the pdf and png from the figure source.  Tgif (.obj) files
+were once used but the file conversions require a valid X display to 
+be running, and are therefore to be avoided since our code server 
+does not run such a server.  Tgif pdf conversions were also cumbersome.
+
+Store the .dia versions in mercurial, but not the .png or .pdfs.  
+If the figure is not available in a vector graphics format, store both
+a .png and a .pdf version in this directory.
+
+If you add a source (.dia) file here, remember to add it to
+the list of figure sources in the Makefile in the directory above
+
@@ -0,0 +1,42 @@
+#!/usr/bin/python
+
+
+# output xml format:
+# <pages>
+# <page url="xx"><prev url="yyy">zzz</prev><next url="hhh">lll</next><fragment>file.frag</fragment></page>
+# ...
+# </pages>
+
+import pickle
+import os
+import codecs
+
+def dump_pickles(out, dirname, filename, path):
+    f = open(os.path.join(dirname, filename), 'r')
+    data = pickle.load(f)
+    fragment_file = codecs.open(data['current_page_name'] + '.frag', mode='w', encoding='utf-8')
+    fragment_file.write(data['body'])
+    fragment_file.close()
+    out.write('  <page url="%s">\n' % path)
+    out.write('    <fragment>%s.frag</fragment>\n' % data['current_page_name'])
+    if data['prev'] is not None:
+        out.write('    <prev url="%s">%s</prev>\n' % 
+                  (os.path.normpath(os.path.join(path, data['prev']['link'])), 
+                   data['prev']['title']))
+    if data['next'] is not None:
+        out.write('    <next url="%s">%s</next>\n' % 
+                  (os.path.normpath(os.path.join(path, data['next']['link'])), 
+                   data['next']['title']))
+    out.write('  </page>\n')
+    f.close()
+    if data['next'] is not None:
+        next_path = os.path.normpath(os.path.join(path, data['next']['link']))
+        next_filename = os.path.basename(next_path) + '.fpickle'
+        dump_pickles(out, dirname, next_filename, next_path)
+    return
+
+import sys
+
+sys.stdout.write('<pages>\n')
+dump_pickles(sys.stdout, os.path.dirname(sys.argv[1]), os.path.basename(sys.argv[1]), '/')
+sys.stdout.write('</pages>')
@@ -0,0 +1,842 @@
+.. include:: replace.txt
+
+
+Conceptual Overview
+-------------------
+
+The first thing we need to do before actually starting to look at or write
+|ns3| code is to explain a few core concepts and abstractions in the
+system.  Much of this may appear transparently obvious to some, but we
+recommend taking the time to read through this section just to ensure you
+are starting on a firm foundation.
+
+Key Abstractions
+****************
+
+In this section, we'll review some terms that are commonly used in
+networking, but have a specific meaning in |ns3|.
+
+Node
++++
+In Internet jargon, a computing device that connects to a network is called
+a *host* or sometimes an *end system*.  Because |ns3| is a 
+*network* simulator, not specifically an *Internet* simulator, we 
+intentionally do not use the term host since it is closely associated with
+the Internet and its protocols.  Instead, we use a more generic term also
+used by other simulators that originates in Graph Theory --- the *node*.
+
+In |ns3| the basic computing device abstraction is called the 
+node.  This abstraction is represented in C++ by the class ``Node``.  The 
+``Node`` class provides methods for managing the representations of 
+computing devices in simulations.
+
+You should think of a ``Node`` as a computer to which you will add 
+functionality.  One adds things like applications, protocol stacks and
+peripheral cards with their associated drivers to enable the computer to do
+useful work.  We use the same basic model in |ns3|.
+
+Application
+++++++++++
+Typically, computer software is divided into two broad classes.  *System
+Software* organizes various computer resources such as memory, processor
+cycles, disk, network, etc., according to some computing model.  System
+software usually does not use those resources to complete tasks that directly
+benefit a user.  A user would typically run an *application* that acquires
+and uses the resources controlled by the system software to accomplish some
+goal.  
+
+Often, the line of separation between system and application software is made
+at the privilege level change that happens in operating system traps.
+In |ns3| there is no real concept of operating system and especially
+no concept of privilege levels or system calls.  We do, however, have the
+idea of an application.  Just as software applications run on computers to
+perform tasks in the "real world," |ns3| applications run on
+|ns3| ``Nodes`` to drive simulations in the simulated world.
+
+In |ns3| the basic abstraction for a user program that generates some
+activity to be simulated is the application.  This abstraction is represented 
+in C++ by the class ``Application``.  The ``Application`` class provides 
+methods for managing the representations of our version of user-level 
+applications in simulations.  Developers are expected to specialize the
+``Application`` class in the object-oriented programming sense to create new
+applications.  In this tutorial, we will use specializations of class 
+``Application`` called ``UdpEchoClientApplication`` and 
+``UdpEchoServerApplication``.  As you might expect, these applications 
+compose a client/server application set used to generate and echo simulated 
+network packets 
+
+Channel
+++++++
+
+In the real world, one can connect a computer to a network.  Often the media
+over which data flows in these networks are called *channels*.  When
+you connect your Ethernet cable to the plug in the wall, you are connecting 
+your computer to an Ethernet communication channel.  In the simulated world
+of |ns3|, one connects a ``Node`` to an object representing a
+communication channel.  Here the basic communication subnetwork abstraction 
+is called the channel and is represented in C++ by the class ``Channel``.  
+
+The ``Channel`` class provides methods for managing communication 
+subnetwork objects and connecting nodes to them.  ``Channels`` may also be
+specialized by developers in the object oriented programming sense.  A 
+``Channel`` specialization may model something as simple as a wire.  The 
+specialized  ``Channel`` can also model things as complicated as a large 
+Ethernet switch, or three-dimensional space full of obstructions in the case 
+of wireless networks.
+
+We will use specialized versions of the ``Channel`` called
+``CsmaChannel``, ``PointToPointChannel`` and ``WifiChannel`` in this
+tutorial.  The ``CsmaChannel``, for example, models a version of a 
+communication subnetwork that implements a *carrier sense multiple 
+access* communication medium.  This gives us Ethernet-like functionality.  
+
+Net Device
++++++++++
+It used to be the case that if you wanted to connect a computers to a network,
+you had to buy a specific kind of network cable and a hardware device called
+(in PC terminology) a *peripheral card* that needed to be installed in
+your computer.  If the peripheral card implemented some networking function,
+they were called Network Interface Cards, or *NICs*.  Today most 
+computers come with the network interface hardware built in and users don't 
+see these building blocks.
+
+A NIC will not work without a software driver to control the hardware.  In 
+Unix (or Linux), a piece of peripheral hardware is classified as a 
+*device*.  Devices are controlled using *device drivers*, and network
+devices (NICs) are controlled using *network device drivers*
+collectively known as *net devices*.  In Unix and Linux you refer
+to these net devices by names such as *eth0*.
+
+In |ns3| the *net device* abstraction covers both the software 
+driver and the simulated hardware.  A net device is "installed" in a 
+``Node`` in order to enable the ``Node`` to communicate with other 
+``Nodes`` in the simulation via ``Channels``.  Just as in a real
+computer, a ``Node`` may be connected to more than one ``Channel`` via
+multiple ``NetDevices``.
+
+The net device abstraction is represented in C++ by the class ``NetDevice``.
+The ``NetDevice`` class provides methods for managing connections to 
+``Node`` and ``Channel`` objects; and may be specialized by developers
+in the object-oriented programming sense.  We will use the several specialized
+versions of the ``NetDevice`` called ``CsmaNetDevice``,
+``PointToPointNetDevice``, and ``WifiNetDevice`` in this tutorial.
+Just as an Ethernet NIC is designed to work with an Ethernet network, the
+``CsmaNetDevice`` is designed to work with a ``CsmaChannel``; the
+``PointToPointNetDevice`` is designed to work with a 
+``PointToPointChannel`` and a ``WifiNetNevice`` is designed to work with
+a ``WifiChannel``.
+
+Topology Helpers
++++++++++++++++
+In a real network, you will find host computers with added (or built-in)
+NICs.  In |ns3| we would say that you will find ``Nodes`` with 
+attached ``NetDevices``.  In a large simulated network you will need to 
+arrange many connections between ``Nodes``, ``NetDevices`` and 
+``Channels``.
+
+Since connecting ``NetDevices`` to ``Nodes``, ``NetDevices``
+to ``Channels``, assigning IP addresses,  etc., are such common tasks
+in |ns3|, we provide what we call *topology helpers* to make 
+this as easy as possible.  For example, it may take many distinct 
+|ns3| core operations to create a NetDevice, add a MAC address, 
+install that net device on a ``Node``, configure the node's protocol stack,
+and then connect the ``NetDevice`` to a ``Channel``.  Even more
+operations would be required to connect multiple devices onto multipoint 
+channels and then to connect individual networks together into internetworks.
+We provide topology helper objects that combine those many distinct operations
+into an easy to use model for your convenience.
+
+A First ns-3 Script
+*******************
+If you downloaded the system as was suggested above, you will have a release
+of |ns3| in a directory called ``repos`` under your home 
+directory.  Change into that release directory, and you should find a 
+directory structure something like the following:
+
+::
+
+  AUTHORS       examples       scratch        utils      waf.bat*
+  bindings      LICENSE        src            utils.py   waf-tools
+  build         ns3            test.py*       utils.pyc  wscript
+  CHANGES.html  README         testpy-output  VERSION    wutils.py
+  doc           RELEASE_NOTES  testpy.supp    waf*       wutils.pyc
+
+
+Change into the ``examples/tutorial`` directory.  You should see a file named 
+``first.cc`` located there.  This is a script that will create a simple
+point-to-point link between two nodes and echo a single packet between the
+nodes.  Let's take a look at that script line by line, so go ahead and open
+``first.cc`` in your favorite editor.
+
+Boilerplate
+++++++++++
+The first line in the file is an emacs mode line.  This tells emacs about the
+formatting conventions (coding style) we use in our source code.  
+
+::
+
+  /* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
+
+This is always a somewhat controversial subject, so we might as well get it
+out of the way immediately.  The |ns3| project, like most large 
+projects, has adopted a coding style to which all contributed code must 
+adhere.  If you want to contribute your code to the project, you will 
+eventually have to conform to the |ns3| coding standard as described 
+in the file ``doc/codingstd.txt`` or shown on the project web page
+`here
+<http://www.nsnam.org/codingstyle.html>`_.
+
+We recommend that you, well, just get used to the look and feel of |ns3|
+code and adopt this standard whenever you are working with our code.  All of 
+the development team and contributors have done so with various amounts of 
+grumbling.  The emacs mode line above makes it easier to get the formatting 
+correct if you use the emacs editor.
+
+The |ns3| simulator is licensed using the GNU General Public 
+License.  You will see the appropriate GNU legalese at the head of every file 
+in the |ns3| distribution.  Often you will see a copyright notice for
+one of the institutions involved in the |ns3| project above the GPL
+text and an author listed below.
+
+::
+
+  /*
+   * This program is free software; you can redistribute it and/or modify
+   * it under the terms of the GNU General Public License version 2 as
+   * published by the Free Software Foundation;
+   *
+   * This program is distributed in the hope that it will be useful,
+   * but WITHOUT ANY WARRANTY; without even the implied warranty of
+   * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+   * GNU General Public License for more details.
+   *
+   * You should have received a copy of the GNU General Public License
+   * along with this program; if not, write to the Free Software
+   * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307 USA
+   */
+
+Module Includes
+++++++++++++++
+The code proper starts with a number of include statements.  
+
+::
+
+  #include "ns3/core-module.h"
+  #include "ns3/network-module.h"
+  #include "ns3/internet-module.h"
+  #include "ns3/point-to-point-module.h"
+  #include "ns3/applications-module.h"
+
+To help our high-level script users deal with the large number of include 
+files present in the system, we group includes according to relatively large 
+modules.  We provide a single include file that will recursively load all of 
+the include files used in each module.  Rather than having to look up exactly
+what header you need, and possibly have to get a number of dependencies right,
+we give you the ability to load a group of files at a large granularity.  This
+is not the most efficient approach but it certainly makes writing scripts much
+easier.
+
+Each of the |ns3| include files is placed in a directory called 
+``ns3`` (under the build directory) during the build process to help avoid
+include file name collisions.  The ``ns3/core-module.h`` file corresponds 
+to the ns-3 module you will find in the directory ``src/core`` in your 
+downloaded release distribution.  If you list this directory you will find a
+large number of header files.  When you do a build, Waf will place public 
+header files in an ``ns3`` directory under the appropriate 
+``build/debug`` or ``build/optimized`` directory depending on your 
+configuration.  Waf will also automatically generate a module include file to
+load all of the public header files.
+
+Since you are, of course, following this tutorial religiously, you will 
+already have done a
+
+::
+
+  ./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
+
+::
+
+  ./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 
+above.  You can take a look at the contents of these files and find that they
+do include all of the public include files in their respective modules.
+
+Ns3 Namespace
+++++++++++++
+The next line in the ``first.cc`` script is a namespace declaration.
+
+::
+
+  using namespace ns3;
+
+The |ns3| project is implemented in a C++ namespace called 
+``ns3``.  This groups all |ns3|-related declarations in a scope
+outside the global namespace, which we hope will help with integration with 
+other code.  The C++ ``using`` statement introduces the |ns3|
+namespace into the current (global) declarative region.  This is a fancy way
+of saying that after this declaration, you will not have to type ``ns3::``
+scope resolution operator before all of the |ns3| code in order to use
+it.  If you are unfamiliar with namespaces, please consult almost any C++ 
+tutorial and compare the ``ns3`` namespace and usage here with instances of
+the ``std`` namespace and the ``using namespace std;`` statements you 
+will often find in discussions of ``cout`` and streams.
+
+Logging
+++++++
+The next line of the script is the following,
+
+::
+
+  NS_LOG_COMPONENT_DEFINE ("FirstScriptExample");
+
+We will use this statement as a convenient place to talk about our Doxygen
+documentation system.  If you look at the project web site, 
+`ns-3 project
+<http://www.nsnam.org>`_, you will find a link to "Documentation" in the navigation bar.  If you select this link, you will be
+taken to our documentation page. There 
+is a link to "Latest Release" that will take you to the documentation
+for the latest stable release of |ns3|.
+If you select the "API Documentation" link, you will be
+taken to the |ns3| API documentation page.
+
+Along the left side, you will find a graphical representation of the structure
+of the documentation.  A good place to start is the ``NS-3 Modules``
+"book" in the |ns3| navigation tree.  If you expand ``Modules`` 
+you will see a list of |ns3| module documentation.  The concept of 
+module here ties directly into the module include files discussed above.  The |ns3| logging subsystem is discussed in the ``C++ Constructs Used by All Modules`` 
+section, so go ahead and expand that documentation node.  Now, expand the 
+``Debugging`` book and then select the ``Logging`` page.
+
+You should now be looking at the Doxygen documentation for the Logging module.
+In the list of ``#define``s at the top of the page you will see the entry
+for ``NS_LOG_COMPONENT_DEFINE``.  Before jumping in, it would probably be 
+good to look for the "Detailed Description" of the logging module to get a 
+feel for the overall operation.  You can either scroll down or select the
+"More..." link under the collaboration diagram to do this.
+
+Once you have a general idea of what is going on, go ahead and take a look at
+the specific ``NS_LOG_COMPONENT_DEFINE`` documentation.  I won't duplicate
+the documentation here, but to summarize, this line declares a logging 
+component called ``FirstScriptExample`` that allows you to enable and 
+disable console message logging by reference to the name.
+
+Main Function
+++++++++++++
+The next lines of the script you will find are,
+
+::
+
+  int
+  main (int argc, char *argv[])
+  {
+
+This is just the declaration of the main function of your program (script).
+Just as in any C++ program, you need to define a main function that will be 
+the first function run.  There is nothing at all special here.  Your 
+|ns3| script is just a C++ program.
+
+The next two lines of the script are used to enable two logging components that
+are built into the Echo Client and Echo Server applications:
+
+::
+
+    LogComponentEnable("UdpEchoClientApplication", LOG_LEVEL_INFO);
+    LogComponentEnable("UdpEchoServerApplication", LOG_LEVEL_INFO);
+
+If you have read over the Logging component documentation you will have seen
+that there are a number of levels of logging verbosity/detail that you can 
+enable on each component.  These two lines of code enable debug logging at the
+INFO level for echo clients and servers.  This will result in the application
+printing out messages as packets are sent and received during the simulation.
+
+Now we will get directly to the business of creating a topology and running 
+a simulation.  We use the topology helper objects to make this job as
+easy as possible.
+
+Topology Helpers
++++++++++++++++
+NodeContainer
+~~~~~~~~~~~~~
+The next two lines of code in our script will actually create the 
+|ns3| ``Node`` objects that will represent the computers in the 
+simulation.  
+
+::
+
+    NodeContainer nodes;
+    nodes.Create (2);
+
+Let's find the documentation for the ``NodeContainer`` class before we
+continue.  Another way to get into the documentation for a given class is via 
+the ``Classes`` tab in the Doxygen pages.  If you still have the Doxygen 
+handy, just scroll up to the top of the page and select the ``Classes`` 
+tab.  You should see a new set of tabs appear, one of which is 
+``Class List``.  Under that tab you will see a list of all of the 
+|ns3| classes.  Scroll down, looking for ``ns3::NodeContainer``.
+When you find the class, go ahead and select it to go to the documentation for
+the class.
+
+You may recall that one of our key abstractions is the ``Node``.  This
+represents a computer to which we are going to add things like protocol stacks,
+applications and peripheral cards.  The ``NodeContainer`` topology helper
+provides a convenient way to create, manage and access any ``Node`` objects
+that we create in order to run a simulation.  The first line above just 
+declares a NodeContainer which we call ``nodes``.  The second line calls the
+``Create`` method on the ``nodes`` object and asks the container to 
+create two nodes.  As described in the Doxygen, the container calls down into
+the |ns3| system proper to create two ``Node`` objects and stores
+pointers to those objects internally.
+
+The nodes as they stand in the script do nothing.  The next step in 
+constructing a topology is to connect our nodes together into a network.
+The simplest form of network we support is a single point-to-point link 
+between two nodes.  We'll construct one of those links here.
+
+PointToPointHelper
+~~~~~~~~~~~~~~~~~~
+We are constructing a point to point link, and, in a pattern which will become
+quite familiar to you, we use a topology helper object to do the low-level
+work required to put the link together.  Recall that two of our key 
+abstractions are the ``NetDevice`` and the ``Channel``.  In the real
+world, these terms correspond roughly to peripheral cards and network cables.  
+Typically these two things are intimately tied together and one cannot expect
+to interchange, for example, Ethernet devices and wireless channels.  Our 
+Topology Helpers follow this intimate coupling and therefore you will use a
+single ``PointToPointHelper`` to configure and connect |ns3|
+``PointToPointNetDevice`` and ``PointToPointChannel`` objects in this 
+script.
+
+The next three lines in the script are,
+
+::
+
+    PointToPointHelper pointToPoint;
+    pointToPoint.SetDeviceAttribute ("DataRate", StringValue ("5Mbps"));
+    pointToPoint.SetChannelAttribute ("Delay", StringValue ("2ms"));
+
+The first line,
+
+::
+
+    PointToPointHelper pointToPoint;
+
+instantiates a ``PointToPointHelper`` object on the stack.  From a 
+high-level perspective the next line,
+
+::
+
+    pointToPoint.SetDeviceAttribute ("DataRate", StringValue ("5Mbps"));
+
+tells the ``PointToPointHelper`` object to use the value "5Mbps"
+(five megabits per second) as the "DataRate" when it creates a 
+``PointToPointNetDevice`` object.
+
+From a more detailed perspective, the string "DataRate" corresponds
+to what we call an ``Attribute`` of the ``PointToPointNetDevice``.
+If you look at the Doxygen for class ``ns3::PointToPointNetDevice`` and 
+find the documentation for the ``GetTypeId`` method, you will find a list
+of  ``Attributes`` defined for the device.  Among these is the "DataRate"
+``Attribute``.  Most user-visible |ns3| objects have similar lists of 
+``Attributes``.  We use this mechanism to easily configure simulations without
+recompiling as you will see in a following section.
+
+Similar to the "DataRate" on the ``PointToPointNetDevice`` you will find a
+"Delay" ``Attribute`` associated with the ``PointToPointChannel``.  The 
+final line,
+
+::
+
+    pointToPoint.SetChannelAttribute ("Delay", StringValue ("2ms"));
+
+tells the ``PointToPointHelper`` to use the value "2ms" (two milliseconds)
+as the value of the transmission delay of every point to point channel it 
+subsequently creates.
+
+NetDeviceContainer
+~~~~~~~~~~~~~~~~~~
+At this point in the script, we have a ``NodeContainer`` that contains
+two nodes.  We have a ``PointToPointHelper`` that is primed and ready to 
+make ``PointToPointNetDevices`` and wire ``PointToPointChannel`` objects
+between them.  Just as we used the ``NodeContainer`` topology helper object
+to create the ``Nodes`` for our simulation, we will ask the 
+``PointToPointHelper`` to do the work involved in creating, configuring and
+installing our devices for us.  We will need to have a list of all of the 
+NetDevice objects that are created, so we use a NetDeviceContainer to hold 
+them just as we used a NodeContainer to hold the nodes we created.  The 
+following two lines of code,
+
+::
+
+    NetDeviceContainer devices;
+    devices = pointToPoint.Install (nodes);
+
+will finish configuring the devices and channel.  The first line declares the 
+device container mentioned above and the second does the heavy lifting.  The 
+``Install`` method of the ``PointToPointHelper`` takes a 
+``NodeContainer`` as a parameter.  Internally, a ``NetDeviceContainer`` 
+is created.  For each node in the ``NodeContainer`` (there must be exactly 
+two for a point-to-point link) a ``PointToPointNetDevice`` is created and 
+saved in the device container.  A ``PointToPointChannel`` is created and 
+the two ``PointToPointNetDevices`` are attached.  When objects are created
+by the ``PointToPointHelper``, the ``Attributes`` previously set in the 
+helper are used to initialize the corresponding ``Attributes`` in the 
+created objects.
+
+After executing the ``pointToPoint.Install (nodes)`` call we will have
+two nodes, each with an installed point-to-point net device and a single
+point-to-point channel between them.  Both devices will be configured to 
+transmit data at five megabits per second over the channel which has a two 
+millisecond transmission delay.
+
+InternetStackHelper
+~~~~~~~~~~~~~~~~~~~
+We now have nodes and devices configured, but we don't have any protocol stacks
+installed on our nodes.  The next two lines of code will take care of that.
+
+::
+
+    InternetStackHelper stack;
+    stack.Install (nodes);
+
+The ``InternetStackHelper`` is a topology helper that is to internet stacks
+what the ``PointToPointHelper`` is to point-to-point net devices.  The
+``Install`` method takes a ``NodeContainer`` as a parameter.  When it is
+executed, it will install an Internet Stack (TCP, UDP, IP, etc.) on each of
+the nodes in the node container.
+
+Ipv4AddressHelper
+~~~~~~~~~~~~~~~~~
+Next we need to associate the devices on our nodes with IP addresses.  We 
+provide a topology helper to manage the allocation of IP addresses.  The only
+user-visible API is to set the base IP address and network mask to use when
+performing the actual address allocation (which is done at a lower level 
+inside the helper).
+
+The next two lines of code in our example script, ``first.cc``,
+
+::
+
+    Ipv4AddressHelper address;
+    address.SetBase ("10.1.1.0", "255.255.255.0");
+
+declare an address helper object and tell it that it should begin allocating IP
+addresses from the network 10.1.1.0 using the mask 255.255.255.0 to define 
+the allocatable bits.  By default the addresses allocated will start at one
+and increase monotonically, so the first address allocated from this base will
+be 10.1.1.1, followed by 10.1.1.2, etc.  The low level |ns3| system
+actually remembers all of the IP addresses allocated and will generate a
+fatal error if you accidentally cause the same address to be generated twice 
+(which is a very hard to debug error, by the way).
+
+The next line of code,
+
+::
+
+    Ipv4InterfaceContainer interfaces = address.Assign (devices);
+
+performs the actual address assignment.  In |ns3| we make the
+association between an IP address and a device using an ``Ipv4Interface``
+object.  Just as we sometimes need a list of net devices created by a helper 
+for future reference we sometimes need a list of ``Ipv4Interface`` objects.
+The ``Ipv4InterfaceContainer`` provides this functionality.
+
+Now we have a point-to-point network built, with stacks installed and IP 
+addresses assigned.  What we need at this point are applications to generate
+traffic.
+
+Applications
++++++++++++
+Another one of the core abstractions of the ns-3 system is the 
+``Application``.  In this script we use two specializations of the core
+|ns3| class ``Application`` called ``UdpEchoServerApplication``
+and ``UdpEchoClientApplication``.  Just as we have in our previous 
+explanations,  we use helper objects to help configure and manage the 
+underlying objects.  Here, we use ``UdpEchoServerHelper`` and
+``UdpEchoClientHelper`` objects to make our lives easier.
+
+UdpEchoServerHelper
+~~~~~~~~~~~~~~~~~~~
+The following lines of code in our example script, ``first.cc``, are used
+to set up a UDP echo server application on one of the nodes we have previously
+created.
+
+::
+
+    UdpEchoServerHelper echoServer (9);
+
+    ApplicationContainer serverApps = echoServer.Install (nodes.Get (1));
+    serverApps.Start (Seconds (1.0));
+    serverApps.Stop (Seconds (10.0));
+
+The first line of code in the above snippet declares the 
+``UdpEchoServerHelper``.  As usual, this isn't the application itself, it
+is an object used to help us create the actual applications.  One of our 
+conventions is to place *required* ``Attributes`` in the helper constructor.
+In this case, the helper can't do anything useful unless it is provided with
+a port number that the client also knows about.  Rather than just picking one 
+and hoping it all works out, we require the port number as a parameter to the 
+constructor.  The constructor, in turn, simply does a ``SetAttribute``
+with the passed value.  If you want, you can set the "Port" ``Attribute``
+to another value later using ``SetAttribute``.
+
+Similar to many other helper objects, the ``UdpEchoServerHelper`` object 
+has an ``Install`` method.  It is the execution of this method that actually
+causes the underlying echo server application to be instantiated and attached
+to a node.  Interestingly, the ``Install`` method takes a
+``NodeContainter`` as a parameter just as the other ``Install`` methods
+we have seen.  This is actually what is passed to the method even though it 
+doesn't look so in this case.  There is a C++ *implicit conversion* at
+work here that takes the result of ``nodes.Get (1)`` (which returns a smart
+pointer to a node object --- ``Ptr<Node>``) and uses that in a constructor
+for an unnamed ``NodeContainer`` that is then passed to ``Install``.
+If you are ever at a loss to find a particular method signature in C++ code
+that compiles and runs just fine, look for these kinds of implicit conversions.  
+
+We now see that ``echoServer.Install`` is going to install a
+``UdpEchoServerApplication`` on the node found at index number one of the
+``NodeContainer`` we used to manage our nodes.  ``Install`` will return
+a container that holds pointers to all of the applications (one in this case 
+since we passed a ``NodeContainer`` containing one node) created by the 
+helper.
+
+Applications require a time to "start" generating traffic and may take an
+optional time to "stop".  We provide both.  These times are set using  the
+``ApplicationContainer`` methods ``Start`` and ``Stop``.  These 
+methods take ``Time`` parameters.  In this case, we use an *explicit*
+C++ conversion sequence to take the C++ double 1.0 and convert it to an 
+|ns3| ``Time`` object using a ``Seconds`` cast.  Be aware that
+the conversion rules may be controlled by the model author, and C++ has its
+own rules, so you can't always just assume that parameters will be happily 
+converted for you.  The two lines,
+
+::
+
+    serverApps.Start (Seconds (1.0));
+    serverApps.Stop (Seconds (10.0));
+
+will cause the echo server application to ``Start`` (enable itself) at one
+second into the simulation and to ``Stop`` (disable itself) at ten seconds
+into the simulation.  By virtue of the fact that we have declared a simulation
+event (the application stop event) to be executed at ten seconds, the simulation
+will last *at least* ten seconds.
+
+UdpEchoClientHelper
+~~~~~~~~~~~~~~~~~~~
+
+The echo client application is set up in a method substantially similar to
+that for the server.  There is an underlying ``UdpEchoClientApplication``
+that is managed by an ``UdpEchoClientHelper``.
+
+::
+
+    UdpEchoClientHelper echoClient (interfaces.GetAddress (1), 9);
+    echoClient.SetAttribute ("MaxPackets", UintegerValue (1));
+    echoClient.SetAttribute ("Interval", TimeValue (Seconds (1.)));
+    echoClient.SetAttribute ("PacketSize", UintegerValue (1024));
+
+    ApplicationContainer clientApps = echoClient.Install (nodes.Get (0));
+    clientApps.Start (Seconds (2.0));
+    clientApps.Stop (Seconds (10.0));
+
+For the echo client, however, we need to set five different ``Attributes``.
+The first two ``Attributes`` are set during construction of the 
+``UdpEchoClientHelper``.  We pass parameters that are used (internally to
+the helper) to set the "RemoteAddress" and "RemotePort" ``Attributes``
+in accordance with our convention to make required ``Attributes`` parameters
+in the helper constructors.  
+
+Recall that we used an ``Ipv4InterfaceContainer`` to keep track of the IP 
+addresses we assigned to our devices.  The zeroth interface in the 
+``interfaces`` container is going to correspond to the IP address of the 
+zeroth node in the ``nodes`` container.  The first interface in the 
+``interfaces`` container corresponds to the IP address of the first node 
+in the ``nodes`` container.  So, in the first line of code (from above), we
+are creating the helper and telling it so set the remote address of the client
+to be  the IP address assigned to the node on which the server resides.  We 
+also tell it to arrange to send packets to port nine.
+
+The "MaxPackets" ``Attribute`` tells the client the maximum number of 
+packets we allow it to send during the simulation.  The "Interval" 
+``Attribute`` tells the client how long to wait between packets, and the
+"PacketSize" ``Attribute`` tells the client how large its packet payloads
+should be.  With this particular combination of ``Attributes``, we are 
+telling the client to send one 1024-byte packet.
+
+Just as in the case of the echo server, we tell the echo client to ``Start``
+and ``Stop``, but here we start the client one second after the server is
+enabled (at two seconds into the simulation).
+
+Simulator
+++++++++
+What we need to do at this point is to actually run the simulation.  This is 
+done using the global function ``Simulator::Run``.
+
+::
+
+    Simulator::Run ();
+
+When we previously called the methods,
+
+::
+
+    serverApps.Start (Seconds (1.0));
+    serverApps.Stop (Seconds (10.0));
+    ...
+    clientApps.Start (Seconds (2.0));
+    clientApps.Stop (Seconds (10.0));
+
+we actually scheduled events in the simulator at 1.0 seconds, 2.0 seconds and
+two events at 10.0 seconds.  When ``Simulator::Run`` is called, the system 
+will begin looking through the list of scheduled events and executing them.  
+First it will run the event at 1.0 seconds, which will enable the echo server 
+application (this event may, in turn, schedule many other events).  Then it 
+will run the event scheduled for t=2.0 seconds which will start the echo client
+application.  Again, this event may schedule many more events.  The start event
+implementation in the echo client application will begin the data transfer phase
+of the simulation by sending a packet to the server.
+
+The act of sending the packet to the server will trigger a chain of events
+that will be automatically scheduled behind the scenes and which will perform 
+the mechanics of the packet echo according to the various timing parameters 
+that we have set in the script.
+
+Eventually, since we only send one packet (recall the ``MaxPackets`` 
+``Attribute`` was set to one), the chain of events triggered by 
+that single client echo request will taper off and the simulation will go 
+idle.  Once this happens, the remaining events will be the ``Stop`` events
+for the server and the client.  When these events are executed, there are
+no further events to process and ``Simulator::Run`` returns.  The simulation
+is then complete.
+
+All that remains is to clean up.  This is done by calling the global function 
+``Simulator::Destroy``.  As the helper functions (or low level 
+|ns3| code) executed, they arranged it so that hooks were inserted in
+the simulator to destroy all of the objects that were created.  You did not 
+have to keep track of any of these objects yourself --- all you had to do 
+was to call ``Simulator::Destroy`` and exit.  The |ns3| system
+took care of the hard part for you.  The remaining lines of our first 
+|ns3| script, ``first.cc``, do just that:
+
+::
+
+    Simulator::Destroy ();
+    return 0;
+  }
+
+Building Your Script
++++++++++++++++++++
+We have made it trivial to build your simple scripts.  All you have to do is 
+to drop your script into the scratch directory and it will automatically be 
+built 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.
+
+::
+
+  cd ../..
+  cp examples/tutorial/first.cc scratch/myfirst.cc
+
+Now build your first example script using waf:
+
+::
+
+  ./waf
+
+You should see messages reporting that your ``myfirst`` example was built
+successfully.
+
+::
+
+  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
+  [706/708] cxx_link: build/debug/scratch/myfirst_3.o -> build/debug/scratch/myfirst
+  Waf: Leaving directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build'
+  'build' finished successfully (2.357s)
+
+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):
+
+::
+
+  ./waf --run scratch/myfirst
+
+You should see some output:
+
+::
+
+  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.418s)
+  Sent 1024 bytes to 10.1.1.2
+  Received 1024 bytes from 10.1.1.1
+  Received 1024 bytes from 10.1.1.2
+
+Here you see that the build system checks to make sure that the file has been
+build and then runs it.  You see the logging component on the echo client 
+indicate that it has sent one 1024 byte packet to the Echo Server on 
+10.1.1.2.  You also see the logging component on the echo server say that
+it has received the 1024 bytes from 10.1.1.1.  The echo server silently 
+echoes the packet and you see the echo client log that it has received its 
+packet back from the server.
+
+Ns-3 Source Code
+****************
+
+Now that you have used some of the |ns3| helpers you may want to 
+have a look at some of the source code that implements that functionality.
+The most recent code can be browsed on our web server at the following link:
+http://code.nsnam.org/ns-3-dev.  There, you will see the Mercurial
+summary page for our |ns3| development tree.
+
+At the top of the page, you will see a number of links,
+
+::
+
+  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:
+
+::
+
+  drwxr-xr-x                               [up]     
+  drwxr-xr-x                               bindings python  files
+  drwxr-xr-x                               doc              files
+  drwxr-xr-x                               examples         files
+  drwxr-xr-x                               ns3              files
+  drwxr-xr-x                               scratch          files
+  drwxr-xr-x                               src              files
+  drwxr-xr-x                               utils            files
+  -rw-r--r-- 2009-07-01 12:47 +0200 560    .hgignore        file | revisions | annotate
+  -rw-r--r-- 2009-07-01 12:47 +0200 1886   .hgtags          file | revisions | annotate
+  -rw-r--r-- 2009-07-01 12:47 +0200 1276   AUTHORS          file | revisions | annotate
+  -rw-r--r-- 2009-07-01 12:47 +0200 30961  CHANGES.html     file | revisions | annotate
+  -rw-r--r-- 2009-07-01 12:47 +0200 17987  LICENSE          file | revisions | annotate
+  -rw-r--r-- 2009-07-01 12:47 +0200 3742   README           file | revisions | annotate
+  -rw-r--r-- 2009-07-01 12:47 +0200 16171  RELEASE_NOTES    file | revisions | annotate
+  -rw-r--r-- 2009-07-01 12:47 +0200 6      VERSION          file | revisions | annotate
+  -rwxr-xr-x 2009-07-01 12:47 +0200 88110  waf              file | revisions | annotate
+  -rwxr-xr-x 2009-07-01 12:47 +0200 28     waf.bat          file | revisions | annotate
+  -rw-r--r-- 2009-07-01 12:47 +0200 35395  wscript          file | revisions | annotate
+  -rw-r--r-- 2009-07-01 12:47 +0200 7673   wutils.py        file | revisions | annotate
+  
+Our example scripts are in the ``examples`` directory.  If you click on ``examples``
+you will see a list of subdirectories.  One of the files in ``tutorial`` subdirectory is ``first.cc``.  If
+you click on ``first.cc`` you will find the code you just walked through.
+
+The source code is mainly in the ``src`` directory.  You can view source
+code either by clicking on the directory name or by clicking on the ``files``
+link to the right of the directory name.  If you click on the ``src``
+directory, you will be taken to the listing of the ``src`` subdirectories.  If you 
+then click on ``core`` subdirectory, you will find a list of files.  The first file
+you will find (as of this writing) is ``abort.h``.  If you click on the 
+``abort.h`` link, you will be sent to the source file for ``abort.h`` which 
+contains useful macros for exiting scripts if abnormal conditions are detected.
+
+The source code for the helpers we have used in this chapter can be found in the 
+``src/applications/helper`` directory.  Feel free to poke around in the directory tree to
+get a feel for what is there and the style of |ns3| programs.
@@ -0,0 +1,31 @@
+.. include:: replace.txt
+
+
+Conclusion
+----------
+
+Futures
+*******
+
+This document is intended as a living document.  We hope and expect it to 
+grow over time to cover more and more of the nuts and bolts of |ns3|.  
+
+Writing manual and tutorial chapters is not something we all get excited about,
+but it is very important to the project.  If you are an expert in one of these
+areas, please consider contributing to |ns3| by providing one of these
+chapters; or any other chapter you may think is important.
+
+Closing
+*******
+
+|ns3| is a large and complicated system.  It is impossible to cover all 
+of the things you will need to know in one small tutorial.  Readers
+who want to learn more are encouraged to read the following additional
+documentation:
+
+* The |ns3| manual
+* The |ns3| model library documentatio
+* The |ns3| Doxygen (API documentation)
+* The |ns3| wiki
+
+-- The |ns3| development team.
@@ -0,0 +1,216 @@
+# -*- coding: utf-8 -*-
+#
+# ns-3 documentation build configuration file, created by
+# sphinx-quickstart on Tue Dec 14 09:00:39 2010.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys, os
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#sys.path.insert(0, os.path.abspath('.'))
+
+# -- General configuration -----------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be extensions
+# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
+extensions = ['sphinx.ext.pngmath']
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+# The encoding of source files.
+#source_encoding = 'utf-8-sig'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = u'ns-3'
+copyright = u'2010, ns-3 project'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = 'ns-3-dev'
+# The full version, including alpha/beta/rc tags.
+release = 'ns-3-dev'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#language = None
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+#today = ''
+# Else, today_fmt is used as the format for a strftime call.
+#today_fmt = '%B %d, %Y'
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+exclude_patterns = []
+
+# The reST default role (used for this markup: `text`) to use for all documents.
+#default_role = None
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+#add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+#add_module_names = True
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+#show_authors = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# A list of ignored prefixes for module index sorting.
+#modindex_common_prefix = []
+
+
+# -- Options for HTML output ---------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+html_theme = 'default'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+#html_theme_options = {}
+
+# Add any paths that contain custom themes here, relative to this directory.
+#html_theme_path = []
+
+# The name for this set of Sphinx documents.  If None, it defaults to
+# "<project> v<release> documentation".
+#html_title = None
+
+# A shorter title for the navigation bar.  Default is the same as html_title.
+#html_short_title = None
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+#html_logo = None
+
+# The name of an image file (within the static path) to use as favicon of the
+# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+#html_favicon = None
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+#html_last_updated_fmt = '%b %d, %Y'
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+#html_use_smartypants = True
+
+# Custom sidebar templates, maps document names to template names.
+#html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+#html_additional_pages = {}
+
+# If false, no module index is generated.
+#html_domain_indices = True
+
+# If false, no index is generated.
+#html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+#html_split_index = False
+
+# If true, links to the reST sources are added to the pages.
+#html_show_sourcelink = True
+
+# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
+#html_show_sphinx = True
+
+# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
+#html_show_copyright = True
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> tag referring to it.  The value of this option must be the
+# base URL from which the finished HTML is served.
+#html_use_opensearch = ''
+
+# This is the file name suffix for HTML files (e.g. ".xhtml").
+#html_file_suffix = None
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'ns-3doc'
+
+
+# -- Options for LaTeX output --------------------------------------------------
+
+# The paper size ('letter' or 'a4').
+#latex_paper_size = 'letter'
+
+# The font size ('10pt', '11pt' or '12pt').
+#latex_font_size = '10pt'
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, documentclass [howto/manual]).
+latex_documents = [
+  ('index', 'ns-3-tutorial.tex', u'ns-3 Tutorial',
+   u'ns-3 project', 'manual'),
+]
+
+# The name of an image file (relative to this directory) to place at the top of
+# the title page.
+#latex_logo = None
+
+# For "manual" documents, if this is true, then toplevel headings are parts,
+# not chapters.
+#latex_use_parts = False
+
+# If true, show page references after internal links.
+#latex_show_pagerefs = False
+
+# If true, show URL addresses after external links.
+#latex_show_urls = False
+
+# Additional stuff for the LaTeX preamble.
+#latex_preamble = ''
+
+# Documents to append as an appendix to all manuals.
+#latex_appendices = []
+
+# If false, no module index is generated.
+#latex_domain_indices = True
+
+
+# -- Options for manual page output --------------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    ('index', 'ns-3-tutorial', u'ns-3 Tutorial',
+     [u'ns-3 project'], 1)
+]
@@ -0,0 +1 @@
+../figures
@@ -0,0 +1,547 @@
+	.. include:: replace.txt
+
+
+Getting Started
+---------------
+
+Downloading ns-3
+****************
+
+The |ns3| system as a whole is a fairly complex system and has a
+number of dependencies on other components.  Along with the systems you will
+most likely deal with every day (the GNU toolchain, Mercurial, you programmer
+editor) you will need to ensure that a number of additional libraries are
+present on your system before proceeding.  |ns3| provides a wiki
+for your reading pleasure that includes pages with many useful hints and tips.
+One such page is the "Installation" page,
+http://www.nsnam.org/wiki/index.php/Installation.
+
+The "Prerequisites" section of this wiki page explains which packages are 
+required to support common |ns3| options, and also provides the 
+commands used to install them for common Linux variants.  Cygwin users will
+have to use the Cygwin installer (if you are a Cygwin user, you used it to
+install Cygwin). 
+
+You may want to take this opportunity to explore the |ns3| wiki 
+a bit since there really is a wealth of information there. 
+
+From this point forward, we are going to assume that the reader is working in
+Linux or a Linux emulation environment (Linux, Cygwin, etc.) and has the GNU
+toolchain installed and verified along with the prerequisites mentioned 
+above.  We are also going to assume that you have Mercurial and Waf installed
+and running on the target system.
+
+The |ns3| code is available in Mercurial repositories on the server
+http://code.nsnam.org.  You can also download a tarball release at
+http://www.nsnam.org/releases/, or you can work with repositories
+using Mercurial.  We recommend using Mercurial unless there's a good reason
+not to.  See the end of this section for instructions on how to get a tarball
+release.
+
+The simplest way to get started using Mercurial repositories is to use the
+``ns-3-allinone`` environment.  This is a set of scripts that manages the 
+downloading and building of various subsystems of |ns3| for you.  We 
+recommend that you begin your |ns3| adventures in this environment
+as it can really simplify your life at this point.
+
+Downloading ns-3 Using Mercurial
++++++++++++++++++++++++++++++++
+One practice is to create a directory called ``repos`` in one's home 
+directory under which one can keep local Mercurial repositories.  
+*Hint:  we will assume you do this later in the tutorial.*  If you adopt
+that approach, you can get a copy of ``ns-3-allinone`` by typing the 
+following into your Linux shell (assuming you have installed Mercurial):
+
+::
+  cd
+  mkdir repos
+  cd repos
+  hg clone http://code.nsnam.org/ns-3-allinone
+
+As the hg (Mercurial) command executes, you should see something like the 
+following displayed,
+
+::
+
+  destination directory: ns-3-allinone
+  requesting all changes
+  adding changesets
+  adding manifests
+  adding file changes
+  added 47 changesets with 67 changes to 7 files
+  updating to branch default
+  7 files updated, 0 files merged, 0 files removed, 0 files unresolved
+
+After the clone command completes, you should have a directory called 
+``ns-3-allinone``, the contents of which should 
+look something like the following:
+
+::
+
+  build.py*  constants.py  dist.py*  download.py*  README  util.py
+
+Notice that you really just downloaded some Python scripts.  The next step
+will be to use those scripts to download and build the |ns3|
+distribution of your choice.
+
+If you go to the following link: http://code.nsnam.org/,
+you will see a number of repositories.  Many are the private repositories of
+the |ns3| development team.  The repositories of interest to you will
+be prefixed with "ns-3".  Official releases of |ns3| will be 
+numbered as ``ns-3.<release>.<hotfix>``.  For example, a second hotfix to a
+still hypothetical release forty two of |ns3| would be numbered as
+``ns-3.42.2``.
+
+The current development snapshot (unreleased) of |ns3| may be found 
+at http://code.nsnam.org/ns-3-dev/.  The 
+developers attempt to keep these repository in consistent, working states but
+they are in a development area with unreleased code present, so you may want 
+to consider staying with an official release if you do not need newly-
+introduced features.
+
+Since the release numbers are going to be changing, I will stick with 
+the more constant ns-3-dev here in the tutorial, but you can replace the 
+string "ns-3-dev" with your choice of release (e.g., ns-3.10) in the 
+text below.  You can find the latest version  of the
+code either by inspection of the repository list or by going to the 
+`"ns-3 Releases"
+<http://www.nsnam.org/releases>`_
+web page and clicking on the latest release link.
+
+Go ahead and change into the ``ns-3-allinone`` directory you created when
+you cloned that repository.  We are now going to use the ``download.py`` 
+script to pull down the various pieces of |ns3| you will be using.
+
+Go ahead and type the following into your shell (remember you can substitute
+the name of your chosen release number instead of ``ns-3-dev`` -- like
+``"ns-3.10"`` if you want to work with a 
+stable release).
+
+::
+
+  ./download.py -n ns-3-dev
+
+Note that the default for the ``-n`` option is ``ns-3-dev`` and so the
+above is actually redundant.  We provide this example to illustrate how to
+specify alternate repositories.  In order to download ``ns-3-dev`` you 
+can actually use the defaults and simply type,
+
+::
+
+  ./download.py
+
+As the hg (Mercurial) command executes, you should see something like the 
+following,
+
+::
+
+      #
+      # Get NS-3
+      #
+  
+  Cloning ns-3 branch
+   =>  hg clone http://code.nsnam.org/ns-3-dev ns-3-dev
+  requesting all changes
+  adding changesets
+  adding manifests
+  adding file changes
+  added 4634 changesets with 16500 changes to 1762 files
+  870 files updated, 0 files merged, 0 files removed, 0 files unresolved
+
+This is output by the download script as it fetches the actual ``ns-3``
+code from the repository.
+
+The download script is smart enough to know that on some platforms various
+pieces of ns-3 are not supported.  On your platform you may not see some
+of these pieces come down.  However, on most platforms, the process should
+continue with something like,
+
+::
+
+      #
+      # Get PyBindGen
+      #
+
+  Required pybindgen version:  0.10.0.640
+  Trying to fetch pybindgen; this will fail if no network connection is available.  Hit Ctrl-C to skip.
+   =>  bzr checkout -rrevno:640 https://launchpad.net/pybindgen pybindgen
+  Fetch was successful.
+
+This was the download script getting the Python bindings generator for you.
+Note that you will need bazaar (bzr), a version control system, to download 
+PyBindGen. Next you should see (modulo platform variations) something along 
+the lines of,
+
+::
+
+      #
+      # Get NSC
+      #
+
+  Required NSC version:  nsc-0.5.0
+  Retrieving nsc from https://secure.wand.net.nz/mercurial/nsc
+   =>  hg clone https://secure.wand.net.nz/mercurial/nsc nsc
+  requesting all changes
+  adding changesets
+  adding manifests
+  adding file changes
+  added 273 changesets with 17565 changes to 15175 files
+  10622 files updated, 0 files merged, 0 files removed, 0 files unresolved
+
+This part of the process is the script downloading the Network Simulation
+Cradle for you. Note that NSC is not supported on OSX or Cygwin and works 
+best with gcc-3.4 or gcc-4.2 or greater series.
+
+After the download.py script completes, you should have several new directories
+under ``~/repos/ns-3-allinone``:
+
+::
+
+  build.py*     constants.pyc  download.py*  nsc/        README      util.pyc
+  constants.py  dist.py*       ns-3-dev/     pybindgen/  util.py
+
+Go ahead and change into ``ns-3-dev`` under your ``~/repos/ns-3-allinone`` 
+directory.  You should see something like the following there:
+
+::
+
+  AUTHORS       doc       ns3            scratch   testpy.supp  VERSION   waf-tools
+  bindings      examples  README         src       utils        waf*      wscript
+  CHANGES.html  LICENSE   RELEASE_NOTES  test.py*  utils.py     waf.bat*  wutils.py
+
+You are now ready to build the |ns3| distribution.
+
+Downloading ns-3 Using a Tarball
++++++++++++++++++++++++++++++++
+The process for downloading |ns3| via tarball is simpler than the
+Mercurial process since all of the pieces are pre-packaged for you.  You just
+have to pick a release, download it and decompress it.
+
+As mentioned above, one practice is to create a directory called ``repos``
+in one's home directory under which one can keep local Mercurial repositories.
+One could also keep a ``tarballs`` directory.  *Hint:  the tutorial
+will assume you downloaded into a ``repos`` directory, so remember the
+placekeeper.*  If you adopt the ``tarballs`` directory approach, you can 
+get a copy of a release by typing the following into your Linux shell 
+(substitute the appropriate version numbers, of course):
+
+::
+
+  cd
+  mkdir tarballs
+  cd tarballs
+  wget http://www.nsnam.org/releases/ns-allinone-3.13.tar.bz2
+  tar xjf ns-allinone-3.13.tar.bz2
+
+If you change into the directory ``ns-allinone-3.13`` you should see a
+number of files:
+
+::
+
+  build.py      ns-3.13/      pybindgen-0.15.0.795/    util.py
+  constants.py  nsc-0.5.2/    README  
+
+You are now ready to build the |ns3| distribution.
+
+Building ns-3
+*************
+
+Building with build.py
++++++++++++++++++++++
+The first time you build the |ns3| project you should build using the
+``allinone`` environment.  This will get the project configured for you
+in the most commonly useful way.
+
+Change into the directory you created in the download section above.  If you
+downloaded using Mercurial you should have a directory called 
+``ns-3-allinone`` under your ``~/repos`` directory.  If you downloaded
+using a tarball you should have a directory called something like 
+``ns-allinone-3.13`` under your ``~/tarballs`` directory.  Take a deep
+breath and type the following:
+
+::
+
+  ./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
+build.py tells it to build them for us.  In the future you can build
+|ns3| without examples and tests if you wish.
+
+You will see lots of typical compiler output messages displayed as the build
+script builds the various pieces you downloaded.  Eventually you should see the
+following magic words:
+
+::
+
+  Waf: Leaving directory `/home/craigdo/repos/ns-3-allinone/ns-3.13/build'
+  'build' finished successfully (2m30.586s)
+  
+  Modules built: 
+  aodv                      applications              bridge
+  click                     config-store              core
+  csma                      csma-layout               dsdv
+  emu                       energy                    flow-monitor
+  internet                  lte                       mesh
+  mobility                  mpi                       netanim
+  network                   nix-vector-routing        ns3tcp
+  ns3wifi                   olsr                      openflow
+  point-to-point            point-to-point-layout     propagation
+  spectrum                  stats                     tap-bridge
+  template                  test                      tools
+  topology-read             uan                       virtual-net-device
+  visualizer                wifi                      wimax
+
+Once the project has built, you can stop working with the
+``ns-3-allinone`` scripts.  You got what you needed from them and will now 
+interact directly with Waf and we do it in the |ns3| directory,
+not in the ``ns-3-allinone`` directory.  Go ahead and change into the 
+|ns3| directory (or the directory for the appropriate release  or
+development snapshot that you downloaded; e.g.  
+
+::
+
+  cd ns-3-dev
+
+Building with Waf
+++++++++++++++++
+We use Waf to configure and build the |ns3| project.  It's not 
+strictly required at this point, but it will be valuable to take a slight
+detour and look at how to make changes to the configuration of the project.
+Probably the most useful configuration change you can make will be to 
+build the optimized version of the code.  By default you have configured
+your project to build the debug version.  Let's tell the project to 
+make an optimized build.  To explain to Waf that it should do optimized
+builds that include the examples and tests, you will need to execute the 
+following command,
+
+::
+
+  ./waf -d optimized --enable-examples --enable-tests configure
+
+This runs Waf out of the local directory (which is provided as a convenience
+for you).  As the build system checks for various dependencies you should see
+output that looks similar to the following,
+
+::
+
+  Checking for program g++                 : ok /usr/bin/g++
+  Checking for program cpp                 : ok /usr/bin/cpp
+  Checking for program ar                  : ok /usr/bin/ar
+  Checking for program ranlib              : ok /usr/bin/ranlib
+  Checking for g++                         : ok
+  Checking for program pkg-config          : ok /usr/bin/pkg-config
+  Checking for -Wno-error=deprecated-declarations support : yes
+  Checking for -Wl,--soname=foo support                   : yes
+  Checking for header stdlib.h                            : ok
+  Checking for header signal.h                            : ok
+  Checking for header pthread.h                           : ok
+  Checking for high precision time implementation         : 128-bit integer
+  Checking for header stdint.h                            : ok
+  Checking for header inttypes.h                          : ok
+  Checking for header sys/inttypes.h                      : not found
+  Checking for library rt                                 : ok
+  Checking for header netpacket/packet.h                  : ok
+  Checking for pkg-config flags for GSL                   : ok
+  Checking for header linux/if_tun.h                      : ok
+  Checking for pkg-config flags for GTK_CONFIG_STORE      : ok
+  Checking for pkg-config flags for LIBXML2               : ok
+  Checking for library sqlite3                            : ok
+  Checking for NSC location                               : ok ../nsc (guessed)
+  Checking for library dl                                 : ok
+  Checking for NSC supported architecture x86_64          : ok
+  Checking for program python                             : ok /usr/bin/python
+  Checking for Python version >= 2.3                      : ok 2.5.2
+  Checking for library python2.5                          : ok
+  Checking for program python2.5-config                   : ok /usr/bin/python2.5-config
+  Checking for header Python.h                            : ok
+  Checking for -fvisibility=hidden support                : yes
+  Checking for pybindgen location                         : ok ../pybindgen (guessed)
+  Checking for Python module pybindgen                    : ok
+  Checking for pybindgen version                          : ok 0.10.0.640
+  Checking for Python module pygccxml                     : ok
+  Checking for pygccxml version                           : ok 0.9.5
+  Checking for program gccxml                             : ok /usr/local/bin/gccxml
+  Checking for gccxml version                             : ok 0.9.0
+  Checking for program sudo                               : ok /usr/bin/sudo
+  Checking for program hg                                 : ok /usr/bin/hg
+  Checking for program valgrind                           : ok /usr/bin/valgrind
+  ---- Summary of optional NS-3 features:
+  Threading Primitives          : enabled
+  Real Time Simulator           : enabled
+  Emulated Net Device           : enabled
+  GNU Scientific Library (GSL)  : enabled
+  Tap Bridge                    : enabled
+  GtkConfigStore                : enabled
+  XmlIo                         : enabled
+  SQlite stats data output      : enabled
+  Network Simulation Cradle     : enabled
+  Python Bindings               : enabled
+  Python API Scanning Support   : enabled
+  Use sudo to set suid bit      : not enabled (option --enable-sudo not selected)
+  Build tests                   : enabled
+  Build examples                : enabled
+  Static build                  : not enabled (option --enable-static not selected)
+  'configure' finished successfully (2.870s)
+
+Note the last part of the above output.  Some ns-3 options are not enabled by
+default or require support from the underlying system to work properly.
+For instance, to enable XmlTo, the library libxml-2.0 must be found on the
+system.  If this library were not found, the corresponding |ns3| feature 
+would not be enabled and a message would be displayed.  Note further that there is 
+a feature to use the program ``sudo`` to set the suid bit of certain programs.
+This is not enabled by default and so this feature is reported as "not enabled."
+
+Now go ahead and switch back to the debug build that includes the examples and tests.
+
+::
+
+  ./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
+
+Some waf commands are meaningful during the build phase and some commands are valid
+in the configuration phase.  For example, if you wanted to use the emulation 
+features of |ns3|, you might want to enable setting the suid bit using
+sudo as described above.  This turns out to be a configuration-time command, and so 
+you could reconfigure using the following command that also includes the examples and tests
+
+::
+
+  ./waf -d debug --enable-sudo --enable-examples --enable-tests configure
+
+If you do this, waf will have run sudo to change the socket creator programs of the
+emulation code to run as root.  There are many other configure- and build-time options
+available in waf.  To explore these options, type:
+
+::
+
+  ./waf --help
+
+We'll use some of the testing-related commands in the next section.
+
+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.
+
+Testing ns-3
+************
+
+You can run the unit tests of the |ns3| distribution by running the 
+"./test.py -c core" script,
+
+::
+
+  ./test.py -c core
+
+These tests are run in parallel by waf. You should eventually
+see a report saying that,
+
+::
+
+  92 of 92 tests passed (92 passed, 0 failed, 0 crashed, 0 valgrind errors)
+
+This is the important message.
+
+You will also see output from the test runner and the output will actually look something like,
+
+::
+
+  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 (1.799s)
+  
+  Modules built: 
+  aodv                      applications              bridge
+  click                     config-store              core
+  csma                      csma-layout               dsdv
+  emu                       energy                    flow-monitor
+  internet                  lte                       mesh
+  mobility                  mpi                       netanim
+  network                   nix-vector-routing        ns3tcp
+  ns3wifi                   olsr                      openflow
+  point-to-point            point-to-point-layout     propagation
+  spectrum                  stats                     tap-bridge
+  template                  test                      tools
+  topology-read             uan                       virtual-net-device
+  visualizer                wifi                      wimax
+
+  PASS: TestSuite ns3-wifi-interference
+  PASS: TestSuite histogram
+  PASS: TestSuite sample
+  PASS: TestSuite ipv4-address-helper
+  PASS: TestSuite devices-wifi
+  PASS: TestSuite propagation-loss-model
+
+  ...
+
+  PASS: TestSuite attributes
+  PASS: TestSuite config
+  PASS: TestSuite global-value
+  PASS: TestSuite command-line
+  PASS: TestSuite basic-random-number
+  PASS: TestSuite object
+  PASS: TestSuite random-number-generators
+  92 of 92 tests passed (92 passed, 0 failed, 0 crashed, 0 valgrind errors)
+
+This command is typically run by users to quickly verify that an 
+|ns3| distribution has built correctly.  
+
+Running a Script
+****************
+We typically run scripts under the control of Waf.  This allows the build 
+system to ensure that the shared library paths are set correctly and that
+the libraries are available at run time.  To run a program, simply use the
+``--run`` option in Waf.  Let's run the |ns3| equivalent of the
+ubiquitous hello world program by typing the following:
+
+::
+
+  ./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 
+produces the following output.
+
+::
+
+  Hello Simulator
+
+*Congratulations.  You are now an ns-3 user.*
+
+*What do I do if I don't see the output?*
+
+If you don't see ``waf`` messages indicating that the build was 
+completed successfully, but do not see the "Hello Simulator" output, 
+chances are that you have switched your build mode to "optimized" in 
+the "Building with Waf" section, but have missed the change back to 
+"debug" mode.  All of the console output used in this tutorial uses a 
+special |ns3| logging component that is useful for printing 
+user messages to the console.  Output from this component is 
+automatically disabled when you compile optimized code -- it is 
+"optimized out."  If you don't see the "Hello Simulator" output,
+type the following,
+
+::
+
+  ./waf -d debug --enable-examples --enable-tests configure
+
+to tell ``waf`` to build the debug versions of the |ns3| 
+programs that includes the examples and tests.  You must still build 
+the actual debug version of the code by typing,
+
+::
+
+  ./waf
+
+Now, if you run the ``hello-simulator`` program, you should see the 
+expected output.
+
+If you want to run programs under another tool such as gdb or valgrind,
+see this `wiki entry
+<http://www.nsnam.org/wiki/index.php/User_FAQ#How_to_run_NS-3_programs_under_another_tool>`_.
+
--- a/Show More
+++ b/Show More
@@ -1 +1 @@
 .0.9
 -dev