--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/manual/source/new-modules.rst Thu May 12 14:13:48 2011 -0700
@@ -0,0 +1,243 @@
+.. 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 - Copy the template module
+*********************************
+
+The template module ::
+
+ src/template
+
+is a skeleton module that shows how modules should be created.
+
+For the purposes of this discussion we will assume that your new module is called "new-module". From the top level |ns3| directory, do the following to copy the template module to a new directory with the same name as your new module: ::
+
+ cp -r src/template src/new-module
+
+Now you will need to open the following file in your favorite text editor: ::
+
+ src/new-module/wscript
+
+and replace all of the occurrences of "template" in this wscript file with the name of your new module, i.e. "new-module" for our assumed module name.
+
+If your module will have model source files, then create the following directory where they will go: ::
+
+ mkdir src/new-module/model
+
+Copy all of your module's model source files to the above directory.
+
+If your module will have helper source files, then create the following directory where they will go: ::
+
+ mkdir src/new-module/helper
+
+Copy all of your module's helper source files to the above directory.
+
+Step 3 - Specify 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 function call and list
+of source files. Note that the second argument for the function
+create_ns3_module() is the list of modules that the module being created
+depends on: ::
+
+ module = bld.create_ns3_module('spectrum', ['internet', 'propagation', 'applications'])
+
+ 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: ::
+
+ headers = bld.new_task_gen('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 call and source file name. 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('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
+**************************************************************
+
+If your new module has examples, then you must specify which of them
+should be run in your ::
+
+ src/new-module/tests/examples-to-run.py
+
+file by modifying it with your text editor. These examples are run by
+test.py.
+
+As an example, the examples that are run by test.py for the core module are specified in ::
+
+ src/core/tests/examples-to-run
+
+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"),
+ ]
+
+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
+
+
--- a/doc/manual/source/support.rst Thu May 12 01:08:05 2011 +0200
+++ b/doc/manual/source/support.rst Thu May 12 14:13:48 2011 -0700
@@ -7,6 +7,7 @@
animation
statistics
new-models
+ new-modules
enable-modules
enable-tests
troubleshoot
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/src/core/test/sample-test-suite.cc Thu May 12 14:13:48 2011 -0700
@@ -0,0 +1,63 @@
+/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
+
+// An essential include is test.h
+#include "ns3/test.h"
+
+// Do not put your test classes in namespace ns3. You may find it useful
+// to use the using directive to access the ns3 namespace directly
+using namespace ns3;
+
+// This is an example TestCase.
+class SampleTestCase1 : public TestCase
+{
+public:
+ SampleTestCase1 ();
+ virtual ~SampleTestCase1 ();
+
+private:
+ virtual void DoRun (void);
+};
+
+// Add some help text to this case to describe what it is intended to test
+SampleTestCase1::SampleTestCase1 ()
+ : TestCase ("Sample test case (does nothing)")
+{
+}
+
+// This destructor does nothing but we include it as a reminder that
+// the test case should clean up after itself
+SampleTestCase1::~SampleTestCase1 ()
+{
+}
+
+//
+// This method is the pure virtual method from class TestCase that every
+// TestCase must implement
+//
+void
+SampleTestCase1::DoRun (void)
+{
+ // A wide variety of test macros are available in src/core/test.h
+ NS_TEST_ASSERT_MSG_EQ (true, true, "true doesn't equal true for some reason");
+ // Use this one for floating point comparisons
+ NS_TEST_ASSERT_MSG_EQ_TOL (0.01, 0.01, 0.001, "Numbers are not equal within tolerance");
+}
+
+// The TestSuite class names the TestSuite, identifies what type of TestSuite,
+// and enables the TestCases to be run. Typically, only the constructor for
+// this class must be defined
+//
+class SampleTestSuite : public TestSuite
+{
+public:
+ SampleTestSuite ();
+};
+
+SampleTestSuite::SampleTestSuite ()
+ : TestSuite ("sample", UNIT)
+{
+ AddTestCase (new SampleTestCase1);
+}
+
+// Do not forget to allocate an instance of this TestSuite
+static SampleTestSuite sampleTestSuite;
--- a/src/core/wscript Thu May 12 01:08:05 2011 +0200
+++ b/src/core/wscript Thu May 12 14:13:48 2011 -0700
@@ -158,6 +158,7 @@
'test/object-test-suite.cc',
'test/ptr-test-suite.cc',
'test/random-variable-test-suite.cc',
+ 'test/sample-test-suite.cc',
'test/simulator-test-suite.cc',
'test/time-test-suite.cc',
'test/timer-test-suite.cc',
--- a/src/template/test/sample-test-suite.cc Thu May 12 01:08:05 2011 +0200
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,63 +0,0 @@
-/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
-
-// An essential include is test.h
-#include "ns3/test.h"
-
-// Do not put your test classes in namespace ns3. You may find it useful
-// to use the using directive to access the ns3 namespace directly
-using namespace ns3;
-
-// This is an example TestCase.
-class SampleTestCase1 : public TestCase
-{
-public:
- SampleTestCase1 ();
- virtual ~SampleTestCase1 ();
-
-private:
- virtual void DoRun (void);
-};
-
-// Add some help text to this case to describe what it is intended to test
-SampleTestCase1::SampleTestCase1 ()
- : TestCase ("Sample test case (does nothing)")
-{
-}
-
-// This destructor does nothing but we include it as a reminder that
-// the test case should clean up after itself
-SampleTestCase1::~SampleTestCase1 ()
-{
-}
-
-//
-// This method is the pure virtual method from class TestCase that every
-// TestCase must implement
-//
-void
-SampleTestCase1::DoRun (void)
-{
- // A wide variety of test macros are available in src/core/test.h
- NS_TEST_ASSERT_MSG_EQ (true, true, "true doesn't equal true for some reason");
- // Use this one for floating point comparisons
- NS_TEST_ASSERT_MSG_EQ_TOL (0.01, 0.01, 0.001, "Numbers are not equal within tolerance");
-}
-
-// The TestSuite class names the TestSuite, identifies what type of TestSuite,
-// and enables the TestCases to be run. Typically, only the constructor for
-// this class must be defined
-//
-class SampleTestSuite : public TestSuite
-{
-public:
- SampleTestSuite ();
-};
-
-SampleTestSuite::SampleTestSuite ()
- : TestSuite ("sample", UNIT)
-{
- AddTestCase (new SampleTestCase1);
-}
-
-// Do not forget to allocate an instance of this TestSuite
-static SampleTestSuite sampleTestSuite;
--- a/src/template/wscript Thu May 12 01:08:05 2011 +0200
+++ b/src/template/wscript Thu May 12 14:13:48 2011 -0700
@@ -7,19 +7,23 @@
# Set the C++ source files for this module.
module.source = [
- # Uncomment this line to compile this model source file.
- #'model/sample-model.cc',
+ # Uncomment these lines to compile these model source files.
+ #'model/sample-model-1.cc',
+ #'model/sample-model-2.cc',
- # Uncomment this line to compile this helper source file.
- #'helper/sample-helper.cc',
+ # Uncomment these lines to compile these helper source files.
+ #'helper/sample-helper-1.cc',
+ #'helper/sample-helper-2.cc',
]
# Create the module's test library.
- test_library = bld.create_ns3_module_test_library('template')
+ module_test = bld.create_ns3_module_test_library('template')
# Set the C++ source files for the module's test library.
- test_library.source = [
- 'test/sample-test-suite.cc',
+ module_test.source = [
+ # Uncomment these lines to compile these test suites.
+ #'test/sample-test-suite-1.cc',
+ #'test/sample-test-suite-2.cc',
]
# Make headers be installed for this module.
@@ -28,17 +32,19 @@
# Set the C++ header files for this module.
headers.source = [
- # Uncomment this line to install this model header file.
- #'model/sample-model.h',
+ # Uncomment these lines to install these model header files.
+ #'model/sample-model-1.h',
+ #'model/sample-model-2.h',
- # Uncomment this line to install this helper header file.
- #'helper/sample-helper.h',
+ # Uncomment these lines to install these helper header files.
+ #'helper/sample-helper-1.h',
+ #'helper/sample-helper-2.h',
]
# Uncomment these lines if this module needs a library such as the
# real-time (RT) library to be linked in at build time.
- #module .uselib = 'RT'
- #test_library.uselib = 'RT'
+ #module .uselib = 'RT'
+ #module_test.uselib = 'RT'
# Look for examples if they are enabled.
if (bld.env['ENABLE_EXAMPLES']):