[m-rev.] for review: some documentation for ssdebug

[Julien Fischer]

On Thu, 10 Jun 2010, Peter Wang wrote:

> Branches: main, 10.04
>
> README.ssdebug:
>        Add some documentation for the source-to-source debugger.
>
> NEWS:
> README.Java:
>        Mention the source-to-source debugger.
>
> diff --git a/NEWS b/NEWS
> index 13ff88b..c7bce3e 100644
> --- a/NEWS
> +++ b/NEWS
> @@ -372,6 +372,10 @@ Changes to the Mercury compiler:
> * Generation of 64-bit code on Mac OS X is now supported,
>   i.e. the x86_64*apple*darwin* architecture is now supported.
>
> +* We have added an alternative debugger, the source-to-source debugger.
> +  It is much more limited than mdb, but works not just with the low-level
> +  C backend.

I suggest:

 	* We have added another debugger, called the source-to-source debugger (ssdb).
  	  Currently it is more limited than mdb, but it does work with
           backends other than the low-level C backend, e.g. the Java
           backend.

...

> index 0000000..51ffbea
> --- /dev/null
> +++ b/README.ssdebug
> @@ -0,0 +1,81 @@
> +-----------------------------------------------------------------------------
> +
> +SOURCE-TO-SOURCE DEBUGGER
> +
> +The source-to-source debugger (ssdebug, ssdb) is a debugger of last resort.

I would not describe it as the debugger of "last resort", for me that
would be gdb or jdb (depending on the backend).

> +It 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.
> +
> +-----------------------------------------------------------------------------
> +
> +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.

How closely to mdb and ssdb commands line up (for the subset that ssdb
supports)?

> +For Java grades, JDK 7 improves performance considerably.
> +Early access releases are available from
> +        <http://java.sun.com/javase/downloads/ea.jsp>
> +
> +Programs in .ssdebug grades use much more stack space (tail call optimisation

s/Programs in/Programs built in/

> +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 grades, EXCP.
> +
> +- Standard library procedures are treated specially.  Events will only be
> +  generated at the boundaries where a user procedure calls a standard library
> +  procedure.

     at the boundaries at which a user procedure calls and returns from a
     standard library procedure ...

(There is only one boundary at which it is called.)

> 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.
> +
> +- Exceptions are only handled in Java 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 other grades, the debugger's internal state will be inconsistent with the

I suggest: In non-Java grades,

> +  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.
> +
> +- Many commands available in mdb are not yet implemented for ssdebug.
> +
> +- There is no tab completion.
> +
> +- There is no I/O tabling.

Julien.
--------------------------------------------------------------------------
mercury-reviews mailing list
Post messages to:       mercury-reviews at csse.unimelb.edu.au
Administrative Queries: owner-mercury-reviews at csse.unimelb.edu.au
Subscriptions:          mercury-reviews-request at csse.unimelb.edu.au
--------------------------------------------------------------------------