.\" ----------------------- sec6.t -----------------------
.sh 1 "Debugging"
.sh 2 "High Level Tracing"
.pp
The preferred method of tracing execution is through the predicate
\fItrace\fR/1.
.(x b
(L)	 trace/1
.)x
This predicate takes as argument a term \fIP\fR/\fIN\fR, where
\fIP\fR is a predicate name and \fIN\fR 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
.(l
	| ?- trace(pred1/2), trace([pred2/3, pred3/2]).
.)l
sets trace points on predicates \fIpred1\fR/2, \fIpred2\fR/3 and
\fIpred3\fR/2.
Only those predicates are traced that have trace points set on them.
.pp
If all the predicates in a file are to be traced, it is usually convenient to use the
\fIPredList\fR parameter of \fIcompile\fR/4 or \fIconsult\fR/3, e.g.:
.(l
	| ?- compile(foo, 'foo.out', [t,v], Preds), load('foo.out'), trace(Preds).
or
	| ?- consult(foo, [v], Preds), trace(Preds).
.)l
Notice that in the first case, the \fBt\fR compiler option (see Section 8.3)
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
\fBt\fR option to \fIconsult\fR.
.pp
The trace points set on predicates may be overwritten by loading byte code
files via \fIload\fR/1, and in this case it may be necessary to explicitly
set trace points again on the loaded predicates.  This does not happen with
\fIconsult\fR: predicates that were being traced continue to have trace points
set after consulting.
.pp
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 \fItrace\fR/1.  This makes \fItrace\fR/1 and \fIspy\fR/1
very similar: essentially, trace amounts to two levels of spy points.
In SB-Prolog, tracing occurs at \fICall\fR (i.e. entry to a predicate),
successful \fIExit\fR from a clause, and \fIFailure\fR of the entire call.  The tracing options available during debugging are the following:
.ip \fBc\fR,\ \s-2NEWLINE\s+2:\ 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).
.ip \fBa\fR:\ Abort
Causes execution to abort and control to return to the top level interpreter.
.ip \fBb\fR:\ Break
Calls the evaluable predicate \fIbreak\fR, thus invoking recursively
a new incarnation of the system interpreter.  The
command prompt at break level \fIn\fR is
.(l
	\fIn\fR: ?-
.)l
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 \fIend_\^of_\^file\fR; or to the top level interpreter by typing in \fIabort\fR.
.ip \fBf\fR:\ Fail
Causes execution to fail, thus transferring control to the Fail port of the current execution.
.ip \fBh\fR:\ Help
Displays the table of debugging options.
.ip \fBl\fR:\ 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.
.ip \fBn\fR:\ Nodebug
Turns off debug mode.
.ip \fBq\fR:\ Quasi-skip
This is like Skip except that it does not mask out spy points.
.ip \fBr\fR:\ Retry\ (fail)
Transfers to the Call port of the current goal.  Note, however, that side effects, such as
database modifications etc., are not undone.
.ip \fBs\fR:\ 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.
.sp
.lp
Other predicates that are useful in debugging are:
.sp
.ip \fBuntrace\fR(\fIPreds\fR)
.(x b
(L)	 untrace/1
.)x
where Preds is a term \fIP\fR/\fIN\fR, where \fIP\fR is a predicate name and \fIN\fR its arity,
or a list of such terms.  Turns off tracing on the specified predicates.
\fIPreds\fR must be instantiated at the time of the call.
.ip \fBspy\fR(\fIPreds\fR)
.(x b
(L)	 spy/1
.)x
where Preds is a term \fIP\fR/\fIN\fR, where \fIP\fR is a predicate name and \fIN\fR its arity,
or a list of such terms.  Sets spy points on the specified predicates.
\fIPreds\fR must be instantiated at the time of the call.
.ip \fBnospy\fR(\fBPreds\fR)
.(x b
(L)	 nospy/1
.)x
where Preds is a term \fIP\fR/\fIN\fR, where \fIP\fR is a predicate name and \fIN\fR its arity,
or a list of such terms.  Removes spy points on the specified predicates.
\fIPreds\fR must be instantiated at the time of the call.
.ip \fBdebug\fR
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.
.(x b
(L)	 debug/0
.)x
The predicates \fItrace\fR/1 and \fIspy\fR/1 cause debugging mode to be turned on automatically.
.ip \fBnodebug\fR
Turns off debugging mode.  This causes trace and spy points to be ignored.
.(x b
(L)	 nodebug/0
.)x
.ip \fBdebugging\fR
Displays information about whether debug mode is on or not, and lists
predicates that have trace points or spy points set on them.
.(x b
(L)	 debugging/0
.)x
.ip \fBtracepreds\fR(\fIL\fR\|)
Binds \fIL\fR to a list of terms \fIP\fR/\fIN\fR where the predicate
\fIP\fR of arity \fIN\fR has a trace point set on it.
.(x b
(L)	 tracepreds/1
.)x
.ip \fBspypreds\fR(\fIL\fR\|)
Binds \fIL\fR to a list of terms \fIP\fR/\fIN\fR where the predicate
\fIP\fR of arity \fIN\fR has a spy point set on it.
.(x b
(L)	 spypreds/1
.)x
.sp
.pp
There is one known bug in the package: attempts to set trace points, via
\fItrace\fR/1, on system and library predicates that are used by the trace
package can cause bizarre behaviour.
.sh 2 "Low Level Tracing"
.pp
SB-Prolog also provides a facility for low level tracing of execution.  This can
be activated by invoking the simulator with the \-T option, or through the
predicate \fItrace\fR/0.  It causes trace information to be printed out at every
call (including those to system trap handlers).  The volume of such trace information can very become large very
quickly, so this method of tracing is not recommended in general.
.(x b
(L)	 trace/0
.)x
.pp
Low level tracing may be turned off using the predicate \fIuntrace\fR/0.
.(x b
(L)	 untrace/0
.)x
.\" ---------------------- end of section sec6.t ----------------------