2.9 Overview of the Debugger

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

The standard ports are called call, exit, redo, fail and unify. The tracer is started by the trace/0 command, when a spy point is reached and the system is in debugging mode (see spy/1 and debug/0) or when an exception is raised.

The interactive toplevel 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 can be modified to include the ignore_ops and/or portray options using the w, p or d command.

1 ?- visible(+all), leash(-exit). Yes 2 ?- trace, min([3, 2], X). Call: ( 3) min([3, 2], G235) ? creep Unify: ( 3) min([3, 2], G235) Call: ( 4) min([2], G244) ? creep Unify: ( 4) min([2], 2) Exit: ( 4) min([2], 2) Call: ( 4) min(3, 2, G235) ? creep Unify: ( 4) min(3, 2, G235) Call: ( 5) 3 < 2 ? creep Fail: ( 5) 3 < 2 ? creep Redo: ( 4) min(3, 2, G235) ? creep Exit: ( 4) min(3, 2, 2) Exit: ( 3) min([3, 2], 2) Yes [trace] 3 ?-

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 -tty is active. Tracer options:

Spy (\Splus)

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

No spy (\Sminus)

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

Find (\Sdiv)

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 (\Sdot)

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 4). 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)

Write goals using ignore_ops option.

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)

Write goals using the portray option (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)

Write goals without using the portray option.

The ideal 4 port model 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, tail recursion optimisation is switched off. (4)