This is the LISP DEBUG 0.8 release

1. DIFFERENCES WITH THE 0.6 RELEASE
===================================

1.1. Completely rewrite of the debugger
1.2. Added support for ACL5 and CLISP , the debugger works now with CMU Lisp(cmucl),GNU Lisp(gcl),
     Allegro Lisp (acl5) and CLISP.
1.3. Watch points of variables and expressions are possible
1.4. Timetravelling added.
1.5. More logical behavior of <Step Over>
1.6. Added <Step Next> to step to a choosen location.
1.7  Added <Source> menu  to select a source.
1.8  Replaced function search by more general search in a source.
1.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.
1.10 Possibility to extend the debugger via a special language.




2. 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 , so 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

LISP DEBUG is developped and tested with the following code :
	- GCL-2.2.2.
	- CMUCL 18b.
	- CLISP (version 19980715)
	- ACL version 5
	- TCL 8.0 and Tk 8.0 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.
	- More porting information is available in the manual.


3.Installing.
=============

3.1 Automatic installation.

Before you start :
	- Make sure that TCL/TK version 8.0 is installed.
	- Your LISP system is installed.

Do then the following :
	- Unpack the distribution files in an empty directory,
	  make this directory current and use 'su' to give you 
	  adminstrative rights.
	- To install the 'GCL' version of the debugger , type 'make gcl'.
	- To install the 'CMUCL' version of the debugger , type 'make cmucl'.
	- To install the 'CLISP' version of the debugger , type 'make clisp'.
	- To install the 'ACL' verion of the debugg , type 'make acl'
From then the installation will go on automatic. To test the installation 
start your LISP system and type (debug) ((deb) for ACL) at the lisp prompt. For 
use of the debugger I refer to the usermanual or to (6). 


Note :	- The installation routines search for the lisp installations from /usr , 
	  if lisp is installed somewhere else , please modify 'TOP' in 
	  install-gcl (or install-cmucl,cinstall_clisp,install_acl).
	- The installation routines make some assumption about the startup command
	  of lisp , look at the LISP variable in install_gcl,install_cmucl,install_clisp
	  and install_acl fro this value and modify it if needed.
	- The installation routines make some modifications in your existing lisp system,
	  before dooing this they make a save copy with extension .old if you have 
          to revert to the old system you can use these files or rely on the 
	  deinstallation routines (make deinstall-gcl,make deinstall-cmucl,deinstall-clisp
          or deinstall-acl). The files modified are :
		- GCL 
			- gcl (normally in /usr/local/bin)
		- CMUCL
			- lisp.core (normally in /usr/lib/cmucl)
		- CLISP
			- lispinit.mem (normally in /usr/local/lib/lisp
		- ACL
			- lisp.dxl (normally in /usr/local/acl5)
	- If the debugger is already installed then some files of the 
	  lisp debugger are also saved :
		- GCL
			- saved-debug (normally in /usr/local/lib/gcl-2.2.2/unixport
		- CMUCL
			- dlisp.core in /usr/lib/cmucl
	- The 'interface' program is installed in /usr/local/bin if you want you 
	  can modify INSTALLDIR in the install scripts.
	- The 'interface' program is made by a 'autoconf' makefile. This is the first
	  time I use 'userconf'. I you are a 'autoconf' specialist please look at the
	  configure.in and makefile.in in the cfiles subdirectory and mail me about any
	  inconvenients. 


3.2 Manual installation.

3.2.1 GCL

	- Unpack the distribution files in a empty directory using 'tar -xvzf lisp-debug-0.8.tar.gz'.
	- 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 the installatiodir.
	- 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)
	- 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 'save-debug' file should be copied to a directory like '/usr/local/lib/gcl-2.2.3/unixport'.
	- The debugcode.o to 
	- You should modify the 'gcl' command in '/usr/local/bin' to refer to this file (modify the 
	  'saved-... ' entry after the 'exec' command.


3.2.2 CMUCL
	- Unpack the distribution files in a empty directory using 'tar -xvzf lisp-debug-0.8.tar.gz'.
	- 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" which must replace the 'lisp.core' file of cmucl.
	- The lisp.core file is generally installed in '/usr/lib/cmucl' or '/usr/lib/ncmucl'.

3.2.3 ACL
	- Unpack the distribution files in a empty directory using 'tar -xvzf lisp-debug-0.8.tar.gz'.
	- 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.
	- Start lisp again , and type 
		- (make-package "DEBUGGER")
		- (excl:build-lisp-image "save.dxl" :lisp-files '("debugger.fasl"))
		- (exit)
	- This will generate a file "save.dxl" which must replace the 'lisp.dxl' file of ACL.
	- The lisp.dxl file is generally installed in '/usr/local/acl5' (remark this file is
          renamed if the startup command of lisp is changed).

3.2.3 CLISP
	- Unpack the distribution files in a empty directory using 'tar -xvzf lisp-debug-0.8.tar.gz'.
	- 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.
	- The lispinit.mem file is generally installed in '/usr/local/lib/lisp'.


4. BUGS.
========
	- At moment of the release no 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.
	- My email address is : mmertens@akam.be (if this is not working you can try mmertens@azlan.uk or
				mmertens@azlan.be).


5. FILES.
=========

	- Makefile  		: Makefile to install and compile the debugger.
	- README		: This file
	- debug.lyx		: LYX version of the manual.
	- debug.ps		: Postscript version of the manual.
	- debug.tex		: TeX version of the manual.
	- debug.txt		: ASCI version of the manual.
	- pic1.ps		: Postscript code of the figures.
	- pic2.ps		: Postscript code of the figures.
	- pic3.ps		: Postscript code of the figures.
	- pic4.ps 		: Postscript code of the figures.
	- pic6.ps 		: Postscript code of the figures.
	- pic7.ps               : Postscript code of the figures
	- pic8.ps               : Postscript 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
	- filter		: Shell script filter used during the installation.
	- 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/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.


6. USER GUIDE
=============

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

	- Start your lisp system.
	- 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 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




