# Debugging Facilities

No Scheme system would be complete without facilities to assist the programmer in debugging his or her code. &SISC; provides aid for passive debugging (requiring no action on the part of the programmer) and active debugging (requiring code instrumentation to facilitate debugging).

## Passive Debugging

Passive debugging facilities are provided that collect information on an error that occurred at runtime and was not caught by the executing code. The programmer can then inspect the last error, obtain information about the call stack of the error, or even attempt to restart the computation.

> &procedure; `exception` `get-last-exception`

> > Retrieves the last exception that occurred in &SISC;.

One of the most common desires is to obtain a trace of the call stack, to determine what sequence of calls resulted in the error. &SISC; provides procedures for accessing the call stack of any continuation.

> &requires; (import debugging)

> &procedure; `list` `stack-trace` `continuation`

> > Returns the stack trace for `continuation` in form of a list. The format of the list is

> > stack-trace | := | `(`call-frame ...`)`
> > call-frame | := | sisc-expr | `(`sisc-expr overflown `.` stack`)`
> > overflown | := | #t | #f
> > stack | := | `(`stack-entry ...`)`
> > stack-entry | := | sisc-expr | `(`repetitions `.` stack`)`
> > repetitions | := | integer

> > Each element in the list represents one level in the &SISC; interpreter's call stack, starting from the top. The element contains the &SISC; virtual machine expression that would be executed next in that frame, and, if available, a compact representation of a virtual stack created by collecting information on tail calls carried out in that frame.

> > The virtual stack is bounded in size by the value of the see `maxStackTraceDepth` configuration parameter (see config-parameters). If old information was dropped due to the bound being exceeded then the `overflown` flag is set.

> > Each entry in the virtual stack contains either the &SISC; virtual machine expression that was executed, or a sub-stack annotated with a repetition count, indicating that the entries in that sub-stack were repeated several times.

> > &SISC; expressions are annotated with source locations if the `emitAnnotations` parameter is set to `true`. Additional annotations are produced when `emitDebuggingSymbols` is set to `true`. See config-parameters. The annotations can be retrieved using the `annotation` function with the keys `source-file`, `line-number`, `column-number`, `source-kind`, and `proc-name`.

> > Stack trace entries for expressions with a `source-kind` mentioned on `suppressed-stack-trace-source-kinds` are suppressed.

> &procedure; `list` `suppressed-stack-trace-source-kinds` `list`

> > Retrieves or sets the list of source kinds to suppress in stack traces returned by `stack-trace`. This is a dynamic parameter.

> > The default value is `(#f)` which causes all stack trace entries for expressions with no specified source kind to be suppressed.

> > The annotation of expressions with source kinds and other information is controlled by the `source-annotations` parameter.

> &procedure; `alist` `source-annotations` `alist`

> > Retrieves or sets the association list of additional annotations for expressions that are being read. This is a dynamic parameter.

> > All system and core library code is loaded with this parameter set to `()`, resulting in no additional annotations being produced. However, on entry to the REPL, the parameter is set to `((source-kind . user))`. In combination with the default settings for `suppressed-stack-trace-source-kinds` this results in system code being omitted from stack traces.

> &procedure; `print-stack-trace` `continuation`

> > Displays the call stack of the `continuation` in a human-readable form.

The error message, location information and call stack associated with an exception can be displayed in human-readable form using the following procedure.

> &procedure; `print-exception` `exception` `stack-trace?`

> > Displays the error message and location of `exception`. A stack trace is displayed if `stack-trace?` is absent or set to #t. Furthermore the procedure calls itself recursively in order to display similar information for nested exceptions.

In order to obtain the source file location of a call, your Scheme code must have been loaded while &SISC;'s reader had annotations enabled. Annotations are a means of attaching metadata to compiled Scheme code. To allow the reader to attach annotations related to the source file position of the code it reads, enable the emission of annotations with the `emitAnnotations` configuration parameter (see config-parameters).

&SISC; can also produce more detailed stack traces if code was generated with debugging symbols. These are extra annotations generated by the compiler that track function and variable names that would ordinarily be discarded. By including these annotations, the stack trace can display the name of more of the calls involved. To enable the generation of debugging symbols, the `emitDebuggingSymbols` configuration parameter must be set to `true` (see config-parameters).

