mirror of
https://github.com/Mercury-Language/mercury.git
synced 2026-04-15 17:33:38 +00:00
1fc67cafdd
Branches: main
README.ssdebug:
Update a note about SIGINT handling in Mono, which is (will be) fixed
in later versions.
109 lines
4.4 KiB
Plaintext
109 lines
4.4 KiB
Plaintext
-----------------------------------------------------------------------------
|
|
|
|
SOURCE-TO-SOURCE DEBUGGER
|
|
|
|
The source-to-source debugger (ssdebug, ssdb) operates by performing a
|
|
high-level transformation of Mercury source code to provide a rudimentary
|
|
debugger interface. As such, it has numerous limitations (see below), but
|
|
can potentially work with all backends. It is mainly intended for when you
|
|
cannot use the Mercury debugger `mdb', such as with the Java or high-level C
|
|
backends.
|
|
|
|
ssdebug is still an experimental feature.
|
|
|
|
-----------------------------------------------------------------------------
|
|
|
|
INSTALLATION
|
|
|
|
To use the source-to-source debugger you must install grades containing the
|
|
".ssdebug" grade component. One way to do this is to invoke configure
|
|
with the option `--enable-ssdebug-grades'. This will add the grades
|
|
hlc.gc.ssdebug, csharp.ssdebug and java.ssdebug to the set of library grades
|
|
to install.
|
|
|
|
-----------------------------------------------------------------------------
|
|
|
|
THE .ssdebug GRADE COMPONENT
|
|
|
|
Compile your program in a grade with the ".ssdebug" grade component,
|
|
e.g. java.ssdebug or hlc.gc.ssdebug.
|
|
|
|
You may run the program as usual. To bring up the debugger prompt, set
|
|
the environment variable SSDB beforehand.
|
|
|
|
% SSDB=1 ./calculator
|
|
1: 1 1 CALL calculator.main
|
|
ssdb>
|
|
|
|
As in mdb, the three numbers are the event number, call sequence number (CSN)
|
|
and the stack depth. Type "help" to show a list of commands. All commands act
|
|
like their mdb counterparts (with reduced functionality), except for `list'
|
|
which prints the source code at the call site, not of the called procedure.
|
|
|
|
The debugger will execute commands from `$HOME/.ssdbrc' and `.ssdbrc' in
|
|
the current working directory, in order, at startup. You can put your
|
|
aliases and settings in those files. Lines starting with the # character
|
|
will be ignored.
|
|
|
|
For Java grades, JDK 7 improves performance considerably.
|
|
Early access releases are available from
|
|
<http://java.sun.com/javase/downloads/ea.jsp>
|
|
|
|
Programs built in .ssdebug grades use much more stack space (tail call
|
|
optimisation is destroyed by the transformation). You will likely need to
|
|
increase the stack size, e.g.
|
|
|
|
JAVA='java -Xss10m' SSDB=1 ./calculator
|
|
|
|
-----------------------------------------------------------------------------
|
|
|
|
LIMITATIONS
|
|
|
|
- There are no internal events. The only events are CALL, EXIT, REDO, FAIL,
|
|
and, for Java and C# grades, EXCP.
|
|
|
|
- Standard library procedures are treated specially. Events will only be
|
|
generated at the boundaries at which a user procedure calls and returns
|
|
from a standard library procedure. No events will be generated when a
|
|
standard library procedure calls another standard library procedure.
|
|
|
|
- The "retry" command works by executing forwards until reaching the end of
|
|
the call to retry, then recursively calling that procedure. Any side
|
|
effects of continuing execution will be visible. If it is not possible to
|
|
reach the end of the procedure to retry, the program will simply keep
|
|
executing. Press ^C to get back the debugger prompt.
|
|
|
|
- When running on Mono 2.8 and earlier, ^C can cause the program to hang.
|
|
This is fixed in later versions.
|
|
|
|
- Exceptions are only handled in Java and C# grades. Only a single EXCP event
|
|
is generated when an exception is thrown, instead of propagating EXCP events
|
|
up the call stack to the nearest exception handler.
|
|
|
|
- In grades which don't handle exceptions, the debugger's internal state will
|
|
be inconsistent with the program's execution after an exception, so you had
|
|
better quit the program and restart.
|
|
|
|
- Breakpoints currently match procedures by module and name only. Predicates
|
|
or functions with the same name but different arities will still match.
|
|
The debugger will not warn you if you set a breakpoint on a non-existent
|
|
procedure.
|
|
|
|
- We provide the filename and line number of call sites, but not the location
|
|
of the source code for the called procedure itself. Use mtags.
|
|
|
|
- The print goal command does not distinguish predicates and functions.
|
|
|
|
- Procedures with arguments which are neither `in' nor `out' will not be
|
|
transformed, hence will not generate events when called.
|
|
|
|
- Many commands available in mdb are not yet implemented for ssdebug.
|
|
|
|
- There is no tab completion.
|
|
|
|
- There is no I/O tabling.
|
|
|
|
- Debugging of multi-threaded programs is not supported.
|
|
|
|
-----------------------------------------------------------------------------
|