This is the LISP DEBUG 0.9 release

1. DIFFERENCES of 0.9 WITH THE 0.8 RELEASE

1.1 Corrected numerous bugs like

Errors with watch,watch exp and eval if exp is not selfevaluating
Misterious hangs during debugging.
Interface not accepting some commands from lisp environment
If you change from source, the set breakpoints are not highlighted anymore
Source of pasted code was not available on 'source' menu.
Problem with 'defstruct' in cmucl, this was caused by macro expanding in non printable characters , solved by adding option debugging macros (default turned off).
Profiling was not highlighting correct code.
Find works now even if the debugger switched from sources.
...
Ps. corrected doesn't mean that I have catched all bugs :(.
Do a correct binding of variables for do,do*... .

1.2. You can change the size of the source,result and command pane. 1.3. Results can be displayed in a separate window. 1.4. Halting is now possible before and after code to be executed. 1.5. If halting after executing code is active , the result of the call

is shown.
1.6. If halting after executing code is active then you can change the

result returned.
1.7. If debugged code has an error during executing ,the debugger is

     automatical entered and the code causing the problem is highlighted. This
     behaviour can be turned of if you wish to debug functions containing 
     ignore-error , handler-case or other error handling. 
     This feature is not available for gcl because it doesn't have 
     handler-case.

1.8. You can select a source out of the loaded sources. 1.9. The manual is now also available in html format. 1.10.The extension language is simplified (removed the ^,$) so

variable definition is much simpler.

2. DIFFERENCES of 0.8 WITH THE 0.6 RELEASE

2.1. Completely rewrite of the debugger 2.2. Added support for ACL5 and CLISP , the debugger works now with CMU Lisp(cmucl),GNU Lisp(gcl),

Allegro Lisp (acl5) and CLISP.
2.3. Watch points of variables and expressions are possible 2.4. Timetravelling added.
2.5. More logical behavior of <Step Over> 2.6. Added <Step Next> to step to a choosen location. 2.7 Added <Source> menu to select a source. 2.8 Replaced function search by more general search in a source. 2.9 Separated GUI from LISP , lisp doesn't have to support TCL/TK anymore.

TCL/TK is still used but now from a C program. 2.10 Possibility to extend the debugger via a special language.

3. What is LISP DEBUG.

LISP DEBUG is a lisp source debugger , designed to work with GCL (GNU COMMON LISP), CMUCL (CMU COMMON LISP),ACL5 (Allegro Common Lisp V5) and CLISP. LISP DEBUG is released using the GNU licence so you are free to use it.

LISP DEBUG has the following functionality :

Graphical interface.
Breakpoints (conditional or not) can be set using point and click in the source.
Watchpoints on variables and expressions can be set using point and click.
Evaluation of expressions during debugging is possible
Debug controls are :
- Step , execute the next expression
- Step Next , execute the next expression at the same level as the previous expression.
- Next , indicate what the next expression is to stop and start executing untill this expressions is reached.
- Continue, continue execution untill finish or the next
Profiling of code is possible.
Highlighting of executing code.
Support for debugging multiple source code.
Debug granullity is the lispform level , much finer then linelevel debugging.
Timetraveling , you can look at the lexical context of already executed steps (compare this with frames).
You can extend the debugger using a special language that is simular to the form definitions in CLTL2. This allows you to add support for your own controlstructures added to lisp.
Designed to be portable to other lisp's or OS's
Halting is possible before and after executing a form
If halted after execution of a form, you have the possibility to change the result of the execution of the form.
If a debugged program encounters a continuable LISP error, the debugger is automatically entered and the problem code is highlighted.

LISP DEBUG is developped and tested with the following code :

GCL-2.3.
CMUCL 18b.
CLISP (must be higher or equal then version 1999-07-22 (July 1999))
ACL version 5
TCL 8.1 and Tk 8.1 or higher.
I'm only able to test LISP DEBUG on my 'linux' system but installing it on other systems should be easy provided that :
- The lisp is CLTL2 compliant
- The lisp can use sockets.
- TCL/TK libraries are available (not needed in the LISP system (with the execption of GCL)).
- Someone has noticed that the GCL version was not working on a SPARC.
More porting information is available in the manual.

4.Installing.

The installation routines are greatly improved in this version.

