---

This file is part of Logtalk https://logtalk.org/ SPDX-FileCopyrightText: 1998-2024 Paulo Moura <pmoura@logtalk.org> SPDX-License-Identifier: Apache-2.0

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

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:

[../../docs/library_index.html#debugger](../../docs/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 in 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:

[../../manuals/userman/debugging.html](../../manuals/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-levle goal when tracing it.

Alternative debugger tools

Logtalk provides basic support for the SWI-Prolog graphical tracer. The required settings are described in the 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:

| ?- gtrace, foo::bar.

You can also use the gspy/1 predicate to spy 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)).

and checking 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.