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)
Contact: pedro.estrela@inesc.pt
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, Makefile.in and configure.in
(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"
export TK_LIBRARY_PATH
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 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 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 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 Makefile.in to include it (trivial patch)
ns/> patch < Makefile.in_step6.patch
- now patch tkAppinit.cc 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
Contact: pedro.estrela@inesc.pt
www.terraview.org
Programa de apoio cartogrᦩco (SIG) para
planeamento agricola, florestal e ambiental
