\chapter{Development and debugging tools}	\label{sec:debugging}

This section describes various tools and techniques to help finding bugs
in \productpl{} code.  Most of the tracing is done in the hosting
Prolog language.  \product{} provides additional tools for tracing
the execution of certain methods, breaking on the implementation of
a Prolog-defined method, finding and inspecting objects.


\section{Object-base consistency}

Unlike Prolog, \product{} is not {\em secure}: if a Prolog environment traps
a fatal error there is almost always a bug in the Prolog system.
Except for violating system limits there is no Prolog program that can
make the Prolog environment crash.  For \product{} this is different.
Consider the following example:

\begin{code}
1 ?- new(@p, picture),
     send(@p, display, new(B, box(100,100))),
     get(B, area, Area),
     free(Area).

Area = @ 803438, B = @803419/box
\end{code}

After these calls, the <-area attribute of the box has been destroyed,
but the box is not aware of this fact.  The utility predicate
checkpce/0 scans the \product{} object-base for various inconsistencies and
will report that the box contains a slot referring to a freed object.

\begin{code}
2 ?- checkpce.

[WARNING: Freed object in slot area of @803419/box: @803438/area]
[PCE: Checked 13173 objects]
\end{code}

\product{} uses heuristics trying to avoid that such problems actually
crash the system (in the example above execution continues
normally).

We advice using checkpce/0 regularly during program development to
verify your application is not violating object consistency.  Please
see \secref{whoiswho} and \secref{hyper} for techniques
to avoid `dangling' object references.


\section{Tracing methods}

It is often useful to inspect the execution of a particular method.
Suppose we want to monitor geometry-changes of graphical objects.  The
utility predicate tracepce/1 (see also \secref{interface}) may be used:

\begin{code}
1 ?- tracepce((graphical->geometry)).
Trace method: graphical ->geometry
\end{code}

As \verb$->$ is a standard Prolog operator with priority over 1000,
tracepce/1 requires two brackets.  Get-methods may be specified in
a similar way.  \verb$<-$ is not an operator.  It is suggested to
define \verb$<-$ as an infix operator in the \product{} initialisation
file, so this operator is available during program development:

\begin{code}
:- op(100, xfx, <-).
\end{code}

Instance variables may be specified as <class>-<variable>. A trace-point
on an instance variable makes both reading and writing the variable
visible.

The predicate notracepce/1 disables a tracepoint.

\section{Breaking (spy) on methods}

\index{spy}\index{break}%
Prolog-defined methods are all implemented using the same predicate,
which makes it hard to use spy/1 for starting the debugger on a method.
One way around is to stick a call to trace/0 into the method body and
recompile the file.  For those among us who dislike this idea there
is the possibility to use spypce/1.

\begin{description}
    \predicate{spypce}{1}{+Spec}
\arg{Spec} specifies a send- or get-method like tracepce/1.  If the
method is defined in Prolog \product{} calls trace/0 just before
starting the implementation of the method.
\end{description}


\section{Visual hierarchy tool}		\label{sec:vishierarchy}

\index{hierarchy,of UI components}
The ``Visual Hierarchy'' tool provides an overview of the consists-of
relations between the various UI components in a tool.  It is part of
the online manual tools and may be started from the ``Tool'' entry in
the main dialog.  \Figref{vishierarchy} shows this tool examining
the structure of the ``PceDraw'' demo program.

\postscriptfig[width=\textwidth]{vishierarchy}{Visual Hierarchy Tool showing ``PceDraw''}

This tool is very useful to examine the structure of existing
applications (for example the various demo programs).  It may also
be used to find object-references and to launch the inspector
(\secref{inspector}) on a particular object.

There are three ways to expand the tree of the visual hierarchy
tool.  The first is to expand the tree from the initially displayed
root object.  The second is to type the reference in the ``Visual''
text_item and press {\sc return}.  The most comfortable way is to position
the mouse in the target object and type {\sc meta-shift-control-V}.%
    \footnote{To remember this sequence: {\bf V} for Visual and all
              defined modifiers to avoid a conflict with application
	      defined key-bindings.}
	      

\section{Inspector tool}		\label{sec:inspector}

The inspector provides a visual representation of all attributes of an
object.  It is a visual form of the debugging predicate show_slots/1
which dumps the class and slot value of the argument reference in
the Prolog window.  The inspector is started from the ``Tools'' entry
of the manual tools.

\postscriptfig[width=\textwidth]{inspector}{Inspector Tool}
\index{object,inspecting}\index{inspector}