build: (fixes #217) Guard compilation of example used as a test

* Added documentation to ExampleAsTestSuite on the need for this guarding
* Updated with Peter's patch for examples-as-test placeholders in wscripts

doc/manual/source/how-to-write-tests.rst

@@ -164,7 +164,13 @@ and command line arguments for the example.  In the preceding code the
 same example is run twice with different arguments.
 
 You then need to add that newly created test suite file to the list of
-test sources in ``mymodule/wscript``.
+test sources in ``mymodule/wscript``.  Building of examples
+is an option so you need to guard the inclusion of the test suite:
+
+.. sourcecode:: python
+
+   if (bld.env['ENABLE_EXAMPLES']):
+      module.source.append('model/mymodule-examples-test-suite.cc')
 
 Since you modified a wscript file you need to reconfigure and rebuild
 everything.

src/antenna/wscript

@@ -22,6 +22,12 @@ def build(bld):
         'test/test-parabolic-antenna.cc',
         ]
 
+    # Tests encapsulating example programs should be listed here
+    if (bld.env['ENABLE_EXAMPLES']):
+        module_test.source.extend([
+        #   'test/antenna-examples-test-suite.cc',
+            ])
+
     headers = bld(features='ns3header')
     headers.module = 'antenna'
     headers.source = [

src/aodv/wscript

@@ -23,6 +23,12 @@ def build(bld):
         'test/loopback.cc',
         ]
 
+    # Tests encapsulating example programs should be listed here
+    if (bld.env['ENABLE_EXAMPLES']):
+        aodv_test.source.extend([
+        #   'test/aodv-examples-test-suite.cc',
+            ])
+
     headers = bld(features='ns3header')
     headers.module = 'aodv'
     headers.source = [

src/applications/wscript

@@ -33,6 +33,12 @@ def build(bld):
         'test/udp-client-server-test.cc'
         ]
 
+    # Tests encapsulating example programs should be listed here
+    if (bld.env['ENABLE_EXAMPLES']):
+        applications_test.source.extend([
+        #   'test/applications-examples-test-suite.cc',
+            ])
+
     headers = bld(features='ns3header')
     headers.module = 'applications'
     headers.source = [

src/brite/wscript

@@ -92,6 +92,12 @@ def build(bld):
     module_test.source = [
         ]
 
+    # Tests encapsulating example programs should be listed here
+    if (bld.env['ENABLE_EXAMPLES']):
+        module_test.source.extend([
+        #   'test/brite-examples-test-suite.cc',
+            ])
+
     if bld.env['BRITE'] and bld.env['DL']:
         module.use.extend(['BRITE', 'DL'])
         module_test.use.extend(['BRITE', 'DL'])

src/buildings/wscript

@@ -27,6 +27,12 @@ def build(bld):
         'test/buildings-channel-condition-model-test.cc',
         ]
 
+    # Tests encapsulating example programs should be listed here
+    if (bld.env['ENABLE_EXAMPLES']):
+        module_test.source.extend([
+        #   'test/buildings-examples-test-suite.cc',
+            ])
+
     headers = bld(features='ns3header')
     headers.module = 'buildings'
     headers.source = [

src/click/wscript

@@ -113,6 +113,12 @@ def build(bld):
         'test/ipv4-click-routing-test.cc',
         ]
 
+    # Tests encapsulating example programs should be listed here
+    if (bld.env['ENABLE_EXAMPLES']):
+        module_test.source.extend([
+        #   'test/click-examples-test-suite.cc',
+            ])
+
     if bld.env['NSCLICK'] and bld.env['DL']:
         module.use.extend(['NSCLICK', 'DL'])
         module_test.use.extend(['NSCLICK', 'DL'])

src/core/model/example-as-test.h

@@ -148,7 +148,13 @@ class ExampleAsTestCase : public TestCase
  * the same example is run twice with different arguments.
  *
  * You then need to add that newly created test suite file to the list
- * of test sources in `mymodule/wscript`.
+ * of test sources in `mymodule/wscript`.   Building of examples
+ * is an option so you need to guard the inclusion of the test suite:
+ *
+ * \code{.py}
+ * if (bld.env['ENABLE_EXAMPLES']):
+ *    module.source.append('model/mymodule-examples-test-suite.cc')
+ * \endcode
  *
  * Since you modified a wscript file you need to reconfigure and
  * rebuild everything.

src/core/wscript

@@ -246,7 +246,9 @@ def build(bld):
         ]
 
     if (bld.env['ENABLE_EXAMPLES']):
-        core_test.source.append('test/examples-as-tests-test-suite.cc')
+        core_test.source.extend([
+            'test/examples-as-tests-test-suite.cc',
+            ])
 
     headers = bld(features='ns3header')
     headers.module = 'core'

src/dsdv/wscript

@@ -16,6 +16,12 @@ def build(bld):
         'test/dsdv-testcase.cc',
         ]
 