Better use of the GNU configure command.
No extensive find's anymore.
You have now to choices of installation:
- Overwrite , your existing command to start lisp is modified so that debugging is added to it. There is no easy way to start lisp without debugging support. Because of problems with dumping an image in the free version of ACL no overwrite option is available for ACL
- Add , a extra command is added to start lisp with debugging support. You can now start LISP without debugging support (the old command) and with debugging support (the new command).
A deinstall program is also installed, allowing you to remove debugging from your system (Add or Overwrite).

There is still one big problem with the installation. If you have installed a previous version of LISP DEBUG, the installation will fail in most cases. If you have a previous version of LISP DEBUG either deinstall it or reinstall your LISP system.

4.1 Automatic installation.

Before you start :

Make sure that TCL/TK version 8.1 or higher is installed.
Your LISP system is installed and the command to start lisp is in your PATH.
You have root permissions.

Do then the following :

Unpack the distribution files in an empty directory, make this directory current and use 'su' to give you adminstrative rights.
Type then './configure' , the system will then check your system for lisp installations, TCL/TK installation ... . In case of problems you can search other libraries then the standard ones with the following options for the 'configure' command:
--prefix=PREFIX , (PREFIX is the install directory
for the lisp debugger components and executables , default PREFIX is /usr/local , execuatbles are stored in $PREFIX/bin and some lisp code in $PREFIX/lib/lispdebug. --bindir=BINDIR , (configure searches $BINDIR:$PATH for
executables to start lisp.) --libdir=LIBDIR (You can add some extra dirs to search for
TCL/TK libraries and for LISP installations, configure will try the default installation directories of TCL/TK and the lisp installations).
To install the 'GCL version of the debugger', type:
'make addgcl' to create 'gcldebug' in $PREFIX/bin to start
lisp with debug support. 'make overwritegcl' to modify your 'gcl' command to start
lisp with debug support. In all cases 'deinstall_gcl' is also added to deinstall the debugger.
To install the 'CMUCL' version of the debugger , type:
'make addcmucl' to create 'cmucldebug' in $PREFIX/bin to start
lisp with debug support. 'make overwritecmucl' to modify the 'lisp' command to start
lisp always with debug support. In all cases 'deinstall_cmucl' is also added to deinstall the debugger.
To install the 'CLISP' version of the debugger , type:
'make addclisp' to create 'clispdebugger' in $PREFIX/bin to start
lisp with debug support. 'make overwriteclisp' to modify the clisp command to start
lisp always with debug support.
To install the 'ACL' verion of the debugg , type:
'make addacl' to create 'acldebugger' in $PREFIX/bin to start
lisp with debug support. 'make overwriteacl' to modify the 'lisp' command to start acl
always with debug support.

From then the installation will go on automatic. To test the installation start your LISP system (either by lisp,gcl,clisp or acldebug,cmucldebug, gcldebug,clispdebug depending on your type of install) and type (debug) ((deb) for ACL) at the lisp prompt.For userinstruction of the debugger use the usermanual or look in (6).

4.2 Manual installation.

4.2.1 GCL

Unpack the distribution files in a empty directory using 'tar -xvzf lispdebug-0.9.tgz'.
Use a editor to modify gcl.lisp so that the correct location of 'tkl.o' is used.
Create 'interface' by gooing to cfiles , and typing
- '.configure'
- 'make'
Copy the file 'interface' to /usr/local/bin or any other location in $PATH.
Return to the installation directory (cd ..) and start gcl.
At the lisp prompt type the following :
- (make-package "DEBUGGER"))
- (compile-file "debugger.lisp")
- (compile-file "gcl.lisp")
- (load "debugger.o")
- (DEBUGGER::process-definition-file "lispsintax")
- (bye) This creates debugcode.o.
The file debugcode.o should be placed in /usr/local/lib/lispdebug or any directory pointed to by the environment variable LISPDEBUG.
Start lisp again , and type :
- (use-package "PCL") (if you want support for PCL and this is compiled in)
- (load "debugger.o")
- (gbc)
- (si::save-system "saved-debug")
The 'saved-debug' file should be copied to a directory like '/usr/local/lib/gcl-2.2.3/unixport'.
You can now use 'saved-debug' to start gcl with debug support , look in the 'gcl' batch file if you want to create a 'batch' file to start 'saved-debug'. (You can also modify gcl itself).

