## 4.38 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 `\bnfmeta{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)
  Set style checking options. Spec is either `+<option>`, `-<option>`, `?(<option>)`101In older versions ```?``' was a prefix operator. In versions after 5.5.13, explicit brackets are needed. or a list of such options. `+<option>` sets a style checking option, `-<option>` clears it and `?(<option>)` succeeds or fails according to the current setting. consult/1 and derivatives reset the style checking options to their value before loading the file. If, for example, a file containing long atoms should be loaded, the user can start the file with:

      :- style_check(-atom).

  The currently available options are given below with their default between brackets.

  singleton(true)
    The predicate read_clause/1 (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.15.1.6 for details on variable handling and warnings.
  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.15.1.2.
  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.
  string(false)
    Backward compatibility. See the Prolog flag double_quotes (current_prolog_flag/2).
  charset(false)
    Warn on atoms and variables holding non-ASCII characters that are not quoted. See also section 2.15.1.1.