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

Peter Wang novalazy at gmail.com
Thu Jun 10 12:43:31 AEST 2010

Branches: main, 10.04

        Add some documentation for the source-to-source debugger.
        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.
 Changes to the Mercury deep profiler:
 * The deep profiler now supports measuring a proxy for time: a counter that
diff --git a/README.Java b/README.Java
index 29d0664..b87bf41 100644
--- a/README.Java
+++ b/README.Java
@@ -125,7 +125,7 @@ Q. What features are not yet implemented for the Java back-end?
 A. The following implementation features are not supported:
-	Mercury-level debugging
+	Mercury-level debugging (but see next question)
 	Mercury-level profiling
@@ -162,7 +162,13 @@ A. The following implementation features are not supported:
    This list is probably not complete.
-Q. So how do I enable Java-level debugging?
+Q. How do I debug Mercury programs on Java?
+A. The only Mercury-level debugger available for Java grades is the
+   source-to-source debugger; see README.ssdebug.
+Q. How do I enable Java-level debugging?
 A. By default, javac already generates line number and source file debugging
    information.  You can include local variable debugging information by
diff --git a/README.ssdebug b/README.ssdebug
new file mode 100644
index 0000000..51ffbea
--- /dev/null
+++ b/README.ssdebug
@@ -0,0 +1,81 @@
+The source-to-source debugger (ssdebug, ssdb) is a debugger of last resort.
+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.
+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.
+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
+is destroyed by the transformation).  You will likely need to increase the
+stack size, e.g.
+        JAVA='java -Xss10m' SSDB=1 ./calculator
+- 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.  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
+  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.

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

More information about the reviews mailing list