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