4.2.2 CMUCL

Unpack the distribution files in a empty directory using 'tar -xvzf lispdebug-0..tgz'.
Create 'interface' by gooing to cfiles , and typing :
- '.configure'
- 'make'
Copy the file 'interface' to /usr/local/bin or any other location in $PATH.
Start lisp in this directory by typing 'lisp'
At the lisp prompt type the following :
- (make-package "DEBUGGER")
- (compile-file "debugger.lisp")
- (compile-file "cmu.lisp")
- (load "DEBUGGER.x86f")
- (DEBUGGER::process-definition-file "lispsyntax")
- (quit)
The file debugcode.x86f should be placed in /usr/local/lib/lispdebug or any directory pointed to by the environment variable LISPDEBUG.
Start lisp again , and type
- (gc-off)
- (load "debugger.x86f")
- #-gengc (setf lisp::need-to-collect-garbage NIL)
- (gc-on)
- (save-lisp "dlisp.core")
This will generate a file "dlisp.core".
Now either replace the lisp.core in /usr/lib/cmucl by dlisp.core or start lisp with the -core option to point to dlisp.core.

4.2.3 ACL

Unpack the distribution files in a empty directory using 'tar -xvzf lispdebug-0.9.tgz'.
Create 'interface' by gooing to cfiles , and typing :
- '.configure'
- 'make'
Copy the file 'interface' to /usr/local/bin or any other location in PATH.
Start lisp in this directory by typing 'lisp'
At the lisp prompt type the following :
- (make-package "DEBUGGER")
- (compile-file "debugger.lisp")
- (compile-file "acl5.lisp")
- (load "DEBUGGER.fasl")
- (DEBUGGER::process-definition-file "lispsyntax")
- (exit)
The file debugcode.fasl should be placed in /usr/local/lib/lispdebug or any directory pointed to by the environment variable LISPDEBUG.
The installation used to work with a building of a image but this failes in the current free version of ACL , please remove the following lines. # REMOVE THIS - Start lisp again , and type # REMOVE THIS - (make-package "DEBUGGER") # REMOVE THIS - (excl:build-lisp-image "save.dxl" :lisp-files '("debugger.fasl")) # REMOVE THIS - (exit) # REMOVE THIS - This will generate a file "save.dxl" which must replace the # REMOVE THIS 'lisp.dxl' file of ACL or alternatively use the -I flag of lisp # REMOVE THIS to start acl with the new dump. # REMOVE THIS - The lisp.dxl file is generally installed in '/usr/local/acl5' # REMOVE THIS (remark this file is renamed if the startup command of lisp is changed).
Copy the file debugger.fasl to /usr/local/lib/lispdebug and create a script 'acldebug' in /usr/local/bin with the following contents:
/usr/local/acl5/lisp -L /usr/local/lib/lispdebug/debugger.fasl After a chmod a+rwx /usr/local/bin/acldebug you can use acldebug to start ACL with debug support.

4.2.3 CLISP

Unpack the distribution files in a empty directory using 'tar -xvzf lispdebug-0.9.tgz'.
Create 'interface' by gooing to cfiles , and typing :
- '.configure'
- 'make'
Copy the file 'interface' to /usr/local/bin or any other location in $PATH.
Start lisp in this directory by typing 'clisp'
At the lisp prompt type the following :
- (make-package "DEBUGGER")
- (compile-file "debugger.lisp")
- (compile-file "clisp.lisp")
- (load "DEBUGGER.fas")
- (DEBUGGER::process-definition-file "lispsyntax")
- (exit)
The file debugcode.fas should be placed in /usr/local/lib/lispdebug or any directory pointed to by the environment variable LISPDEBUG.
Start lisp again , and type
- (make-package "DEBUGGER")
- (load "debugger.fas")
- (saveinitmem)
- (bye)
This will generate a file "lispinit.mem" which must replace the 'lispinit.mem' file of CLISP alternatively you can use the -M to start clisp with the new memory file.
The lispinit.mem file is generally installed in '/usr/local/lib/lisp'.

5. BUGS.

