2.9 Overview of the Debugger

SWI-Prolog has a traditional commandline debugger. It also provides programmatic access to the debugger. This facility is used to provide a graphical debugger as well as remote debugging in the web interface provided by SWISH.

SWI-Prolog has a 6-port tracer, extending the standard 4-port tracer Byrd, 1980, Clocksin & Melish, 1987 with two additional ports. The standard ports are called call, exit, redo, and fail. The additional unify port allows the user to inspect the result after unification of the head. The additional exception port shows exceptions raised by throw/1 or one of the built-in predicates. See section 4.11.

The tracer is started by the trace/0 command. If the system is in debug mode (see debug/0) the trace is started, after reaching a spy point set using spy/1 or break point set using set_breakpoint/4. The debugger is also started if an error(Formal, Extended) exception is raised that is not caught.

If the native graphics plugin (XPCE) is available, the commands gtrace/0 and gspy/1 activate the graphical debugger while tdebug/0 and tspy/1 allow debugging of arbitrary threads.

The interactive top-level goal trace/0 means ``trace the next query''. The tracer shows the port, displaying the port name, the current depth of the recursion and the goal. The goal is printed using the Prolog predicate write_term/2. The style is defined by the Prolog flag debugger_write_options and can be modified using this flag or using the w, p and d commands of the tracer.

min_numlist([H|T], Min) :-
        min_numlist(T, H, Min).

min_numlist([], Min, Min).
min_numlist([H|T], Min0, Min) :-
        Min1 is min(H, Min0),
        min_numlist(T, Min1, Min).

1 ?- visible(+all), leash(-exit).
true.

2 ?- trace, min_numlist([3, 2], X).
   Call: (7) min_numlist([3, 2], _G0) ? creep
   Unify: (7) min_numlist([3, 2], _G0)
   Call: (8) min_numlist([2], 3, _G0) ? creep
   Unify: (8) min_numlist([2], 3, _G0)
^  Call: (9) _G54 is min(2, 3) ? creep
^  Exit: (9) 2 is min(2, 3)
   Call: (9) min_numlist([], 2, _G0) ? creep
   Unify: (9) min_numlist([], 2, 2)
   Exit: (9) min_numlist([], 2, 2)
   Exit: (8) min_numlist([2], 3, 2)
   Exit: (7) min_numlist([3, 2], 2)
X = 2.

On leashed ports (set with the predicate leash/1, default are call, exit, redo and fail) the user is prompted for an action. All actions are single-character commands which are executed without waiting for a return, unless the command line option --no-tty is active. Tracer options:

Spy (+)

Set a spy point (see spy/1) on the current predicate.

No spy (-)

Remove the spy point (see nospy/1) from the current predicate.

Find (/)

Search for a port. After the `/', the user can enter a line to specify the port to search for. This line consists of a set of letters indicating the port type, followed by an optional term, that should unify with the goal run by the port. If no term is specified it is taken as a variable, searching for any port of the specified type. If an atom is given, any goal whose functor has a name equal to that atom matches. Examples:

/f	Search for any fail port
/fe solve	Search for a fail or exit port of any goal with name solve
/c solve(a, _)	Search for a call to solve/2 whose first argument is a variable or the atom a
/a member(_, _)	Search for any port on member/2. This is equivalent to setting a spy point on member/2.

Repeat find (.)

Repeat the last find command (see `/').

Alternatives (A)

Show all goals that have alternatives.

Context (C)

Toggle `Show Context'. If on, the context module of the goal is displayed between square brackets (see section 6). Default is off.

Listing (L)

List the current predicate with listing/1.

Abort (a)

Abort Prolog execution (see abort/0).

Break (b)

Enter a Prolog break environment (see break/0).

Creep (c)

Continue execution, stop at next port. (Also return, space).

Display (d)

Set the max_depth(Depth) option of debugger_write_options, limiting the depth to which terms are printed. See also the w and p options.

Exit (e)

Terminate Prolog (see halt/0).

Fail (f)

Force failure of the current goal.

Goals (g)

Show the list of parent goals (the execution stack). Note that due to tail recursion optimization a number of parent goals might not exist any more.

Help (h)

Show available options (also `?').

Ignore (i)

Ignore the current goal, pretending it succeeded.

Leap (l)

Continue execution, stop at next spy point.

No debug (n)

Continue execution in `no debug' mode.

Print (p)

Set the Prolog flag debugger_write_options to [quoted(true), portray(true), max_depth(10), priority(699)]. This is the default.

Retry (r)

Undo all actions (except for database and I/O actions) back to the call port of the current goal and resume execution at the call port.

Skip (s)

Continue execution, stop at the next port of this goal (thus skipping all calls to children of this goal).

Up (u)

Continue execution, stop at the next port of the parent goal (thus skipping this goal and all calls to children of this goal). This option is useful to stop tracing a failure driven loop.

Write (w)

Set the Prolog flag debugger_write_options to [quoted(true), attributes(write), priority(699)], bypassing portray/1, etc.

The ideal 4-port model Byrd, 1980 as described in many Prolog books Clocksin & Melish, 1987 is not visible in many Prolog implementations because code optimisation removes part of the choice and exit points. Backtrack points are not shown if either the goal succeeded deterministically or its alternatives were removed using the cut. When running in debug mode (debug/0) choice points are only destroyed when removed by the cut. In debug mode, last call optimisation is switched off.^{12This implies the system can run out of stack in debug mode, while no problems arise when running in non-debug mode.}

Reference information to all predicates available for manipulating the debugger is in section 4.39.