build: (works around #14) add Waf option to run without building

CHANGES.html

@@ -86,6 +86,7 @@ us a note on ns-developers mailing list.</p>
 <h2>Changes to build system:</h2>
 <ul>
 <li> The trace sources BackoffTrace and CwTrace were moved from class QosTxop to base class Txop, allowing these values to be traced for DCF operation.  In addition, the trace signature for BackoffTrace was changed from TracedValue to TracedCallback (callback taking one argument instead of two).  Most users of CwTrace for QosTxop configurations will not need to change existing programs, but users of BackoffTrace will need to adjust the callback signature to match.</li>
+<li> Options to run a program through Waf without invoking a project rebuild have been added.  The command './waf --run-no-build <program-name>' parallels the behavior of './waf --run <program-name>' and, likewise, the command './waf --pyrun-no-build' parallels the behavior of './waf --pyrun <program-name>'.</li>
 </ul>
 <h2>Changed behavior:</h2>
 <ul>

doc/manual/source/python.rst

@@ -109,6 +109,16 @@ and the other is to use the --pyrun option to waf:
 
   $ ./waf --pyrun examples/wireless/mixed-wireless.py
 
+As of ns-3.30, a --pyrun-no-build option was added to allow the running of
+a program without invoking a project rebuild.  This option may be useful
+to improve execution time when running the same program repeatedly but with
+different arguments, such as from scripts. It can be used in place of
+--pyrun such as:
+
+.. sourcecode:: bash
+
+  $ ./waf --pyrun-no-build examples/wireless/mixed-wireless.py
+
 To run a python script under the C debugger:
 
 .. sourcecode:: bash

doc/tutorial/source/getting-started.rst

@@ -1136,3 +1136,17 @@ program.
 
 We mention this ``--cwd`` command for completeness; most users will simply
 run Waf from the top-level directory and generate the output data files there.
+
+Running without Building
+++++++++++++++++++++++++
+
+As of the ns-3.30 release, a new Waf option was introduced to allow the
+running of programs while skipping the build step.  This can reduce the time
+to run programs when, for example, running the same program repeatedly
+through a shell script, or when demonstrating program execution. 
+This option, ``--run-no-build``, behaves the same as the ``-run`` option, 
+except that the program and ns-3 libraries will not be rebuilt.
+
+.. sourcecode:: bash
+
+  $ ./waf --run-no-build '<ns3-program> --arg1=value1 --arg2=value2 ...'

wscript

@@ -177,6 +177,10 @@ def options(opt):
                    help=('Run a locally built program; argument can be a program name,'
                          ' or a command starting with the program name.'),
                    type="string", default='', dest='run')
+    opt.add_option('--run-no-build',
+                   help=('Run a locally built program without rebuilding the project; argument can be a program name,'
+                         ' or a command starting with the program name.'),
+                   type="string", default='', dest='run_no_build')
     opt.add_option('--visualize',
                    help=('Modify --run arguments to enable the visualizer'),
                    action="store_true", default=False, dest='visualize')
@@ -190,6 +194,11 @@ def options(opt):
                          ' argument is the path to the python program, optionally followed'
                          ' by command-line options that are passed to the program.'),
                    type="string", default='', dest='pyrun')
+    opt.add_option('--pyrun-no-build',
+                   help=('Run a python program using locally built ns3 python module without rebuilding the project;'
+                         ' argument is the path to the python program, optionally followed'
+                         ' by command-line options that are passed to the program.'),
+                   type="string", default='', dest='pyrun_no_build')
     opt.add_option('--valgrind',
                    help=('Change the default command template to run programs and unit tests with valgrind'),
                    action="store_true", default=False,
@@ -1049,6 +1058,18 @@ def build(bld):
         _doxygen(bld)
         raise SystemExit(0)
 
+    if Options.options.run_no_build:
+        # Check that the requested program name is valid
+        program_name, dummy_program_argv = wutils.get_run_program(Options.options.run_no_build, wutils.get_command_template(bld.env))
+        # Run the program
+        wutils.run_program(Options.options.run_no_build, bld.env, wutils.get_command_template(bld.env), visualize=Options.options.visualize)
+        raise SystemExit(0)
+
+    if Options.options.pyrun_no_build:
+        wutils.run_python_program(Options.options.pyrun_no_build, bld.env,
+                                  visualize=Options.options.visualize)
+        raise SystemExit(0)
+
 def _cleandir(name):
     try:
         shutil.rmtree(name)