Debug Window after an Error

The Debug window displays debugging information when an error (more precisely, any unhandled condition that calls break) occurs in the IDE. Debugging in general is described in debugging.htm. Please look at that document for detailed discussion of the information displayed by the debugger and debugging features. To produce the illustration, the unbound symbol a was entered to the Debug window prompt. Since a had no value, this Restarts dialog was displayed:

Clicking on Abort will cause the error to be unwound. Clicking on Debug changed the display of the Debug window to look like this, with the listener below and the debugging pane above: (click here to see the description of the listener in the Debug window):

The debugging section at the top shows the error message in the text control to the right. (The message also appears in the listener portion but that is in part because that is where the error occurred). Below the toolbar, an outline control shows a stack backtrace (similar but not identical to what is printed in a listener in response to the :zoom command -- see the note The Debug Window after an error and the :zoom top-level command below). The buttons on the toolbar, identified by their tooltips, are as follows. Note that if a button is inappropriate for a situation, it is inactive and its tooltip will not be displayed.

• Show Restarts: display the Restarts dialog. This is a modal dialog. Click Debug to return control to the Debug window.
• Include Hidden Frames/Hide Hidden frames: switch between displaying and hiding hidden frames. See the :hide command for information on hidden frames. Hidden frames are typically internal calls which are not usually the cause of a problem. The tooltip says Include or Hide as the frames are not or are currently shown.
• Include Local Variables / Hide Local Variables: switch between displaying and hiding local variables when opening the frame items for function calls to list the arguments that were passed. See the user option include-local-variables-in-backtraces.
• Continue: if the error signaled is a continuable error (signaled by a call to cerror), this button is active and clicking it allows you to choose a continuation. However, most errors are not continuable (instead, they have restarts which is a generalization of the idea of continuable errors) so this button is usually inactive.
• Return from Frame: Return (as with the command :return) from the selected frame.
• Retry Frame: Restart (as with the command :restart) from the selected frame.
• Pop This Error: clear one break level, as with the command :pop.
• Pop and Retry: pop the error and re-evaluate the form that caused the error, as with the command :prt.
• Abort This Process (icon is a big X): unwind all errors from the stack of this process, as with the command :reset.
• Write a Bug Report (icon is a picture of a bug): writes a file containing the stack backtrace, along with dribble-bug and allegro-ide-options.cl information, which you can include in a bug report to [email protected]. The File | Save and File | Save As commands save dribble-bug and allegro-ide-options.cl along with the backtrace contents when the keyboard focus is in a backtrace pane. See About submitting a bug report from a break in the IDE in cgide.htm.

If not all of the frames (function calls) that are on the stack are initially displayed, additional ones can be displayed by scrolling to the bottom of the backtrace, or by selecting the bottom-most displayed frame. The number of frames that are initially displayed (or added later) is controlled by the user option backtrace-frames-to-show.

If a backtrace should unexpectedly fail to appear when pressing the Debug button on the Restarts dialog, then see backtrace-safe-mode.

Navigating the outline

The outline (which is an instance of an outline widget) can be navigated quickly by pressing the J, K, F, and D keys as alternatives to the down, up, right, and left arrow keys respectively, and the T and B keys for the Home and End keys. This works because the outline widgets in IDE tool dialogs enable their handle-home-key-shortcuts property.

Viewing Function Arguments and Local Variables

There are two ways to see the arguments and local variables of any function call (also called a frame) in the backtrace outline. One way is to "open" the outline item to see the arguments in place in the outline widget. Do this either by clicking the small blue arrow at the left of the outline item, or by selecting it and pressing the right arrow key (as usual with an outline control). It may be most handy to use the up and down arrow keys to peruse the stack, then pressing the right arrow key to see the arguments of a function call, and then pressing the left arrow key to close that item before proceeding to another one (to get the previous list of arguments out of the way).

The other way to view the arguments and local variables is to show them in the inspector. This can be done either by double-clicking the outline item for the desired function call (to the right of the blue arrow), by selecting the "Inspect Arguments and Variables" command from the right-button menu of the outline-item, or by invoking the Tools | Inspect Selected Object command while the desired outline-item is selected.

A combination of these two techniques may be used by opening an outline-item and then double-clicking one of the arguments (or using Tools | Inspect Selected Object) to inspect an individual argument value.

When viewing arguments and local variables directly in the outline control, the icon at the left of each value indicates what type of argument or value it is. Each icon is actually three letters, where "Req" indicates a required argument, "Key" a keyword argument, "Opt" an optional argument, "Res" a rest argument, "Aux" an aux argument, and "Loc" indicates a local variable value. The icons are in different colors to help distinguish them.

Each argument and variable value is printed according to the IDE options dialog-print-level, dialog-print-length, dialog-print-array, and dialog-print-circle, which can be set on the IDE 2 tab of the Options dialog. If the printed representation doesn't fit in the single line that's provided for it, you can see the full text (or much more of it) in a large tooltip window by holding the mouse cursor over the value. Even if the value does fit as printed, a tooltip will still appear if a longer representation will be printed by extending the printer variables *print-level*, *print-length*, and *print-array*. Specifically, the tooltip will use a *print-level* that's one greater than dialog-print-level, a *print-length* that's triple the value of dialog-print-length, and with *print-array* always true. The necessary hovering time for the tooltip to appear is controlled by the CG option tooltip-delay, which can be set on the Common Graphics tab of the Options dialog.

Modifying Arguments and Local Variables

For debugging experiments, it can be useful to change the value of an argument or local variable when execution is paused at a break, and then to continue execution with the modified values. In the IDE's backtrace pane, there are two ways to modify an argument or local variable: one way is to view all of the arguments and variables of a stack frame in the inspector as described above, and then to modify one or more values as usual in the inspector. The other way is to open the outline item for a stack frame, then right-click one of the arguments or variables for that frame and select the Modify Argument or Variable command. A modal dialog will then appear, into which you can enter a Lisp expression that will be evaluated to produce the replacement value.

Once you have modified one or more arguments or variables for a particular frame, you can continue execution in one of two ways. If you modified an argument (rather than a variable), then you can press the Pop and Retry button in the backtrace pane's toolbar to retry the call to that frame's function with the replaced argument(s). Or if execution is paused at a continuable error, then you can modify either an argument or a local variable, and then press the Continue button in the toolbar to continue execution from the actual point of the error. (It's not useful to modify local variables for a non-continuable error.)

Inspecting the Function or Method Object

The "Inspect Function Object" (or "Inspect Method Object") command on the right-button menu of a backtrace outline-item will inspect the function or method itself, rather than its arguments and local variables. Unlike the other commands on this right-button menu, this one is not a shortcut for any IDE menu-bar command, and so this particular action may be invoked only from the right-button menu.

The Debug Window after an error and the :zoom top-level command

Though the IDE implements this specialized graphical interface for browsing a backtrace and proceeding from an error, the corresponding top-level commands such as :zoom are still always available in the listener pane. If both techniques are used simultaneously, note that the two views of the stack are independent, with each one maintaining its own currently selected stack frame, and each one independently either currently showing hidden frames or not. (The IDE display depends on the Include Hidden Frames/Hide Hidden frames button, the :zoom display depends on whether :zoom is called with :all t or :all nil.) In addition, the IDE backtrace outline always shows the whole stack (adding new clumps of frames as you scroll to the bottom), while the :zoom command shows a certain number of frames according to its (sticky) count argument.

Copyright (c) 1998-2019, Franz Inc. Oakland, CA., USA. All rights reserved.
This page has had moderate revisions compared to the 9.0 page.
Created 2019.8.20.