mirror of
https://github.com/Mercury-Language/mercury.git
synced 2025-12-09 19:02:18 +00:00
c372317c26
Estimated hours taken: 8 Branches: main Add option --ssdb-trace which allows one to control which modules are traced in the ssdebug grade and to what level. Add option --link-ssdb-libs which allows one to link the ssdebug libraries into an executable not compiled in a .ssdebug grade. README.ssdebug: Document the new options. compiler/compile_target_code.m: compiler/module_cmds.m: Use link_ssdb_libs rather than source_to_source_debug. compiler/globals.m: Add ssdb_trace_level. Set the correct ssdb_trace_level according to the value of source_to_source_debug. compiler/handle_options.m: Determine the value of --ssdb-trace according to the values of --ssdb and --force-disable-ssdb. Set --link-ssdb-libs to true is --ssdb is set. compiler/mercury_compile_middle_passes.m: Always apply the ssdb transformation pass. compiler/module_imports.m: If the SSDB trace level implies the transformation has been done, then import the ssdb module. compiler/options.m: Add ssdb_trace_level and link_ssdb_libs options. compiler/ssdebug.m: Use ssdb_trace_level to determine which transformations are applied to which procedures. Change the transformation so that it's now aware of which level tracing is in effect. ssdb/ssdb.m: Record which level of tracing is applicable at each level of the stack. Use that information to decide whether or not to stop at an event. Avoid aborts when attempting to install the sigint handler in the C# grade. Allow the read_and_execute_cmd code to handle 10 io errors in a row before finally quiting, this avoids problems in the C# grade where some keypresses lead to transient io errors.
137 lines
5.4 KiB
Plaintext
137 lines
5.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 can install the 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.
|
|
|
|
-----------------------------------------------------------------------------
|
|
|
|
COMPILATION
|
|
|
|
Compile your program in a grade with the ".ssdebug" grade component, e.g.
|
|
java.ssdebug or hlc.gc.ssdebug. Your entire program will be then compiled
|
|
with --ssdb-trace level of deep.
|
|
|
|
An alternative way is to use `mmc --make --link-ssdb-libs' to compile your
|
|
program in any grade. You then just need to set --ssdb-trace shallow or deep
|
|
on the modules you wish to debug.
|
|
|
|
-----------------------------------------------------------------------------
|
|
|
|
TRACING LEVELS
|
|
|
|
--ssdb-trace none
|
|
None of the procedures in the module will generate trace events.
|
|
|
|
--ssdb-trace shallow
|
|
All the procedures in the interface of the module will generate events
|
|
of trace level shallow. Events of trace level shallow are only
|
|
displayed if the parent procedure in the call stack is compiled in
|
|
trace level deep.
|
|
|
|
--ssdb-trace deep
|
|
All procedures in the module will generate events of trace level deep..
|
|
|
|
-----------------------------------------------------------------------------
|
|
|
|
USING THE SOURCE TO SOURCE DEBUGGER
|
|
|
|
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>
|
|
|
|
If you set SSDB=0 then you will need to explicitly enable the debugger later in
|
|
your code by calling ssdb.enable_debugging/2.
|
|
|
|
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.
|
|
|
|
-----------------------------------------------------------------------------
|