High-Level Tracing
The preferred method of tracing execution is through the predicate
trace/1.
trace/1 (L)
This predicate takes as argument a term P/N,
where P is a predicate name and N its arity, and sets a ``trace point''
on the corresponding predicate; it can also be given a list of such terms,
in which case a trace point is set on each member of the list.
For example, executing
| ?- trace(pred1/2), trace([pred2/3, pred3/2]).
sets trace points on predicates pred1/2, pred2/3 and pred3/2.
Only those predicates are traced that have trace points set on them.
If all the predicates in a file are to be traced,
it is usually convenient to use the PredList parameter of compile/4
or consult/3, e.g.:
| ?- compile(foo, 'foo.out', [t,v], Preds), load('foo.out'), trace(Preds).
or
| ?- consult(foo, [v], Preds), trace(Preds).
Notice that in the first case, the t compiler option (see Section ![[*]](crossref.png)
)
should be specified in order to turn off certain assembler optimizations
and facilitate tracing.
In the second case, the same effect may be achieved by specifying the t
option to consult.
The trace points set on predicates may be overwritten by loading byte code
files via load/1, and in this case it may be necessary to explicitly
set trace points again on the loaded predicates.
This does not happen with consult:
predicates that were being traced continue to have trace points set
after consulting.
The tracing facilities of SB-Prolog are in many ways very similar to those of
C-Prolog.
However, leashing is not supported, and only those predicates
can be traced which have had trace points
set on them through trace/1.
This makes trace/1 and spy/1 very similar:
essentially, trace amounts to two levels of spy points.
In SB-Prolog, tracing occurs at Call (i.e. entry to a predicate),
successful Exit from a clause, and Failure of the entire call.
The tracing options available during debugging are the following:
- c, NEWLINE: Creep
- Causes the system to single-step to the next port
(i.e. either the entry to a traced predicate called by the executed clause,
or the success or failure exit from that clause).
- a: Abort
-
Causes execution to abort and control to return
to the top level interpreter.
- b: Break
- Calls the evaluable predicate break, thus invoking recursively
a new incarnation of the system interpreter.
The command prompt at break level n is
n: ?-
The user may return to the previous break level by entering the system
end-of-file character (e.g. ctrl-D), or
typing in the atom end_of_file;
or to the top level interpreter by typing in abort.
- f: Fail
- Causes execution to fail,
thus transferring control to the Fail port of the current execution.
- h: Help
- Displays the table of debugging options.
- l: Leap
- Causes the system to resume running the program,
only stopping when a spy-point is reached or the program terminates.
This allows the user to follow the execution at a higher level than
exhaustive tracing.
- n: Nodebug
- Turns off debug mode.
- q: Quasi-skip
- This is like Skip
except that it does not mask out spy points.
- r: Retry (fail)
- Transfers to the Call port of the current goal.
Note, however, that side effects, such as database modifications etc.,
are not undone.
- s: Skip
- Causes tracing to be turned off
for the entire execution of the procedure.
Thus, nothing is seen until control comes back to that procedure,
either at the Success or the Failure port.
Other predicates that are useful in debugging are:
- untrace(Preds)
- untrace/1 (L)
where Preds is a term P/N, where P is a predicate name and N
its arity, or a list of such terms.
Turns off tracing on the specified predicates.
Preds must be instantiated at the time of the call.
- spy(Preds)
- spy/1 (L)
where Preds is a term P/N, where P is a predicate name and N
its arity, or a list of such terms.
Sets spy points on the specified predicates.
Preds must be instantiated at the time of the call.
- nospy(Preds)
- nospy/1 (L)
where Preds is a term P/N, where P is a predicate name and N
its arity, or a list of such terms.
Removes spy points on the specified predicates.
Preds must be instantiated at the time of the call.
- debug
- debug/0 (L)
Turns on debugging mode.
This causes subsequent execution of predicates with trace or spy
points to be traced, and is a no-op if there are no such predicates.
The predicates trace/1 and spy/1 cause debugging mode
to be turned on automatically.
- nodebug
- nodebug/0 (L)
Turns off debugging mode.
This causes trace and spy points to be ignored.
- debugging
- debugging/0 (L)
Displays information about whether debug mode is on or not, and lists
predicates that have trace points or spy points set on them.
- tracepreds(L)
- tracepreds/1 (L)
Binds L to a list of terms P/N where the predicate P of arity N
has a trace point set on it.
- spypreds(L)
- spypreds/1 (L)
Binds L to a list of terms P/N where the predicate P of arity N
has a spy point set on it.
There is one known bug in the package: attempts to set trace points,
via trace/1, on system and library predicates that are used by the trace
package can cause bizarre behaviour.