## 4.36 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 can not 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 redirects 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
  Reverts 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` parameters of all stacks is enlarged to 8 K-cells if debugging is switched off 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 toplevel 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.4.
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 port 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>)`75In older versions ```?``' was a prefix operator. Inversions 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 resets 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).

  Currently available options are:

  Name | Default | Description
  `singleton` | on | read_clause/1 (used by consult/1) warns on variables only appearing once in a term (clause) which have a name not starting with an underscore. See section 2.15.1.5 for details on variable handling and warnings.
  `atom` | on | read/1 and derivatives will produce an error message on quoted atoms or strings longer than 5 lines.
  `dollar` | off | Accept dollar as a lower case character, thus avoiding the need for quoting atoms with dollar signs. System maintenance use only.
  `discontiguous` | on | Warn if the clauses for a predicate are not together in the same source file.
  `string` | off | Backward compatibility. See the Prolog flag double_quotes (current_prolog_flag/2).
  `charset` | off | Warn on atoms and variables holding non-ASCII characters that are not quoted. See also section 2.15.1.1.