% This LaTeX document was generated using the LaTeX backend of PlDoc, % The SWI-Prolog documentation system Imperative languages like C++, Python or JavaScript execute mostly linear code with some branching and subroutine calls. Their debuggers support stepping through the code and pausing on each line, or running the program until it hits a breakpoint and pauses. When paused, the user can inspect the current program state or give the debugger commands. Prolog has a logical execution model that involves attempting to prove logical predicates and needs a different debugging approach. SWI-Prolog uses the traditional Prolog "Byrd Box Model" or "4 Port Model" debugging approach described by \cite{byrd:80,Clocksin:87} with a couple of extensions to implement its command line debugger. There are two other debuggers available that build on this infrastructure: a \href{https://www.swi-prolog.org/gtrace.html}{graphical debugger} and remote debugging in the web interface provided by \href{https://swish.swi-prolog.org/}{SWISH}. Reference information to all predicates available for manipulating the debugger is in the debugger section (\secref{debugger}). \subsection{The Byrd Box Model And Ports} \label{sec:byrd-box-model} Standard Prolog debugging tools are built around the so-called "Byrd Box Model" or "4 Port Model" which models each predicate in a Prolog program as a state machine ("box") that transitions through states ("ports") as a program is evaluated. The developer can ask the engine to pause for program inspection when it reaches specific ports or predicates. As we go through this overview, remember that a "port" is just another word for a "state" in the state machine that each predicate transitions through during evaluation. The state machine is called a "box" because it is drawn like this: \begin{code} *--------------------------------------* Call | | Exit ---------> + descendant(X,Y) :- offspring(X,Y). + ---------> | | | descendant(X,Z) :- | <--------- + offspring(X,Y), descendant(Y,Z). + <--------- Fail | | Redo *--------------------------------------* \end{code} The standard ports are: \const{call}, \const{redo}, \const{exit} and \const{fail}. SWI-Prolog extends this with two more: \const{unify} and \const{exception}. Each trace happens at a particular phase of predicate resolution. Recall that when resolving or "proving" a predicate, the Prolog engine: \begin{enumerate} \item Collects all rules that \textbf{might} match by having a head with the same name and number of arguments \begin{itemize} \item \const{call} is traced, once, if \textbf{any} rules might match. \item \const{redo} is also traced when the engine backtracks to find the next matching rule. \end{itemize} \item Finds the next matching rule whose head can be unified with the predicate \begin{itemize} \item \const{unify} is traced with the results of unification if one is found. \item \const{fail} is traced if no rule heads can be unified. \end{itemize} \item Applies variable assignments from unification to clauses in the rule body and continues at \#1 with the updated clauses \item After \textbf{all} of the body clauses of the matched rule have either succeeded, failed, or thrown an exception: \begin{itemize} \item \const{exit} is traced if all of them succeeded (meaning this rule is true). \item \const{fail} is traced if any of them failed (meaning this rule is false). \item \const{exception} is traced if any of them threw an exception. \end{itemize} This means there can be \textbf{a lot} of traces between the initial \const{call} and the end of tracing for a particular predicate. \end{enumerate} \subsection{Trace Mode Example} \label{sec:trace-example} The \predref{trace}{0} predicate turns on "trace mode", which, by default, produces a trace and pauses at every port of every predicate to allow inspection of the state of the program. This is normally done from the Prolog console window, but for embedded Prolog systems or when Prolog runs as a daemon it can also be done by getting a prompt via the \href{https://www.swi-prolog.org/pack/list?p=libssh}{libssh} package. \begin{quote} Note: If the native graphics plugin (XPCE) is available, the commands \predref{gtrace}{0} and \predref{gspy}{1} activate the graphical debugger while \predref{tdebug}{0} and \predref{tspy}{1} allow debugging of arbitrary threads. \end{quote} Each goal is printed using the Prolog predicate \predref{write_term}{2}. The style is defined by the Prolog flag \prologflag{debugger_write_options} and can be modified using this flag or using the \const{w}, \const{p} and \const{d} commands of the tracer (\secref{trace-formatting-commands}). Here's an example debugging session that shows the basic flow. The \const{unify} port is off by default since it doesn't add a lot of information in most cases for the command line debugger. \begin{code} is_a(rock1, rock). is_a(rock2, rock). color(rock1, red). noun(X, Type) :- is_a(X, Type). adjective(X, color, Value) :- color(X, Value). \end{code} \begin{code} ?- trace. true. [trace] ?- noun(X, rock), adjective(X, color, red). Call: (11) noun(_9774, rock) ? creep \end{code} The \predref{trace}{0} predicate turned on trace mode, which is now indicated at every prompt by \verb$[trace] ?-$. The initial query provided by the user was \verb$noun(X, rock), adjective(X, color, red)$ which is asking to find a "red rock". Finally: the first port triggered was a \arg{Call} to the first predicate in the initial query, indicating the engine is about to look for the first rule that matches \verb$noun(_9774, rock)$. Pressing \const{spacebar}, \const{c}, or \const{enter} caused the tracer to print \const{creep} followed by the next trace. There are many additional commands available that are described later in the overview. \begin{code} is_a(rock1, rock). is_a(rock2, rock). color(rock1, red). noun(X, Type) :- is_a(X, Type). adjective(X, color, Value) :- color(X, Value). \end{code} \begin{code} [trace] ?- noun(X, rock), adjective(X, color, red). ... Call: (12) is_a(_9774, rock) ? creep Exit: (12) is_a(rock1, rock) ? creep Exit: (11) noun(rock1, rock) ? creep ... \end{code} Next, the first clause of \nopredref{noun}{2} gets a \const{call} trace since the engine is trying to find the next rule that matches \verb$is_a(_9774, rock)$. Since there \textbf{is} a fact that can unify: \verb$is_a(rock1, rock)$, the trace shows \const{exit} (i.e. succeeded) along with that value. Since that was the final predicate in the body of \nopredref{noun}{2}, \nopredref{noun}{2} also gets an \const{exit} trace that shows the unified value of its head: \verb$noun(rock1, rock)$. \begin{code} is_a(rock1, rock). is_a(rock2, rock). color(rock1, red). noun(X, Type) :- is_a(X, Type). adjective(X, color, Value) :- color(X, Value). \end{code} \begin{code} [trace] ?- noun(X, rock), adjective(X, color, red). ... Call: (11) adjective(rock1, color, red) ? creep Call: (12) color(rock1, red) ? creep Exit: (12) color(rock1, red) ? creep Exit: (11) adjective(rock1, color, red) ? creep X = rock1 ; ... \end{code} Prolog then moved to the next predicate in the initial query: \nopredref{adjective}{3} and solved it in a similar way. Since that was the last predicate in the query, an answer was returned. Pressing \verb$;$ requested the next answer and began Prolog backtracking. \begin{code} is_a(rock1, rock). is_a(rock2, rock). color(rock1, red). noun(X, Type) :- is_a(X, Type). adjective(X, color, Value) :- color(X, Value). \end{code} \begin{code} [trace] ?- noun(X, rock), adjective(X, color, red). ... Redo: (12) is_a(_9774, rock) ? creep Exit: (12) is_a(rock2, rock) ? creep Exit: (11) noun(rock2, rock) ? creep Call: (11) adjective(rock2, color, red) ? creep Call: (12) color(rock2, red) ? creep Fail: (12) color(rock2, red) ? creep Fail: (11) adjective(rock2, color, red) ? creep false. \end{code} The only choice point to \const{redo} (i.e. backtrack over) was the \nopredref{is_a}{2} clause of \nopredref{noun}{2} since there was one potential match left to attempt to unify: \verb$is_a(rock2, rock)$. This succeeds with an \const{exit} trace since it does unify with the \const{redo} predicate and causes \verb$noun(rock2, rock)$ to also succeed with \const{exit} just as above. As the traces continue, you can see the \const{fail} port get activated for \verb$color(rock2, red)$ since there is no way to prove that predicate and thus the whole query returns \const{false}. Tracing will continue for every query you pose until you enter \verb$notrace.$ to turn off trace mode. \subsection{Trace Mode Options: \predref{leash}{1} and \predref{visible}{1}} \label{sec:trace-options} When you enable trace mode with \predref{trace}{0}, the tracer will, by default, pause and wait for a command at every port it hits on every predicate. The \predref{leash}{1} predicate can be used to modify the ports to pause at. This is a global setting, so changes will remain until they are changed again or SWI-Prolog is restarted. Disabling the tracer via \predref{notrace}{0} doesn't affect which ports are leashed. The \predref{leash}{1} argument must start with \verb$+$ to add, or \verb$-$ to remove, followed by the name of a port such as \const{call}, \const{exit}, etc. There are special terms like \const{all} which can be used instead of manually adding or removing every port. To stop only at the fail port, use \predref{leash}{1} like this: \begin{code} ?- leash(-all). true. ?- leash(+fail). true. ?- trace. true. [trace] ?- noun(X, rock), adjective(X, color, red). Call: (11) noun(_3794, rock) Call: (12) is_a(_3794, rock) Exit: (12) is_a(rock1, rock) Exit: (11) noun(rock1, rock) Call: (11) adjective(rock1, color, red) Call: (12) color(rock1, red) Exit: (12) color(rock1, red) Exit: (11) adjective(rock1, color, red) X = rock1 ; Redo: (12) is_a(_3794, rock) Exit: (12) is_a(rock2, rock) Exit: (11) noun(rock2, rock) Call: (11) adjective(rock2, color, red) Call: (12) color(rock2, red) Fail: (12) color(rock2, red) ? creep Fail: (11) adjective(rock2, color, red) ? creep false. \end{code} Now, only the lines that start with "Fail:" have "creep" after them because that was the only time the tracer paused for a command. To never pause and just see all the traces, use \verb$leash(-all)$ and don't turn any ports back on. The default ports are still printed out because a different setting, \predref{visible}{1}, controls which ports are printed. \predref{visible}{1} takes the same form of argument as \predref{leash}{1}. To only stop and show the \const{fail} port, use \predref{leash}{1} and \predref{visible}{1} like this: \begin{code} ?- leash(-all). true. ?- leash(+fail). true. ?- visible(-all). true. ?- visible(+fail). true. ?- trace. true. [trace] ?- noun(X, rock), adjective(X, color, red). X = rock1 ; Fail: (12) color(rock2, red) ? creep Fail: (11) adjective(rock2, color, red) ? creep false. \end{code} \subsection{Trace Mode Commands When Paused} \label{sec:trace-commands} You can do way more than just press \const{spacebar} when the tracer is paused at a port. All actions are single-character commands which are executed \textbf{without} waiting for a return (unless the command line option \verb$--no-tty$ is active). Pressing \verb$?$ or \const{h} when paused will print out a list of these commands as well. \subsubsection{Control Flow Commands} \label{sec:trace-control-flow-commands} \begin{quote} \begin{tabulary}{0.9\textwidth}{|l|l|L|} \hline \textbf{Abort} & a & Abort Prolog execution (see \predref{abort}{0}) \\ \textbf{Break} & b & Enter a Prolog break environment (see \predref{break}{0}) \\ \textbf{Creep} & c & Continue execution, stop at next port. (Also \const{return}, \const{space}) \\ \textbf{Exit} & e & Terminate Prolog (see \predref{halt}{0}) \\ \textbf{Fail} & f & Force failure of the current goal \\ \textbf{Find} & / & Search for a port (see below for the description of this command (\secref{trace-find-command})) \\ \textbf{Ignore} & i & Ignore the current goal, pretending it succeeded \\ \textbf{Leap} & l & Continue execution, stop at next spy point \\ \textbf{No debug} & n & Continue execution in 'no debug' mode \\ \textbf{Repeat find} & . & Repeat the last find command (see 'Find' (\secref{trace-find-command})) \\ \textbf{Retry} & r & Undo all actions (except for database and I/O actions) back to the \const{call} port of the current goal and resume execution at the \const{call} port \\ \textbf{Skip} & s & Continue execution, stop at the next port of \textbf{this} goal (thus skipping all calls to children of this goal) \\ \textbf{Spy} & + & Set a spy point (see \predref{spy}{1}) on the current predicate. Spy points are described later in the overview (\secref{spy-points-debug-mode}). \\ \textbf{No spy} & - & Remove the spy point (see \predref{nospy}{1}) from the current predicate. Spy points are described later in the overview (\secref{spy-points-debug-mode}). \\ \textbf{Up} & u & Continue execution, stop at the next port of \textbf{the parent} goal (thus skipping this goal and all calls to children of this goal). This option is useful to stop tracing a failure driven loop. \\ \hline \end{tabulary} \end{quote} \paragraph{Find (\const{\Sdiv}) Description and Examples}\label{sec:trace-find-command} The Find (\verb$/$) command continues execution until a port matching a find pattern is found. After the \verb$/$, the user can enter a line to specify the port to search for. This line consists of a set of letters indicating the port type, followed by an optional term, that should unify with the goal run by the port. If no term is specified it is taken as a variable, searching for any port of the specified type. If an atom is given, any goal whose functor has a name equal to that atom matches. Examples: \begin{quote} \begin{tabulary}{0.9\textwidth}{|l|L|} \hline /f & Search for any \const{fail} port \\ /fe solve & Search for a \const{fail} or \const{exit} port of any goal with name \const{solve} \\ /c \verb$solve(a, _)$ & Search for a call to \predref{solve}{2} whose first argument is a variable or the atom \const{a} \\ /a \verb$member(_, _)$ & Search for any port on \predref{member}{2}. This is equivalent to setting a spy point on \predref{member}{2}. \\ \hline \end{tabulary} \end{quote} \subsubsection{Informational Commands} \label{sec:trace-information-commands} \begin{quote} \begin{tabulary}{0.9\textwidth}{|l|l|L|} \hline \textbf{Alternatives} & A & Show all goals that have alternatives \\ \textbf{Goals} & g & Show the list of parent goals (the execution stack). Note that due to tail recursion optimization a number of parent goals might not exist any more. \\ \textbf{Help} & h & Show available options (also \verb$?$) \\ \textbf{Listing} & L & List the current predicate with \predref{listing}{1} \\ \hline \end{tabulary} \end{quote} \subsubsection{Formatting Commands} \label{sec:trace-formatting-commands} \begin{quote} \begin{tabulary}{0.9\textwidth}{|l|l|L|} \hline \textbf{Context} & C & Toggle 'Show Context'. If \const{on}, the context module of the goal is displayed between square brackets (see modules section (\secref{modules})). Default is \const{off}. \\ \textbf{Display} & d & Set the \verb$max_depth(Depth)$ option of debugger_write_options (\secref{flags}), limiting the depth to which terms are printed. See also the \const{w} and \const{p} options. \\ \textbf{Print} & p & Set the Prolog flag \prologflag{debugger_write_options} to \verb$[quoted(true), portray(true), max_depth(10), priority(699)]$. This is the default. \\ \textbf{Write} & w & Set the Prolog flag \prologflag{debugger_write_options} to \verb$[quoted(true), attributes(write), priority(699)]$, bypassing \predref{portray}{1}, etc. \\ \hline \end{tabulary} \end{quote} \subsection{Trace Mode vs. Trace Point} \label{sec:trace-mode-vs-point} A slight detour is useful to describe some related predicates that can be confusing: To only trace a single or select set of predicates, the \predref{trace}{1} or \predref{trace}{2} predicates can be used to set a \textbf{trace point}. Even though they use the same base predicate name \const{trace}, these predicates ignore the \predref{leash}{1} and \predref{visible}{1} global settings and don't pause when they trace a port. They really are a different feature that also happens to do tracing. A \textbf{trace point} is set on a particular predicate and traces the ports of that predicate \textbf{whether or not you are in \predref{trace}{0} trace mode}. Each trace point can trace different ports if the \predref{trace}{2} variant is used. \begin{code} ?- trace(is_a/2). % is_a/2: [all] true. ?- noun(X, rock), adjective(X, color, red). T Call: is_a(_25702, rock) T Exit: is_a(rock1, rock) X = rock1 ; T Redo: is_a(rock1, rock) T Exit: is_a(rock2, rock) false. \end{code} Notice that \textbf{trace mode} did not have to be turned on using \predref{trace}{0} \textbf{and} that this only traced out the ports hit while executing \nopredref{is_a}{2} \textbf{and} that the program was not ever paused. In fact, if trace mode is turned on while using a trace point, things get very confusing because the trace point infrastructure itself will be traced! \begin{code} ?- trace(is_a/2). % is_a/2: [all] true. ?- trace. true. [trace] ?- noun(X, rock), adjective(X, color, red). Call: (11) noun(_29318, rock) ? creep Call: (12) is_a(_29318, rock) ? creep Call: (13) print_message(debug, frame(user:is_a(_29318, rock), trace(call))) ? creep Call: (18) push_msg(frame(user:is_a(_29318, rock), trace(call))) ? creep Call: (21) exception(undefined_global_variable, '$inprint_message', _30046) ? creep Fail: (21) exception(undefined_global_variable, '$inprint_message', _30090) ? creep Exit: (18) push_msg(frame(user:is_a(_29318, rock), trace(call))) ? creep Call: (19) prolog:message(frame(user:is_a(_29318, rock), trace(call)), _30140, _30142) ? creep Fail: (19) prolog:message(frame(user:is_a(_29318, rock), trace(call)), _30140, _30142) ? creep Call: (19) message_property(debug, stream(_30192)) ? creep Fail: (19) message_property(debug, stream(_30192)) ? creep Call: (20) message_property(debug, prefix(_30200)) ? creep Fail: (20) message_property(debug, prefix(_30200)) ? creep T Call: is_a(_29318, rock) Call: (17) pop_msg ? creep Exit: (17) pop_msg ? creep ...Lots more after this... \end{code} So, trace \textbf{points} are a confusingly named and separate feature from trace \textbf{mode}. \subsection{Spy Points and Debug Mode} \label{sec:spy-points-debug-mode} Back to trace mode features: Because the tracing output of a Prolog program can often be quite large, sometimes it is useful to start trace mode at a particular point deep in the program. This is what a \textbf{spy point} is for. It specifies a predicate that should turn on trace mode. A spy point is enabled like this: \verb$spy(mypredicate/2)$. After that command, the first time \nopredref{mypredicate}{2} is encountered, trace mode will turn on and work just like it does normally. This includes paying attention to the global \predref{leash}{1} and \predref{visible}{1} settings. The spy point can be removed using \predref{nospy}{1} or \predref{nospyall}{0}. \begin{code} is_a(rock1, rock). is_a(rock2, rock). color(rock1, red). noun(X, Type) :- is_a(X, Type). adjective(X, color, Value) :- color(X, Value). \end{code} \begin{code} ?- spy(is_a/2). % Spy point on is_a/2 true. [debug] ?- noun(X, rock), adjective(X, color, red). * Call: (12) is_a(_1858, rock) ? creep * Exit: (12) is_a(rock1, rock) ? creep Exit: (11) noun(rock1, rock) ? creep Call: (11) adjective(rock1, color, red) ? creep Call: (12) color(rock1, red) ? creep Exit: (12) color(rock1, red) ? creep Exit: (11) adjective(rock1, color, red) ? creep X = rock1 ; * Redo: (12) is_a(_1858, rock) ? creep * Exit: (12) is_a(rock2, rock) ? creep Exit: (11) noun(rock2, rock) ? creep Call: (11) adjective(rock2, color, red) ? creep Call: (12) color(rock2, red) ? creep Fail: (12) color(rock2, red) ? creep Fail: (11) adjective(rock2, color, red) ? creep false. \end{code} After the spy point is hit, the output above is identical to the traces generated by running \predref{trace}{0} with the initial query, but is obviously missing all of the traces before the spy point. Note that after \predref{spy}{1} is called, there is a new tag in front of \verb$?-$, the \verb$[debug]$ tag: \begin{code} ?- spy(is_a/2). % Spy point on is_a/2 true. [debug] ?- \end{code} This means the system is in "debug mode". Debug mode does two things: it tells the system to watch for spy points and it turns off some optimizations that would make the traces confusing. The ideal 4-port model (\cite{byrd:80}) as described in many Prolog books (\cite{Clocksin:87}) is not visible in many Prolog implementations because code optimisation removes part of the choice and exit points. Backtrack points are not shown if either the goal succeeded deterministically or its alternatives were removed using the cut. When running in debug mode, choice points are only destroyed when removed by the cut and last call optimisation is switched off. [Note: This implies the system can run out of stack in debug mode, while no problems arise when running in non-debug mode.] Debug mode can be turned off again using \predref{nodebug}{0}, but then the spy point will be ignored (but remembered). Turning debug mode back on via \predref{debug}{0} will hit the spy point again. \begin{code} is_a(rock1, rock). is_a(rock2, rock). color(rock1, red). noun(X, Type) :- is_a(X, Type). adjective(X, color, Value) :- color(X, Value). \end{code} \begin{code} ?- spy(is_a/2). % Spy point on is_a/2 true. [debug] ?- nodebug. true. ?- noun(X, rock). X = rock1 ; X = rock2. ?- debug. true. [debug] ?- noun(X, rock). * Call: (11) is_a(_47826, rock) ? creep * Exit: (11) is_a(rock1, rock) ? creep Exit: (10) noun(rock1, rock) ? creep X = rock1 ; * Redo: (11) is_a(_47826, rock) ? creep * Exit: (11) is_a(rock2, rock) ? creep Exit: (10) noun(rock2, rock) ? creep X = rock2. \end{code} So, debug mode allows Prolog to watch for spy points and enable trace mode when it hits one. The \predref{tracing}{0} and \predref{debugging}{0} predicates will report if the system is in either of those modes. \subsection{Breakpoints} \label{sec:trace-breakpoints} Sometimes even spy points aren't enough. There may be a predicate that is used in many different places and it would be helpful to turn on tracing mode only when \textbf{one particular} call to it is made. \textbf{Breakpoints} allow for turning on trace mode when a specific source file, line number, and character in that line are hit. The predicates used are \predref{set_breakpoint}{4} and \predref{set_breakpoint}{5}. Many breakpoints can be active at a time. Note that the interface provided by these predicates is not intended for end-users. The built-in PceEmacs editor that is also embedded in the graphical debugger allow setting break points based on the cursor position. \file{Example.pl} has now been modified to have multiple calls to \nopredref{noun}{2}: \begin{code} is_a(rock1, rock). is_a(rock2, rock). color(rock1, red). noun(X, Type) :- is_a(X, Type). adjective(X, color, Value) :- color(X, Value). test_noun1(X, Type) :- noun(X, Type). test_noun2(X, Type) :- noun(X, Type). \end{code} To enable tracing just when \nopredref{noun}{2} is called from \nopredref{test_noun2}{2}, \predref{set_breakpoint}{4} can be used like this: \begin{code} ?- set_breakpoint('/...path.../Example.pl', 8, 24, ID). % Breakpoint 1 in 1-st clause of test_noun2/2 at Example.pl:8 ID = 1. ?- debug. true. [debug] ?- noun(X, rock). X = rock1 . [debug] ?- test_noun1(X, rock). X = rock1 . [debug] ?- test_noun2(X, rock). Call: (11) noun(_44982, rock) ? creep Call: (12) is_a(_44982, rock) ? creep Exit: (12) is_a(rock1, rock) ? creep Exit: (11) noun(rock1, rock) ? creep Exit: (10) test_noun2(rock1, rock) ? creep X = rock1 . [trace] ?- notrace. true. [debug] ?- \end{code} The call to \predref{set_breakpoint}{4} had to specify the source file ("\file{Example.pl}"), the line number (8), and the character within that line (24) to precisely specify what clause should turn on trace mode (this is much easier using the graphical debugger because it shows source code). The breakpoint won't get triggered if the system isn't in debug mode but, unlike setting a spy point, \predref{set_breakpoint}{4} does \textbf{not} do this automatically. So, it was turned on manually using \predref{debug}{0}. The output shows that only the call to \nopredref{test_noun2}{2} (where the breakpoint was set) actually turned on trace mode. Note that the \verb$[Trace] ?-$ at the end shows that trace mode is left on after being triggered. It can be turned off again via \predref{notrace}{0}, which will leave the system in debug mode. All debugging modes can be shut off at once by calling \predref{nodebug}{0} since shutting off debug mode automatically turns off trace mode. In addition, SWI-Prolog supports attaching an arbitrary goal to each breakpoint via \predref{set_breakpoint_condition}{2}, which yields \textbf{Conditional Breakpoints}. A conditional breakpoint is the same as the regular breakpoints discussed thus far, except that whenever the breakpoint is triggered, the given goal is invoked and trace mode is only turned on in case it succeeds. To enable tracing just when \nopredref{noun}{2} is called from \nopredref{test_noun2}{2} with \verb$rock2$ as the first argument, \predref{set_breakpoint_condition}{2} can be used like below. Note that the condition is a Prolog string that is parsed to obtain the goal as well as the variable names. The resulting goal is called in the module in which the clause body is executed (see \predref{clause_property}{2}, property \const{module}). \begin{code} ?- set_breakpoint('/...path.../Example.pl', 8, 24, ID). ID = 1. ?- set_breakpoint_condition(1, "X == rock2"). true. ?- debug. true. [debug] ?- test_noun2(X, rock). X = rock1 ; X = rock2. [debug] ?- test_noun2(rock2, rock). Call: (11) noun(rock2, rock) ? creep Call: (12) is_a(rock2, rock) ? creep Exit: (12) is_a(rock2, rock) ? creep Exit: (11) noun(rock2, rock) ? creep Exit: (10) test_noun2(rock2, rock) ? creep true. [trace] ?- \end{code} \subsection{Command Line Debugger Summary} \label{sec:trace-summary} In summary, there are really two distinct "tracing" features: trace \textbf{mode} and trace \textbf{points}. Both write traces to the console using the "Byrd Box Model" but that's where similarity ends. \subsubsection{Trace Mode} \label{sec:trace-summary-trace-mode} Trace mode is the main Prolog command line debugger that allows for tracing the transitions through the resolution states of predicates represented by ports in the "Byrd Box Model" and optionally pausing for a command when certain ports are hit. It can be turned on manually via \predref{trace}{0}, or (when put into debug mode using \predref{debug}{0}) when a specific predicate is encountered via \predref{spy}{1}, or when a specific call to a predicate is encountered via \predref{set_breakpoint}{4} or \predref{set_breakpoint}{5}. When in trace mode, \predref{visible}{1} controls which ports are written to the console, and \predref{leash}{1} controls which ports cause execution to pause to allow program inspection. When execution is paused, there are many commands that can be used to inspect the state of the program, cause goals to fail or succeed, etc. Trace mode is turned off via \predref{notrace}{0} and debug mode is turned off via \predref{nodebug}{0}. \subsubsection{Trace Points} \label{sec:trace-summary-trace-points} Trace \textbf{points} are a separate feature from trace \textbf{mode} that allow writing specified ports to the console when a predicate is being evaluated. It does not ever pause program execution and does not need to be in trace or debug mode to work. They are turned on via \predref{trace}{1} and \predref{trace}{2}. They don't pay attention to \predref{visible}{1} (because the ports shown are set in \predref{trace}{2}) or \predref{leash}{1} (because they don't pause execution). They can be turned off via \predref{trace}{2}.