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

[Peter Wang]

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.
+
 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
 	trailing
 	tabling
@@ -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 @@
+-----------------------------------------------------------------------------
+
+SOURCE-TO-SOURCE DEBUGGER
+
+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.
+
+-----------------------------------------------------------------------------
+
+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.
+
+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
+
+-----------------------------------------------------------------------------
+
+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.  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
--------------------------------------------------------------------------