Finally, when debugging a program for a long period of time, it may be desirable to have stack traces displayed whenever an error occurs, rather than needing to invoke `print-exception` or other functions each time. For this, the `stackTraceOnError` configuratin parameter must be set to `true` (see config-parameters).

## Active Debugging

&requires; (import debugging)

&SISC; provides active debugging aids; procedures and syntax that can be used in source code to assist in tracing the activities of running Scheme code.

### Runtime Tracing

When a function is traced, each call to the function will be displayed to the console with the function's trace identifier and the values of the operands the function is being applied to. Each nested call is indented slightly, so as to illustrate the depth of calls. When the function application returns, the value of the function-call is displayed at the same indentation as the call itself. Once indented to a certain depth, the same indentation is kept for further nesting, but the depth of the call is displayed as an integer preceding the call.

> &syntax; `procedure` `trace-lambda` `trace-name` `formals` `body`

> > When replaced with a trace-lambda, all calls to a lambda defined procedure are traced on the console. `trace-name` is an identifier which will disambiguate the procedure in the trace. `formals` and `body` have identical semantics to `lambda`.

> &syntax; `value` `trace-let` `loop-identifier` `formal-bindings` `body`

> > Replaces a named-let expression in a similar manner to trace-lambda.

> &procedure; `undefined` `trace` `symbol`

> > Begins traces on the procedures named by the symbols given. The procedures must be defined in the top-level environment.

> > If no procedures are given, a message is displayed indicating the names of top-level procedures currently being traced.

> > If a traced procedure is redefined, it will not retain the instrumenting installed by `trace`, until `trace` or `untrace` is called again (with any arguments). At that time, the traced procedures are reinspected and instrumenting reinstalled on redefined procedures.

> &procedure; `undefined` `untrace` `symbol`

> > Stops tracing the top-level procedures named by the symbols given.

> > If no procedures are given, a message is displayed indicating the names of top-level procedures currently being traced.

`trace-lambda` and `trace-let` are useful for debugging anonymous lambdas and named-lets respectively. `trace` and `untrace` ar useful for tracing any top-level bound procedure, including calls to builtin procedures and stored continuations.

Tracing a function installs instrumentation code around the procedure which does not preserve the continuation of a call to that function. Thus, tail calls made in a traced function are no longer tail calls. This may affect the memory usage characteristics of running code.

### Breakpoints

A user may wish to halt execution of a running Scheme program when a given procedure is called. &SISC; provides means to install breakpoints at top-level visible functions without having to redefine the function.

When a breakpoint is set using `set-breakpoint!`, and the function is called, execution will halt, returning to the REPL and displaying an informational message indicating a break, the procedure called, the arguments passed to the breakpointed procedure, and, if possible, the location in a source file of the call. The user may then continue execution using the `continue` procedure.

> &procedure; `undefined` `set-breakpoint!` `symbol`

> > Instruments the top-level procedure named by the given symbol, such that when called, execution will halt and return to the REPL and the name of the breakpointed function and its arguments are displayed.

> &procedure; `undefined` `clear-breakpoint!` `symbol`

> > Removes the instrumentation on the named top-level procedure, if present. Execution will continue normally through occurances of the formally breakpointed procedure.

> &procedure; `does not return` `continue`

> > Continues execution from the most recent break. It is an error to call this procedure if a breakpoint has not been hit, or to call this procedure more than once for a given break.

> &procedure; `continuation` `current-breakpoint-continuation`

> > Returns the continuation of the most recent breakpoint, or #f if execution is not currently interrupted at a breakpoint.

> > The continuation is useful for obtaining stack traces, e.g. with `(print-stack-trace (current-breakpoint-continuation))`.

> &procedure; `list` `current-breakpoint-args`

> > Returns a list containing the current breakpoint's continuation procedure and arguments that will be used when execution is resumed with `continue`, or #f if execution is not currently interrupted at a breakpoint.

> > This procedure is useful for performing deep inspection of the breakpointed procedure and its arguments. The returned values are also handy for constructing modified breakpoint continuations with `set-current-breakpoint-args!`.

> &procedure; `#t/#f` `set-current-breakpoint-args!` `procedure` `value`

> > Sets the current breakpoint's continuation procedure and arguments that will be used when execution is resumed with `continue`. If execution is not currently interrupted at a breakpoint then invoking this procedure has no effect and it returns #f. Otherwise it returns #t.