4.39 Debugging and Tracing Programs

This section is a reference to the debugger interaction predicates. A more use-oriented overview of the debugger is in section 2.9.

If you have installed XPCE, you can use the graphical front-end of the tracer. This front-end is installed using the predicate guitracer/0.

trace

Start the tracer. trace/0 itself cannot be seen in the tracer. Note that the Prolog top level treats trace/0 special; it means `trace the next goal'.

tracing

True if the tracer is currently switched on. tracing/0 itself cannot be seen in the tracer.

notrace

Stop the tracer. notrace/0 itself cannot be seen in the tracer.

guitracer

Installs hooks (see prolog_trace_interception/4) into the system that redirect tracing information to a GUI front-end providing structured access to variable bindings, graphical overview of the stack and highlighting of relevant source code.

noguitracer

Revert back to the textual tracer.

trace(+Pred)

Equivalent to trace(Pred, +all).

trace(+Pred, +Ports)

Put a trace point on all predicates satisfying the predicate specification Pred. Ports is a list of port names (call, redo, exit, fail). The atom all refers to all ports. If the port is preceded by a - sign, the trace point is cleared for the port. If it is preceded by a +, the trace point is set.

The predicate trace/2 activates debug mode (see debug/0). Each time a port (of the 4-port model) is passed that has a trace point set, the goal is printed as with trace/0. Unlike trace/0, however, the execution is continued without asking for further information. Examples:

?- trace(hello).	Trace all ports of hello with any arity in any module.
?- trace(foo/2, +fail).	Trace failures of foo/2 in any module.
?- trace(bar/1, -all).	Stop tracing bar/1.

The predicate debugging/0 shows all currently defined trace points.

notrace(:Goal)

Call Goal, but suspend the debugger while Goal is executing. The current implementation cuts the choice points of Goal after successful completion. See once/1. Later implementations may have the same semantics as call/1.

debug

Start debugger. In debug mode, Prolog stops at spy and trace points, disables last-call optimisation and aggressive destruction of choice points to make debugging information accessible. Implemented by the Prolog flag debug.

Note that the min_free parameter of all stacks is enlarged to 8 K cells if debugging is switched off in order to avoid excessive GC. GC complicates tracing because it renames the _G<NNN> variables and replaces unreachable variables with the atom <garbage_collected>. Calling nodebug/0 does not reset the initial free-margin because several parts of the top level and debugger disable debugging of system code regions. See also set_prolog_stack/2.

nodebug

Stop debugger. Implemented by the Prolog flag debug. See also debug/0.

debugging

Print debug status and spy points on current output stream. See also the Prolog flag debug.

spy(+Pred)

Put a spy point on all predicates meeting the predicate specification Pred. See section 4.5.

nospy(+Pred)

Remove spy point from all predicates meeting the predicate specification Pred.

nospyall

Remove all spy points from the entire program.

leash(?Ports)

Set/query leashing (ports which allow for user interaction). Ports is one of +Name, -Name, ?Name or a list of these. +Name enables leashing on that port, -Name disables it and ?Name succeeds or fails according to the current setting. Recognised ports are call, redo, exit, fail and unify. The special shorthand all refers to all ports, full refers to all ports except for the unify port (default). half refers to the call, redo and fail port.

visible(+Ports)

Set the ports shown by the debugger. See leash/1 for a description of the Ports specification. Default is full.

unknown(-Old, +New)

Edinburgh-Prolog compatibility predicate, interfacing to the ISO Prolog flag unknown. Values are trace (meaning error) and fail. If the unknown flag is set to warning, unknown/2 reports the value as trace.

style_check(+Spec)

Modify/query style checking options. Spec is one of the terms below or a list of these.

• +Style enables a style check
• -Style disables a style check
• ?(Style) queries a style check (note the brackets). If Style is unbound, all active style check options are returned on backtracking.

Loading a file using load_files/2 or one of its derived predicates reset the style checking options to their value before loading the file, scoping the option to the remainder of the file and all files loaded after changing the style checking.

singleton(true)

The predicate read_clause/3 (used by the compiler to read source code) warns on variables appearing only once in a term (clause) which have a name not starting with an underscore. See section 2.16.1.9 for details on variable handling and warnings.

no_effect(true)

This warning is generated by the compiler for BIPs (built-in predicates) that are inlined by the compiler and for which the compiler can prove that they are meaningless. An example is using ==/2 against a not-yet-initialised variable as illustrated in the example below. This comparison is always false.

always_false(X) :-
        X == Y,
        write(Y).

var_branches(false)

Verifies that if a variable is introduced in a branch and used after the branch, it is introduced in all branches. This code aims at bugs following the skeleton below, where p(Next) may be called with Next unbound.

p(Arg) :-
        (  Cond
        -> Next = value1
        ;  true
        ),
        p(Next).

If a variable V is intended to be left unbound, one can use V=_. This construct is removed by the compiler and thus has no implications for the performance of your program.

This check was suggested together with semantic singleton checking. The SWI-Prolog libraries contain about a hundred clauses that are triggered by this style check. Unlike semantic singleton analysis, only a tiny fraction of these clauses proofed faulty. In most cases, the branches failing to bind the variable fail or raise an exception or the caller handles the case where the variable is unbound. The status of this style check is unclear. It might be removed in the future or it might be enhanced with a deeper analysis to be more precise.

atom(true)

The predicate read/1 and derived predicates produce an error message on quoted atoms or strings with more than 6 unescaped newlines. Newlines may be escaped with \ or \c. This flag also enables warnings on \<newline> followed by blank space in native mode. See section 2.16.1.3. Note that the ISO standard does not allow for unescaped newlines in quoted atoms.

discontiguous(true)

Warn if the clauses for a predicate are not together in the same source file. It is advised to disable the warning for discontiguous predicates using the discontiguous/1 directive.

charset(false)

Warn on atoms and variable names holding non-ASCII characters that are not quoted. See also section 2.16.1.1.