Dear NS-users,
I email to share my experience how to install the tcl-debug on ns-allinone2.29. This is an update of my previous tcl-debug installation manual for the new release 2.29. To install tcl-debug with release 2.28, you may refer to http://mailman.isi.edu/pipermail/ns-users/2005-June/050495.html The previous manual tested only on cygwin. This manual is tested both on the Debian Linux and the cygwin. ------------------------------------------------------------------------ --------------------------------------- Target: Install tcl-debug onto ns-allinone package release 2.29 ------------------------------------------------------------------------ --------------------------------------- As a debugger for Tcl, tcl-debug is recommended by the NS development team, on the official NS website. This document is intended to provide a cookbook manual of "How to install tcl-debug to NS". This version is an update for the new release 2.29, ns-allinone-2.29. This manual is tested both on the Debian Linux (sage) and cygwin. This manual only explains how to install tcl-debug. It is assumed that the (Debian) Linux (or cygwin) and NS are already installed. ------------------------------------------------------------------------ --------------------------------------- Note for release 2.28 ------------------------------------------------------------------------ --------------------------------------- The 1st sloppy manual for release 2.28 is available at http://mailman.isi.edu/pipermail/ns-users/2005-June/050495.html * Typo correction: There is a typo in step 4.6 in the previous manual for release 2.28. $ cp ns.exe ../lib/ The above command should be changed to, $ cp ns.exe ../bin/ Note: The manual for release 2.28 is targeted for cygwin users, assuming Linux users have less trouble on tcl-debug installation. Some commands of cygwin are slightly different from those of Linux. For example, the command for cygwin at step 2 is, $ tar -zxvf tcl-debug.tar.gz while the command for my Debian machine is, $ tar zxvf tcl-debug.tar.gz Nonetheless, the procedure to install tcl-debug on the Linux should be the same. I've been using this manual to install tcl-debug onto the Linux over and over; and, it worked all the time. :-) ------------------------------------------------------------------------ --------------------------------------- Convention used in this manual ------------------------------------------------------------------------ --------------------------------------- - A term NS is equivalent to NS-2. I'll use NS instead of NS-2 in this manual. - I follow the convention in the NS manual to show the NS directory, ~ns. For example, ~ns for release 2.29 is ~/ns-allinone-2.29/ns-2.29. Say, an NS user's account name is ns2userName; then, the user's home directory is /home/ns2userName. Note that the ~ sign is synonymous to the home directory. If NS is installed on the home directory, ~/ns-allinone-2.29/ns-2.29 is equal to /home/ns2userName/ns-allinone-2.29/ns-2.29. - There is slight difference in syntax between Lunux and cygwin. In this manual, the default OS (Operating System) under consideration is the Linux (bash shell). If the command for Linux and cygwin is different, the OS is denoted in front of the dollar sign. For example, Linux: $ tar zxvf tcl-debug.tar.gz cygwin: $ tar -zxvf tcl-debug.tar.gz "( )" is also used to show commands in cygwin. For example, the above two lines are equivalent to the single line below. $ tar zxvf tcl-debug.tar.gz ( or cygwin: $ tar -zxvf tcl-debug.tar.gz ) ------------------------------------------------------------------------ --------------------------------------- Tested system ------------------------------------------------------------------------ --------------------------------------- This information is provided for your reference. - NS version and download: release 2.29 all-in-one package, ns-allinone-2.29.2.tar.gz download at http://www.isi.edu/nsnam/ns/ or http://sourceforge.net/project/showfiles.php?group_id=149743&package_id= 169689&release_id=371538 - tcl-debug version and download tcl-debug version 2.0 download at http://expect.nist.gov/tcl-debug/tcl-debug.tar.gz Note: I think the version of tcl-debug in the official NS website is a typo, as of Jan. 20, 2006 At http://www.isi.edu/nsnam/ns/ns-build.html#pieces, you will see, tcl-debug (optional, available for Tcl debugging help) Download source: version 1.7 <http://expect.nist.gov/tcl-debug/tcl-debug.tar.gz> ; web page: http://expect.nist.gov/tcl-debug/. This version will work with Tcl/Tk 8.0 release. When you actually download the tar file, tcl-debug.tar.gz, and install it, you'll see a directory tcl-debug-2.0, not tcl-debug-1.7. - Linux package and download Debian Linux (sage) download at http://www.debian.org/ - Windows + Linux emulator Windows XP + cygwin The Cygwin DLL release version is 1.5.17-1 download at http://www.cygwin.com <http://www.cygwin.com/> or http://www.cygwin.com/setup.exe ------------------------------------------------------------------------ --------------------------------------- List of the referred links: ------------------------------------------------------------------------ --------------------------------------- http://www.cygwin.com/ http://www.debian.org/ http://www.isi.edu/nsnam/ns/ http://expect.nist.gov/tcl-debug/tcl-debug.tar.gz http://mailman.isi.edu/pipermail/ns-users/ http://mailman.isi.edu/pipermail/ns-users/2005-June/050495.html ------------------------------------------------------------------------ --------------------------------------- How to install tcl-debug ------------------------------------------------------------------------ --------------------------------------- There are 4 basic steps to install tcl-debug: (1) prepare installing tcl-debug, (2) compile tcl-debug and prepare (re)compiling ns, (3) compile ns, (4) verify installation of tcl-debug. Detailed steps are given below. --------------------------------------------------- Step 1. Prepare installing tcl-debug --------------------------------------------------- You will download the compressed file tcl-debug.tar.gz and extract it onto a directory parallel to the NS directory, ~ns. 1.1 Download the tcl-debug from http://expect.nist.gov/tcl-debug/tcl-debug.tar.gz This tar.gz file is a compressed file. 1.2 Move the downloaded tar.gz file to the NS root directory, ~/ns-allinone-2.29, by typing $ mv tcl-debug.tar.gz ~/ns-allinone-2.29 1.3 Change directory to the NS root directory by typing, $ cd ~/ns-allinone-2.29 1.4 Extract the tar.gz file by typing Linux: $ tar xvfz tcl-debug.tar.gz cygwin: $ tar -zxvf tcl-debug.tar.gz Then, you'll see a directory tcl-debug-2.0 under ~/ns-allinone-2.29. This directory contains files and subdirectories. To check the content of this directory, type in $ ls ~/ns-allinone-2.29/tcl-debug-2.0 Make sure the directory tcl-debug-2.0 is PARALLEL to the NS directory, ~ns or ~/ns-allinone-2.29/ns-2.29. If so, proceed to step 2; otherwise, go back to one of the previous steps. Tip: If the above option -zxvf for cygwin doesn't work, you may try cygwin:$ gunzip tcl-debug.tar.gz cygwin:$ tar -xvf tcl-debug.tar If you fail to extract the tar.gz file, you can come back to this step after learning more about how to extract compressed files in Unix/Linux. When you google with keywords "Linux tar" or "Unix tar", you will see more than 100,000 search results. Tip: If you want to delete a directory with files and subdirectories in it, you may type in $ rm -rf directoryName The option -rf means r(recursive) and f(force). ------------------------------------------------------------------------ -------- Step 2. Compile tcl-debug and prepare (re)compiling ns ------------------------------------------------------------------------ -------- Compile the tcl-debug, and move the compiled loadable library, libtcldbg.a, to the NS library directory, ~/ns-allinone-2.29/lib, to prepare (re)compiling ns. 2.1 Configure and compile tcl-debug 2.1.1 Change directory into the tcl-debug directory $ cd ~/ns-allinone-2.29/tcl-debug-2.0 Check if configure and Makefile are there, by typing $ ls configure Makefile 2.1.2 Configure tcl-debug by typing $ ./configure If you see the following error message, two different ways are suggested. ns2userName:~/ns-allinone-2.29/tcl-debug-2.0$ ./configure loading cache ./config.cache checking for Tcl configuration... configure: warning: Can't find Tcl configuration definitions ./configure: line 630: #: No such file or directory A handy way to solve this problem is to use a patch. The patch is available at http://web.umr.edu/~tk424/CpE401_EE401_Spring_2006/etc/tcl-debug-2.0/con figure. You can download the patch, replace the original configure, and then type in "$ ./configure" again. This patch works only for this bug. Alternative approach is to modify the file "configure" manually. One of the many ways is suggested in Appendix A. Appendix A explains how to change your "configure" manually. The outcome of this approach in MY own computers is the downloaded patch of the 1st approach. Note: In either way, don't forget to back up the original file "configure", just in case. 2.1.3 Compile tcl-debug by typing, $ make A loadable library, libtcldbg.a, is created after compilation. This file is the loadable "library for tcl debug". Note that you get a loadable library after compilation, not an executable file. To make sure libtcldbg.a is there, type in $ ls *.a or $ ls ~/ns-allinone-2.29/tcl-debug-2.0/*.a If you see "libtcldbg.a", please proceed to the next step; otherwise, go back to one of the previous steps. 2.1.4 Copy the loadable library to the NS library directory, ~ns/lib or ~/ns-allinone-2.29/ns-2.29/lib $ cp *.a ~/ns-allinone-2.29/ns-2.29/lib Make sure libtcldbg.a is copied properly by typing, $ ls ~/ns-allinone-2.29/ns-2.29/lib/*.a or $ cd ~/ns-allinone-2.29/ns-2.29/lib $ ls If you see "libtcldbg.a", please proceed to step 3; otherwise, go back to one of the previous steps. -------------------------------------- Step 3. Compile the NS -------------------------------------- This step is the most important of all. You will enable tcl-debug in NS, and compile NS. 3.1 Move to the NS directory, ~ns or ~/ns-allinone-2.29/ns-2.29, by typing $ cd ~/ns-allinone-2.29/ns-2.29 3.2 Configure NS with an option to enable tcl-debug in NS 3.2.1 Configure NS $ ./configure --with-tcldebug 3.2.2 Make sure libtcldbg.a is checked. Scroll up and read a line starting from "checking for libtcldbg...". This line is right above a line starting from "checking dmallc...". For example, checking dmallc... not requested with --with-dmalloc If this configuration step is successful, you will see the following line or a line similar to it. This line indicates the loadable library libtcldbg.a is recognized, in the directory tcl-debug-2.0. Checking for libtcldbg... -L/home/ns2userName/ns-allinone-2.29/ns-2.29/ ../tcl-debug-2.0 -ltcldbg If failed, you will see, Checking for libtcldbg... no When this step is failed, go back to one of the previous steps. 3.3 Erase previous compilation record by typing, $ make clean Note: This step is important. 3.4 Compile NS by typing, $ make The compilation may take a while depending on your system. If the compilation is successful, tcl-debug is embedded to the NS executable. If failed, you can come back to this step after fixing the bug. This bug fix may be time-consuming and/or painful. Errors during compilation are out of this manual's scope because it is related to NS installation. 3.5 Check if you can run the new NS executable by typing, $ ~/ns-allinone-2.29/ns-2.29/ns % If you do not see the % prompt, compilation is failed. Go back to one of the previous steps. The "ns" command runs NS. To exit the Tcl shell "%", you may type in, % exit $ Tip: Ctrl+C also exits the Tcl shell %. Note: File name of the NS executable is "ns" for Linux. On the other hand, the file name for cygwin is "ns.exe", not "ns". Nevertheless, the command to execute NS is the same both for Linux and cygwin, which is "ns". 3.6 Back up the original NS executable in directory ns-allinone-2.29/bin, by typing Linux: $ mv ~/ns-allinone-2.29/bin/ns ~/ns-allinone-2.29/bin/ns.backup or Linux: $ cd ~/ns-allinone-2.29/bin/ Linux: $ mv ns ns.backup In cygwin, type in, cygwin: $ mv ~/ns-allinone-2.29/bin/ns.exe ~/ns-allinone-2.29/bin/ns.backup or cygwin: $ cd ~/ns-allinone-2.29/bin/ cygwin: $ mv ns.exe ns.backup 3.7 Copy this NS executable ns to the ns-allinone-2.29/bin directory. 3.7.1 First, make sure that you are in the right directory by typing, $ cd ~/ns-allinone-2.29/ns-2.29 3.7.2 Now, copy the NS executable Linux: $ cp ns ../bin/ cygwin: $ cp ns.exe ../bin/ Note: Unless specified, the NS executable in directory ~ns/bin is run whenever you type in the command ns. This is because the directory ~ns/bin is set as the PATH in the .bashrc configuration file. ----------------------------------------------------- Step 4. Check if the tcl-debug works. ----------------------------------------------------- In step 3, tcl-debug is embedded to the NS executable ns (or ns.exe). Step 4 is the last step of this manual. We will check if tcl-debug works properly in this step. You can skip this step if you are sure that tcl-debug is successfully embedded to the NS executable. We will pick a sample Tcl script, say wireless-test.tcl, and insert a line "debug 1;". A command line "debug 1;" launches tcl-debug when Tcl interpreter meets this line. 4.1 Pick a sample Tcl script in directory ~ns/tcl/ex or ~/ns-allinone-2.29/ns-2.29/tcl/ex, say wireless-test.tcl, and insert a line "debug 1;" to this Tcl script with a text editor. 4.1.1 Make sure you are in directory ~/ns-allinone-2.29/ns-2.29/tcl/ex/ by typing, $ cd ~/ns-allinone-2.29/ns-2.29/tcl/ex/ 4.1.2 Open the Tcl script by typing, $ gedit wireless-test.tcl & Line 213 and 214 of the Tcl script look like this, set ns_ [new Simulator] set chan [new $opt(chan)] Note: gedit is used as the primary text editor in this manual. However, any kind of text editor can be used such as emacs, nedit, and so on. Note: If you do not open the Tcl script in ~/ns-allinone-2.29/ns-2.29/tcl/ex, you may get an error message. 4.1.3 Put in a line "debug 1;" wherever you want to launch tcl-debug. In this manual, we insert this line between line 213 and 214. set ns_ [new Simulator] debug 1; # this line calls the tcl-debug set chan [new $opt(chan)] Note: The # sign is a comment. You can ignore the line after the # sign. 4.2 Run the Tcl script by typing, $ ns wireless-test.tcl If tcl-debug works, you will see a line similar to the following line, 2: lappend auto_path $dbg_library dbg2.0> Press Ctrl+C or type in the exit command to return to the original shell $, dbg2.0> exit $ If you don't see the tcl-debug shell "dbg2.0>", go back to one of the previous steps. Note: Not all errors in this step are because of failure in tcl-debug. Note: If you decided to run a different sample Tcl script, that's also fine. Several sample Tcl scripts need a little bit more caution. Run them in the directory ~/ns-allinone-2.29/ns-2.29/tcl/ex/. Otherwise, you'll see an error message like one below. ns2userName: ~/ns-allinone-2.29/ns-2.29$ ns ./tcl/ex/wireless-test.tcl couldn't read file "../lib/ns-mobilenode.tcl": no such file or directory while executing "source.orig ../lib/ns-mobilenode.tcl" ("uplevel" body line 1) invoked from within "uplevel source.orig [list $fileName]" invoked from within "if [$instance_ is_http_url $fileName] { set buffer [$instance_ read_url $fileName] uplevel eval $buffer } else { uplevel source.orig [list $fileName] ..." (procedure "source" line 8) invoked from within "source ../lib/ns-mobilenode.tcl" (file "./tcl/ex/wireless-test.tcl" line 183) 4.3 Congratulations. Your tcl-debug installation is successful. Your next step is to learn how to "use" tcl-debug Pedro Vale Estrela's website is an invaluable source for this purpose. You may find his website at http://inesc-0.tagus.ist.utl.pt/~pmsrve/ns2/ Have fun with Tcl/OTcl and NS-2. Good luck for your research! T !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! !!!!!!!!!!!!!!!!!!!!!! Friends are angels who lift us to our feet when our wing have trouble remembering how to fly. !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! !!!!!!!!!!!!!!!!!!!!!! ------------------------------------------------------------------------ --------------------------------------- Appendix A. Hacking the bug (error message) in step 2.1.2 ------------------------------------------------------------------------ --------------------------------------- This appendix explains the steps to modify the file configure. I repeat step 2.1.2 for your convenience. 2.1.2 Configure tcl-debug by typing $ ./configure If you see the following error message, two different ways are suggested. ns2userName:~/ns-allinone-2.29/tcl-debug-2.0$ ./configure loading cache ./config.cache checking for Tcl configuration... configure: warning: Can't find Tcl configuration definitions ./configure: line 630: #: No such file or directory A handy way is to download my patch, only for this bug, at http://web.umr.edu/~tk424/CpE401_EE401_Spring_2006/etc/tcl-debug-2.0/con figure, replace the original configure, and then type in $ ./configure again. It should work now. Alternative way is to modify the file configure manually. One of the many ways to do it is suggested in Appendix A. Appendix A explains how to change your "configure" manually. The outcome of this approach in MY own computers is the downloaded file at the 1st approach. Note: In either way, don't forget to back up the original file, configure, just in case. Bug fix: 1. Open the file "configure" using a text editor. To use "gedit", one of text editors, type in $ gedit configure & 2. The file "configure" should look like below, around line 630 and line 1360. The line numbers are shown on the left for your convenience. line625 echo "$ac_t""found $TCLCONFIG" 1>&6 line626 fi line627 fi line628 line629 line630 . $TCLCONFIG ... line1359 fi line1360 # see if one is installed line1361 if test x"${ac_cv_c_tclh}" = x ; then 3. Insert the paths as follows: line628 # *** line629 TCLCONFIG="../tcl8.4.11/unix/tclConfig.sh" line630 . $TCLCONFIG ... line1360 # *** line1361 ac_cv_c_tclh="../tcl8.4.11/generic" line1362 # see if one is installed In line 628 and line 1360, # *** is just a comment used to find the edited lines easily. 4. Type in the command "$ .configure" again. If it works, you will see messages like ones below. If not, go back to one of the steps and correct mistakes. If you can not solve the problem, there might be other bugs. Ask questions to the NS mailing list. ns2userName @:~/ns-allinone-2.29/tcl-debug-2.0$ ./configure loading cache ./config.cache checking for Tcl configuration... configure: warning: Can't find Tcl configuration definitions checking Tcl build library... -L/home/ns2root/ns-allinone-2.29/tcl8.4.11/unix -ltcl8.4 -ldl -lieee -lm checking for Tcl_CreateCommand... yes checking if Tcl library build specification is valid... yes checking for gcc... gcc -pipe checking whether the C compiler (gcc -pipe ) works... yes checking whether the C compiler (gcc -pipe ) is a cross-compiler... no checking whether we are using GNU C... yes checking whether gcc -pipe accepts -g... yes checking whether the compiler (gcc -pipe) actually works... yes checking for a BSD compatible install... /usr/bin/install -c checking for ranlib... ranlib checking how to run the C preprocessor... gcc -pipe -E checking if running LynxOS... no checking for Tcl private headers... found in ../tcl8.4.11/generic checking if we are running Linux... yes checking for strchr... yes checking for stdlib.h... yes checking type of library to build... unshared updating cache ./config.cache creating ./config.status creating Makefile creating pkgIndex creating tcldbgcf.h ns2userName @:~/ns-allinone-2.29/tcl-debug-2.0$ 5. If tcl-debug is successfully configured, you can proceed. Move forward to step 2.1.3.
