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
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
Contact: pedro.estrela@inesc.pt
www.terraview.org
Programa de apoio cartogrᦩco (SIG) para planeamento agricola, florestal e
ambiental