+    # Tests encapsulating example programs should be listed here
+    if (bld.env['ENABLE_EXAMPLES']):
+        module_test.source.extend([
+        #   'test/dsdv-examples-test-suite.cc',
+            ])
+
     headers = bld(features='ns3header')
     headers.module = 'dsdv'
     headers.source = [

src/dsr/wscript

@@ -25,6 +25,12 @@ def build(bld):
         'test/dsr-test-suite.cc',
         ]
 
+    # Tests encapsulating example programs should be listed here
+    if (bld.env['ENABLE_EXAMPLES']):
+        module_test.source.extend([
+        #   'test/dsr-examples-test-suite.cc',
+            ])
+
     headers = bld(features='ns3header')
     headers.module = 'dsr'
     headers.source = [

src/energy/wscript

@@ -28,6 +28,12 @@ def build(bld):
         'test/basic-energy-harvester-test.cc',
         ]
 
+    # Tests encapsulating example programs should be listed here
+    if (bld.env['ENABLE_EXAMPLES']):
+        obj_test.source.extend([
+        #   'test/energy-examples-test-suite.cc',
+            ])
+
     headers = bld(features='ns3header')
     headers.module = 'energy'
     headers.source = [

src/flow-monitor/wscript

@@ -19,6 +19,12 @@ def build(bld):
         'test/histogram-test-suite.cc',
         ]
 
