Pedro Vale Estrela - NS2 Debugging Page

Pedro Vale Estrela - NS2 Debugging Page

This page contains information regarding my NS2 Simulator experiences, on the topic of C++ and oTcl debugging.

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

Contact: pedro.estrela@inesc.pt

---

Index

Prologue. 1

C++ debugging: 2

C++ that calls TCL code: 2

TCL that calls C++ code: 2

TCL debugging - "Basic" 2

TCL debugging - "Advanced" 3

Object TCL debugging. 3

oTCL object inspector: 4

TKcon visual shell environment: 4

---

Prologue

During my NS2 experiences, I have made or modify several tools for aiding me in oTCL and C++ debugging: TCL debugger / the MASH object inspector / the TKcon visual shell environment / TK support inside NS2 / TraceGraph Program usage. As an example, check a screenshot of my modified NS2 simulator with the above mentioned facilities here, or at the end of this page.

Starting from my modified NS2 tree, based on ns-2.26, I've cleaned up some of my debug files, ready to be usable by the NS2 community. The ns2_shared_procs.tcl file contains several debug features for TCL, oTCL, NAM, NS2, Tracegraph etc. This file should be used in the tcl/lib directory, and sourced using the "source" command. The "utils_ns.*" files contains several debug features for C++, especially for the use of functions that call oTCL. This file should be placed in the root directory, and compiled/linked by including it in the NS2 makefile.

Please note that these are only fragments of my full ns2 working tree, although i'll do my best efforts to help everyone using these code; in particular, the dprintf() function calls the "my_Dbg_OutputProc()" function, which is absent; if needed, replace with a simple printf() call.

This FAQ covers some issues concerning NS2 debugging. Check answers 3 and 17: Dazhi Chen

C++ debuging:

Check these links for C++ debuging. Of these, I use almost every day the DDD debugger, and I've had previously very good experience with the valgind memory checker.

DDD tutorial (for C++ debugging)
Valgrind (Runs any program and checks for unitialized pointers, and other errors. VERY RECOMMENDED
Valgrind and Purify Debugging Tips

Dmalloc (Replacement for Malloc with consistence checks)
ccured (adds run-time checks to prevent C memory violations),
mpatrol

C++ that calls TCL code:

Use my utils_ns.cc file; it contains functions that call TCL, with argument trace and result checking.
Also contains dprintf, a debug printf that outputs to the TKcon graphic shell (more about this below)

TCL that calls C++ code:

using DDD, put a breakpoint in the "command()" function of the called C++ object. Then check the strncmp for the specific TCL command requested.

TCL debugging - "Basic"

For start, get the tcl-debug package. The original debugger is here TCL debugger v1.9.
I've found somewhere in the Internet the latest version of the tcl-debug package - the 2.0 version. My local mirror is Here.
Then install as it is explained here, and mentioned in the NS2 documentation.
Check windows specific details is this post tcl-debug-2.0 instalation onto Cygwin (windows) (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)

For installation, one should do these steps:

1. in the directory of tcl-debug:

a) ./configure --with-tcl=<path>

b) make clean

c) make

2. in the directory of ns-2.29

a) make clean

b) ./configure --enable-debug --with-tcl=<tcl path> --with-tk=<tk path> --with-tcldebug=<tcl-debug path> c)make

This TCL debugger enables to set specific breakpoints in the TCL code, via "debug 1" instructions. When you do that, the TCL script will be halted at this location, and you can check values of variables etc. Then you can either resume execution, or execute step-by-step TCL instructions (unfortunately, this is a very confusing debugging method, due to the nature of TCL code)

IMPORTANT NOTE: It should be noted that this debugger is has NOT "native" object oriented capabilities, but is essential to inspect variables at run-time. See below for oTcl specific facilities

Update: the step 5 of the “advanced” guide (click here) has similar information on how to install my customized version of the debugger.

TCL debugging - "Advanced"

I've modified the debugger in the following ways:
- Added "c" command that continues up to the following breakpoint (normal behaviour was different)
- Added "C" command that continues up to the end of script, ignoring any further breakpoints
- added capability to redirect input and output to the TKCon window (previously, and input and output was done in a regular text shell, even using the TKCon window shell)
- added History capability (up/down keys), merged in the tkcon shell (more about this below)

These methods are now explained in this guide here

Object TCL debugging

As far as I know, there is simply NO otcl debugger available. All the debuggers that I've tried were for regular TCL only.
On the other hand, there is a debugger / IDE (XoTCLIDE) but concerns Xotcl only. This XoTCL extension, altough derived from MIT's oTcl that NS2 uses, is not compatible with it anymore.

Thus, I've made a series of helper functions that should be called inside the TCL debugger (eg, "debug 1").
Check ns2_shared_procs.tcl , especially these functions:

dputs	shows current running instproc, object, class, instance, etc, and a user defined message
dputsl	long version of the above, also dumps arguments of current instproc
show	show the code (arguments + body) of current instproc
v	shows all accessible vars of the current class
W	shows where we are in otcl
p	shows all accessible procs of the current class

oTCL object inspector:

The MASH object inspector is the only full tool that I'm aware of that has 100% otcl capabilities.
Its utilisation is pretty much straight ford: it shows all available classes, its heritage, the existing instprocs (of the classes and above), and the available instances. Choosing an instance, we get the opportunity to inspect the member variables (instvars).

Its utilisation is pretty much straight ford, just question of sourcing the file and creating a MashInspector object. HOWEVER, it requires TK window capabilities, which is a facility that once existed in NS2, but is not maintained anymore.

The NS2 source code tree uses the tclAppInit.cc for shell only utilization, and the tkAppInit.cc for TK window based utilization (similar to the distinction between tclsh and wish). However, the later is currently outdated in the NS2 code. For this, I've heavily modified tclappinnit.cc to provide both shell and window capabilities, necessary for mash inspector, necessary for TKcon graphic console, and to redirect input / output of the debugger into the console.

You can check below a live screenshot of what its capabilities in N2.
These methods are now explained in this guide here

TKcon visual shell environment:

The TKcon visual shell environment is a very valuable tool that aids debugging by offering a graphic console with line-editing capabilities, which is essential for interactively debugging a script.
However, like the mash object inspector, it requires TK window facilities to work. Thus, it is subject to the same comments as above. You can check below a live screenshot of what its capabilities in N2.

These methods are now explained in this guide here, and a tutorial of how to find a example bug, using these tools, is here

---

Check the files, patches, etc in this directory

Go back to my NS2 page

Contact: pedro.estrela@inesc.pt

www.terraview.org Programa de apoio cartogrᦩco (SIG) para planeamento agricola, florestal e ambiental