Pedro Vale Estrela - NS2 OTCL + TCL-DEBUG + MASH + TKCON Debugging Page

This guide presents step-by step instructions on enabling the various otcl and tcl debugging aids that I've developed over the last few years. I present the guide for ns2-2.28; it should be easily applicable to previous NS2 and TCLTK versions.

Files and Patches (contains the patches mentioned in these pages)


NOTE1: It MAY be required to RECOMPILE and/or RECONFIGURE NS2 appropriately at each step of this guide (use “make ns”)
NOTE2: The mentioned files are available at the files directory. I've also made a compressed file that has everything you'll need on this guide ns2_debugging_files.tar.gz.
NOTE3: This guide was made against a fresh ns-2.28 image, on debian linux. Other OS or NS versions may require additional steps. You're welcome to send any comments for me to update this page (tips for latest 2.29.3)

NOTE4 – UPDATES: a) after installing this modifications, you may need to invoke “make ns” instead of “make”


Step 1: install ns-allinone-2.28

The first step is to correctly install ns-2.28-allinone, which is explained in the NS2 site. for this, you should simply decompress ns-allinone-2.28.tar.gz, and run the "install" script. If you haven't changed anything, this script will make you a fully working ns2.
In particular you MUST change your TCL_LIBRARY and LD_LIBRARY_PATH environment variables, and you SHOULD change the path as explained in the ./install script.
after it, CONFIRM that everything is OK by running this simple example script, taken from the tcl/ex directory. (pmsrve_test_exmaple_step1.tcl) (we'll be using it as a base for the next steps).

Check carefully the tests that I present in each figures for each step:
Step 1 Image

Step 2: add TK support:

The second step is to enable TK functionality in NS2. For this, apply the provided patch to common/tkappinit.c, and

(note: as of ns2.31, is necessary to re-include a X11 dependency, using the provided patch. This requires the GNU autoconf utilities)

ns/common/> cat tkAppInit.cc_step2.patch | patch
ns/> cat Makefile.in_step2.patch | patch
ns/> cat configure.in_step2.patch | patch

Then backup the current “configure” script, re-run autoconf, reconfigure NS2 and recompile.
ns/> mv configure configure.old
ns/> autoconf
ns/> ./configure
ns/> make

UPDATE2: You must also add an environment variable named "TK_LIBRARY_PATH" with the complete path to the TK library. This variable is analogous to the TCL_LIBRARY_PATH that you'll have in you .bashrc init script, (mentioned in the NS install script)

Thus, add the following to the .bashrc script located in your home directory:
TK_LIBRARY_PATH=" your path to /tk<version>/library"

Then test the "nstk" interactively (eg, without arguments). Observe as it appears a new TK window; on the other hand, if you provide a script argument, it runs non-interactively, as before.

Step 2 Image

Step 3: Add TKCON graphic console

Now that we have graphic support, lets use a graphic console that has history, command completion, mouse support etc., called "tkcon". Download it here.

Then put the tkcon.tcl file somewhere. I suggest your home directory (eg ~).
Then create a ".ns.tcl" file in your home directory to identify the location of the tkcon.tcl file.
Either insert it the following code, or use the provided .ns.tcl file.
(NOTE: the .ns.tcl is a tcl file that is read by NS during startup, for reading its configuration)

if { [info exists tk_version] } {
if { [info exists env(DISPLAY)] } {
source ~/tkcon.tcl
set ::tkcon::OPT(exec) {}
tkcon show

Now, start "nstk" INTERACTIVELY (eg, without arguments); now confirm that the console appears as shown in the figure.
Then, inside it, run the test script (source pmsrve_test_exmaple_step3.tcl).

Note that now I've removed the exit(1) from the finish proc; otherwise the program would end and you would not be able to see the results working. Also note the command completion, in this case for both the "source" command and the same of the script to test.

Step 3 Image

Step 4: Add MASH_inspect object inspector

We're now going to add the MASH's object inspector, which requires TK support that is already working by now.

a) add MASH_inspect.tcl do tcl/lib;

b) modify ns-lib.tcl to source it automatically; use the provided patch to it

ns/tcl/lib> patch < ns-lib.tcl.add_MASH.patch

c) recompile NS:
ns/> make

check the figure:
a) running the regular non-tk NS warns if you try to create object inspector;
b) run the example script (step 4) with "nstk". Confirm that I've disabled the simulation start (ns run) to create only the scenario.

Check that it creates a MashInspector object at the end of the scenario creation.
Check that its possible to see all used classes, the instantiations, the instprocs (including the code, as showed) and the internal variables!

(Note: To do the same thing at the middle of simulation, you must use the debugger. More of that on the following steps)
Step 4 Image

Step 5: Add tcl-debug-2.0-pmsrve module

NOTE: check this post for more info if you are using Windows (CygWin) tcl-debug-2.0 installation onto Cygwin (thanks for Tae-hyung Kim)

NEW: thanks to Tae-hyung Kim, a complete detailed step-by-step installation manual of tcl-debug is available here (local mirror)

We're now going to add the tcl-debug-2.0-pmsrve that already contains alterations made by me to the debugger. Simply decompress the file parallel to the ns2 directory, and configure / compile it (at the tcl-debug directory).

tcl-debug> ./configure --with-tcl=../tcl8.4.11/unix/
tcl-debug> make

THEN, reconfigure ns2 with tcl-debug support and C++ debug support (at the NS2 directory),
ns/> ./configure --enable-debug --with-tcldebug=../tcl-debug-2.0-pmsrve

then "make clean; make" (IMPORTANT)

THEN test it:
a) regular ns:
ns/> ns ; "insert debug 1"
b) nstk: "insert debug 1"
(check that the debugger when active freezes the TK windows. This effectively stops any mash object inspectors that you might be working on - more on that later)

Update: tcl-debug-2.0 has a minor bug, which is documented and corrected in this post

Step 5 Image

Step 6: Add special Input / Output support to the debugger

we are now on the final stage.; we'll add specialized IO to the debugger, to make it work inside TKCON, and to make MASH work inside the debugger for this:

- add utils_ns.c / .h to the ns2 dir,
ns/> cp utils_ns.* .

- patch to include it (trivial patch)
ns/> patch < Makefile.in_step6.patch

- now patch to initialize the special support.
ns/common/> patch < tkAppinit.cc_step6.patch

- now make tcl-debug-2,0-pmsrve/tcldbg.h available to NS2. Simply make a symbolic link to ../include, eg:
ns-allinone/include/> ln -s ../tcl-debug-2.0-pmsrve/tcldbg.h .

- reconfigure and recompile
ns/> make

now start nstk. do "debug 1" and check how input is taken from tkcon!
also, now you can stop the NS2 simulation wherever you want, with "debug 1", create an object inspector at that point, and inspect the internal otcl variables!!!
use the example script (pmsrve_..._step6.tcl) and in the figure!

Step 6 Image

Step 7: Explore the new debugging possibilities!

You now should fully explore the possibilities of inspecting at run time the otcl objects. Using these, you can have an environment similar to the image presented below
the most important points to note are:
- inside a "debug 1", I've modified the "c" command to proceed into the next "debug 1" breakpoint
- inside a "debug 1", the "C" command ignores further breakpoints - i've developed a ns2_shared_procs.tcl file with some important debug functions that are otcl-aware, for tracing. check it here, in the otcl debugging topic
- you should combine these methods with C++ debugging, also explained here

Check the files, patches, etc in this directory

Go back to my NS2 page

Contact: Programa de apoio cartogrᦩco (SIG) para planeamento agricola, florestal e ambiental