+    # Tests encapsulating example programs should be listed here
+    if (bld.env['ENABLE_EXAMPLES']):
+        module_test.source.extend([
+        #   'test/flow-monitor-examples-test-suite.cc',
+            ])
+
     headers = bld(features='ns3header')
     headers.module = 'flow-monitor'
     headers.source = ["model/%s" % s for s in [

src/internet-apps/wscript

@@ -30,6 +30,12 @@ def build(bld):
         'test/dhcp-test.cc',
         ]
 
+    # Tests encapsulating example programs should be listed here
+    if (bld.env['ENABLE_EXAMPLES']):
+        applications_test.source.extend([
+        #   'test/internet-apps-examples-test-suite.cc',
+            ])
+
     headers = bld(features='ns3header')
     headers.module = 'internet-apps'
     headers.source = [

src/internet/wscript

@@ -303,6 +303,12 @@ def build(bld):
         'test/tcp-dctcp-test.cc',
         'test/tcp-syn-connection-failed-test.cc',
         ]
+    # Tests encapsulating example programs should be listed here
+    if (bld.env['ENABLE_EXAMPLES']):
+        internet_test.source.extend([
+        #   'test/internet-examples-test-suite.cc',
+            ])
+
     privateheaders = bld(features='ns3privateheader')
     privateheaders.module = 'internet'
     privateheaders.source = [

src/lr-wpan/wscript

@@ -33,6 +33,12 @@ def build(bld):
         'test/lr-wpan-slotted-csmaca-test.cc',
         ]
 
+    # Tests encapsulating example programs should be listed here
+    if (bld.env['ENABLE_EXAMPLES']):
+        module_test.source.extend([
+        #   'test/lr-wpan-examples-test-suite.cc',
+            ])
+
     headers = bld(features='ns3header')
     headers.module = 'lr-wpan'
     headers.source = [

src/lte/wscript

@@ -197,6 +197,12 @@ def build(bld):
         'test/lte-test-radio-link-failure.cc',
         ]
 
+    # Tests encapsulating example programs should be listed here
+    if (bld.env['ENABLE_EXAMPLES']):
+        module_test.source.extend([
+        #   'test/lte-examples-test-suite.cc',
+            ])
+
     headers = bld(features='ns3header')
     headers.module = 'lte'
     headers.source = [

src/mesh/wscript

@@ -54,6 +54,12 @@ def build(bld):
         'test/flame/regression.cc',
         ]
 
+    # Tests encapsulating example programs should be listed here
+    if (bld.env['ENABLE_EXAMPLES']):
+        obj_test.source.extend([
+        #   'test/mesh-examples-test-suite.cc',
+            ])
+
     headers = bld(features='ns3header')
     headers.module = 'mesh'
     headers.source = [

src/mobility/wscript

@@ -36,6 +36,12 @@ def build(bld):
         'test/box-line-intersection-test.cc',
         ]
 
+    # Tests encapsulating example programs should be listed here
+    if (bld.env['ENABLE_EXAMPLES']):
+        mobility_test.source.extend([
+        #   'test/mobility-examples-test-suite.cc',
+            ])
+
     headers = bld(features='ns3header')
     headers.module = 'mobility'
     headers.source = [

src/netanim/wscript

@@ -11,6 +11,12 @@ def build (bld) :
     module.source = [ 'model/animation-interface.cc', ]
     netanim_test = bld.create_ns3_module_test_library('netanim')
     netanim_test.source = ['test/netanim-test.cc', ]
+    # Tests encapsulating example programs should be listed here
+    if (bld.env['ENABLE_EXAMPLES']):
+        netanim_test.source.extend([
+        #   'test/netanim-examples-test-suite.cc',
+            ])
+
     headers = bld(features='ns3header')
     headers.module = 'netanim'
     headers.source = ['model/animation-interface.h', ]

src/network/wscript

@@ -86,6 +86,12 @@ def build(bld):
         'test/packet-socket-apps-test-suite.cc',
         ]
 
+    # Tests encapsulating example programs should be listed here
+    if (bld.env['ENABLE_EXAMPLES']):
+        network_test.source.extend([
+        #   'test/network-examples-test-suite.cc',
+            ])
+
     headers = bld(features='ns3header')
     headers.module = 'network'
     headers.source = [

src/olsr/wscript

@@ -20,6 +20,12 @@ def build(bld):
         'test/tc-regression-test.cc',
         ]
 
+    # Tests encapsulating example programs should be listed here
+    if (bld.env['ENABLE_EXAMPLES']):
+        module_test.source.extend([
+        #   'test/olsr-examples-test-suite.cc',
+            ])
+
     headers = bld(features='ns3header')
     headers.module = 'olsr'
     headers.source = [

src/openflow/wscript

@@ -160,6 +160,12 @@ def build(bld):
     obj_test.source = [
         ]
 
+    # Tests encapsulating example programs should be listed here
+    if (bld.env['ENABLE_EXAMPLES']):
+        obj_test.source.extend([
+        #   'test/openflow-examples-test-suite.cc',
+            ])
+
     if bld.env['OPENFLOW'] and bld.env['DL'] and bld.env['XML2']:
         obj.use.extend('OPENFLOW DL XML2'.split())
         obj_test.use.extend('OPENFLOW DL XML2'.split())

src/point-to-point/wscript

@@ -20,6 +20,12 @@ def build(bld):
         'test/point-to-point-test.cc',
         ]
 
+    # Tests encapsulating example programs should be listed here
+    if (bld.env['ENABLE_EXAMPLES']):
+        module_test.source.extend([
+        #   'test/point-to-point-examples-test-suite.cc',
+            ])
+
     headers = bld(features='ns3header')
     headers.module = 'point-to-point'
     headers.source = [

src/propagation/wscript

@@ -28,6 +28,12 @@ def build(bld):
         'test/three-gpp-propagation-loss-model-test-suite.cc',
         ]
 
+    # Tests encapsulating example programs should be listed here
+    if (bld.env['ENABLE_EXAMPLES']):
+        module_test.source.extend([
+        #   'test/propagation-examples-test-suite.cc',
+            ])
+
     headers = bld(features='ns3header')
     headers.module = 'propagation'
     headers.source = [

src/sixlowpan/wscript

@@ -14,9 +14,15 @@ def build(bld):
         'test/sixlowpan-hc1-test.cc',
         'test/sixlowpan-iphc-test.cc',
         'test/sixlowpan-fragmentation-test.cc',
-        'test/sixlowpan-examples-test-suite.cc',
         ]
 
+    # This suite runs an example, only include if examples are built
+    # Tests encapsulating example programs should be listed here
+    if (bld.env['ENABLE_EXAMPLES']):
+        module_test.source.extend([
+            'test/sixlowpan-examples-test-suite.cc',
+            ])
+
     headers = bld(features=['ns3header'])
     headers.module = 'sixlowpan'
     headers.source = [
@@ -29,4 +35,4 @@ def build(bld):
     if (bld.env['ENABLE_EXAMPLES']):
         bld.recurse('examples')
 
-    bld.ns3_python_bindings()
+    bld.ns3_python_bindings()

src/spectrum/wscript

@@ -51,6 +51,12 @@ def build(bld):
         'test/three-gpp-channel-test-suite.cc',
         ]
 
+    # Tests encapsulating example programs should be listed here
+    if (bld.env['ENABLE_EXAMPLES']):
+        module_test.source.extend([
+        #   'test/spectrum-examples-test-suite.cc',
+            ])
+
     headers = bld(features='ns3header')
     headers.module = 'spectrum'
     headers.source = [

src/stats/wscript

@@ -45,6 +45,12 @@ def build(bld):
         'test/double-probe-test-suite.cc',
         ]
 
+    # Tests encapsulating example programs should be listed here
+    if (bld.env['ENABLE_EXAMPLES']):
+        module_test.source.extend([
+        #   'test/stats-examples-test-suite.cc',
+            ])
+
     headers = bld(features='ns3header')
     headers.module = 'stats'
     headers.source = [

src/test/wscript

@@ -46,3 +46,10 @@ def build(bld):
         'traced/traced-value-callback-typedef-test-suite.cc',
         ]
 
+    # Tests encapsulating example programs should be listed here
+    if (bld.env['ENABLE_EXAMPLES']):
+        test_test.source.extend([
+        #   'test/test-examples-test-suite.cc',
+            ])
+
+