12. Debugging

Larceny's debugging functionality is implemented in Scheme, using some of Larceny's extensions for catching exceptions and inspecting the continuation structure.

12.1. Entering the debugger

When Larceny detects an error or a keyboard interrupt, or when it hits a breakpoint, it signals the condition by printing a message on the console. Larceny then enters the debugger, which signals its presence with a short banner and the debugger prompt:

Entering debugger; type "?" for help.
debug>

You can also re-enter the debugger by evaluating (debug).

12.2. Debugger commands

The debugger is still in an immature state. The following commands are available (commands can be typed in upper or lower case):

B Print backtrace of continuation.

C Print source code of procedure, if available.

D Move down to previous (earlier) activation record.

E n expr Expr is evaluated in the current interaction environment and must evaluate to a procedure. It is passed the contents of slot n from the current activation record, and the result, if not unspecified, is printed.

E (n1 … nk) expr Expr is evaluated in the current interaction environment and must evaluate to a procedure. It is passed the contents of slots n1 through nk from the current activation record, and the result, if not unspecified, is printed.

I n Inspect the procedure in slot n of the current activation record.

I @_ Inspect the active procedure.

Q Quit the debugger and abort the computation.

R Return from the debugger and continue the computation.

S Summarize the contents of the current activation record.

U Up to the next (later) activation record.

X Examine the contents of the current activation record.

The B, D, and U commands can be prefixed with a count, for example, 5 U moves up five activation records, and 10 B displays the next 10 activation records. The default for B is to display all the activations; the default count for D and U is 1.

12.3. Breakpoints

You can set breakpoints either in program text with the break primitive or interactively at the start of a procedure with the break-entry procedure. When Larceny reaches a breakpoint during execution, the program is suspended and the debugger is entered to allow you to inspect the program.

Procedure larceny-break

(larceny-break )

Invokes the breakpoint handler.

Procedure break-entry

(break-entry procedure)

Set a breakpoint at the start of the procedure.

Procedure unbreak

(unbreak procedure …)

(unbreak )

In the first form, remove any breakpoint set by break-entry at the start of the procedure_s. In the second form, remove all breakpoints set by _break-entry.

12.4. Tracing

Procedure trace-entry

(trace-entry procedure)

Set a trace point on entry to the procedure, removing any other trace points on the procedure. When the procedure is entered, information about the call is printed on the console: the name of the procedure and the actual arguments.

Procedure trace-exit

(trace-exit procedure)

Set a trace point on exit from the procedure, removing any other trace points on the procedure. When the procedure returns, information about the return is printed on the console: the name of the procedure and the returned values.

Note that trace-exit destroys the tail recursion properties of the instrumented procedure. Where the procedure would normally "return" by tail-calling another procedure, the instrumented procedure will call the other procedure by a non-tail call and then return, at which point the procedure name and return values will be printed. Thus use of trace-exit may destroy the space properties of the program.

Procedure trace

(trace procedure)

Set trace points on procedure both at entry and exit.

Procedure untrace

(untrace procedure …)

(untrace )

The first form removes any trace points from the specified procedures. The second form removes all untrace points.

12.5. Other functionality

Parameter break-handler

The value of break-handler is a procedure that is called when a breakpoint or tracepoint is encountered. The procedure takes two arguments: the procedure in which the breakpoint was set, and the byte offset within the procedure's code vector of the breakpoint.