.. _library_debugger:

``debugger``
============

This tool provides the default Logtalk command-line debugger. Unlike
Prolog systems, the Logtalk debugger is a regular application, using a
public API. As a consequence, it must be explicitly loaded by the
programmer, either manually at the top-level interpreter or
automatically from a settings file.

API documentation
-----------------

This tool API documentation is available at:

`../../apis/library_index.html#debugger <../../apis/library_index.html#debugger>`__

Loading
-------

This tool can be loaded using the query:

::

   | ?- logtalk_load(debugger(loader)).

When the code to be debugged runs computationally expensive
initializations, loading this tool after the code may have a noticeable
impact on loading times.

Testing
-------

To test this tool, load the ``tester.lgt`` file:

::

   | ?- logtalk_load(debugger(tester)).

Usage
-----

Debugging Logtalk source code (with this debugger) requires compiling
source files using the ``debug(on)`` compiler flag. For example:

::

   | ?- logtalk_load(my_buggy_code, [debug(on)]).

In alternative, you may also turn on the ``debug`` flag globally by
typing:

::

   | ?- set_logtalk_flag(debug, on).

But note that loader files may override this flag setting (e.g., by
using ``debug(off)`` or ``optimize(on)`` options for loaded files). If
that's the case, you will need to either edit the loader files or write
customized loader files enabling debugging. For detailed information on
using the debugger, consult the debugging section of the User Manual:

`../../handbook/userman/debugging.html <../../handbook/userman/debugging.html>`__

The ``debugger_messages.lgt`` source file defines the default debugger
message translations.

The ``dump_trace.lgt`` provides a simple solution for dumping a goal
trace to a file. For example:

::

   | ?- dump_trace::start_redirect_to_file('trace.txt', some_goal),
        dump_trace::stop_redirect_to_file.

A full trace can also be obtained at the top-level by using the ``S``
(Skip) command at the call port for the top-level goal when tracing it.

Alternative debugger tools
--------------------------

Logtalk provides basic support for the SWI-Prolog graphical tracer. The
**required** settings are described in the
``samples/settings-sample.lgt`` file. Logtalk queries can be traced
using this tool by using the ``gtrace/0-1`` predicates. For example:

::

   | ?- gtrace(foo::bar).

Or alternatively:

::

   | ?- gtrace, foo::bar.

You can also use the ``gspy/1`` predicate to spy on a Logtalk predicate
specified as ``Entity::Functor/Arity`` when using the graphical tracer.
When using this tool, internal Logtalk compiler/runtime predicates and
compiled predicates that resulted from the term-expansion mechanism may
be exposed in some cases. This issue is shared with Prolog code and
results from the non-availability of source code for the predicates
being traced.

Known issues
------------

Clause breakpoints require a Prolog backend compiler that supports
accessing read term starting line but only some backends (B-Prolog, GNU
Prolog, JIProlog, XVM, SICStus Prolog, SWI-Prolog, Trealla Prolog, and
YAP) provide accurate line numbers. As a workaround, you can check the
start line number for an entity predicate definition using a query such
as:

::

   | ?- object_property(Entity, defines(Functor/Arity, Properties)).

Check the returned ``line_count/1`` property to find if there's any
offset to the source file number of the predicate clause that you want
to trace. This issue, if present, usually only affects the first
predicate clause.

Clause breakpoints are currently not available when using XSB as this
backend doesn't provide line information.

Using the port command ``p`` (print) requires a backend supporting the
user-defined ``portray/1`` hook predicate called via the ``format/2-3``
predicates ``~p`` control sequence.