Display of circular structures causes the debugger to hang.
- If the result is displayed in the resultpane , print-circle should correct the problem , just as it does at the lisp prompt.
- If the result is displayed in a different there is no solution.
This is not really a bug of the lisp debugger but merely a problem caused by the underlying lisp system.
- If you enable compilation of debugged code then you can have problems with cmucl and acl.
  - Compilation in cmucl takes a very long time and consumes a lot of memory. (This seems to be caused by the extra complexity of the debugged sources).
  - acl doesn't handle well macros used in the arguments of a function.
At moment of the release no more known bugs exist , but I'm sure that the moment the product will be used, a lot of bugs will surface.If you use this product and found a bug (maybe even corrected it) send than a note to me with a description of the bug and if possible your solution. I can then try to correct the bug or merge your solution in my code.
If you think of improvements of this product please send them to me.
I can maintain for this moment the debugger only on a LINUX/PC platform , if someone wants to maintain the debugger on other platforms, be free to do this preferrable after contacting me.
ACL in debugmode is always started with 'acldebug' and there is no overwrite install for ACL (this because a problem in building a image in ACL).
My email address is : mmertens@akam.be (if this is not working you can try
marc.mertens@azlan.co.uk).

7. FILES.

Makefile.in : Used by configure to generate a makefile
to create lisp.
configure.in : template file for autoconf
configure : GNU coonfigure command
README : This file
help/debug.lyx : LYX version of the manual.
help/debug.ps : Postscript version of the manual.
help/debug.tex : TeX version of the manual.
help/debug.txt : ASCI version of the manual.
help/debug.html : html version of the manual.
help/pic1.ps : Postscript code of the figures.
help/pic2.ps : Postscript code of the figures.
help/pic3.ps : Postscript code of the figures.
help/pic4.ps : Postscript code of the figures.
help/pic6.ps : Postscript code of the figures.
help/pic7.ps : Postscript code of the figures
help/pic8.ps : Postscript code of the figures
help/pic1.gif : Gif code of the figures.
help/pic2.gif : Gif code of the figures.
help/pic3.gif : Gif code of the figures.
help/pic4.gif : Gif code of the figures.
help/pic6.gif : Gif code of the figures.
help/pic7.gif : Gif code of the figures
help/pic8.gif : Gif code of the figures
debugger.lisp : Lisp code of the debugger.
cmucl.lisp : Interface code for cmucl
gcl.lisp : Interface code for gcl
clisp.lisp : Interface code for clisp
acl5.lisp : Interface code for acl
install-cmucl : Shell script to install the cmucl version of the debugger.
install-gcl : Shell script to install the gcl version of the debugger.
install-acl : Shell script to install the acl version of the debugger
install-clisp : Shell script to install the clisp version of the debugger
tests/testacl5.lisp : Test lisp code for acl
tests/testclisp.lisp : Test lisp code for clisp
tests/testcmu.lisp : Test lisp code for cmucl
tests/testgcl.lisp : Test lisp code for gcl
tests/testdeb.lisp : The mother of test lisp code
tests/testfirst.lisp : Test code about source changes
tests/testscond.lisp : Test code about source changes
tests/testthird.lisp : Test code about source changes
cfiles/Makefile.in : Template makefile for autoconf
cfiles/configure.in : Template configure file for autoconf
cfiles/configure : configure command
cfiles/hash.c : Hash code
cfiles/hash.h : Hash header code
cfiles/interface.c : Interface code
cfiles/tclinvoke.c : Optimal calls of TCL/TK
cfiles/makefile.linux : makefile you can try if configure can't
make a correct Makefile.

8. USER GUIDE

This is short description of the useage of the debugger. For more detail I refer to debug.ps,debug.html,debug.txt or debug.tex a postscript,html,ASCII or TeX version of the usermanual.

Start your lisp system (use either the native command or acldebug, gcldebug,clispdebug,cmucldebug depending on your installation).
At the prompt type (debug) ((deb) on a Allegro system)
A debugger window appears , use this window to load sources and set breakpoints.
IMPORTANT: Type your lisp forms in the lisp system (not in the command pane of the debugger).
If execution reaches a breakpoint , execution halts , the to be executed code next is highlighted in the debugger and you can use Step,Step Over,Next or Continue to control execution.
Stop the debugger via <File><Exit>

Happy lisping.

Marc Mertens
mmertens@akam.be