10 The Debugger Tool

When developing source code, mistakes may prevent your programs from working properly, or even at all. Sometimes you can see what is causing a bug in a program immediately, and correcting it is trivial. For example, you might make a spelling mistake while typing, which you may instantly notice and correct.

More often, however, you need to spend time studying the program and the errors it signalled before you can debug it. This is especially likely when you are developing large or complex programs.

A Debugger tool is provided to make this process easier. This tool is a graphical front-end to the command line debugger which is supplied with your Lisp image. In order to get the best use from the Debugger tool, it is helpful if you are familiar with the command line debugger supplied. See the LispWorks® User Guide and Reference Manual for a description of the command line debugger.

The Debugger tool can be used to inspect programs which behave in unexpected ways, or which contain Common Lisp forms which are syntactically incorrect.

There are two ways that you can invoke the Debugger tool:

• If you evaluate code that signals an error in a Listener, the command line debugger is entered automatically. At this point, choose Debug > Start GUI Debugger or click the button in the Listener toolbar to invoke the Debugger tool.
• If you run code that signals an error from another source (for example, as a result of running a windowed application, or compiling code in a file of source code), by default a Notifier window appears. Click on the Debug button or the Debug Snapshot button in the Notifier window to invoke the Debugger tool.

  For more information about the Notifier window, including the way to bypass it, see 10.10 The Notifier window.

Here is a short example introducing the Debugger tool:

1. Define the following function in the Listener.

   (defun thing (number)
     (/ number 0))
   

   This function which attempts to divide a number given as an argument by zero.

2. Now call this function as follows:

   (thing 12)
   

   The call to thing invokes the command line debugger.

3. Choose Debug > Start GUI Debugger or click the button to invoke the Debugger tool. Notice that the window title contains the name of the process being debugged.
4. For now, click the Abort button in the Debugger toolbar to return to the top level loop in the Listener.

The command line debugger can be entered by signaling an error in interpretation or execution of a Common Lisp form. For each error signaled, a further level of the debugger is entered. Thus, if, while in the debugger, you execute code which signals an error, a lower level of the debugger is entered. The number in the debugger prompt is incremented to reflect this.

Note that you can also invoke the command line debugger by tracing a function and forcing a break on entry to or exit from that function. See the tutorial chapter (2.3 Using the Debugger) for the example code used in Debugger tool and Debugger tool.

10.1 Description of the Debugger

10.2 What the Debugger tool does

10.3 Simple use of the Debugger tool

10.4 The stack in the Debugger

10.5 An example debugging session

10.6 Performing operations on the error condition

10.7 Performing operations on stack frames

10.8 Performing operations on frame variables

10.9 Configuring the debugger tool

10.10 The Notifier window

10.11 Handling of Cocoa Event Loop hanging

10.12 Errors in CAPI display callbacks