[m-dev.] for review: improve debugger documentation

[Fergus Henderson]

Estimated hours taken: 2.5

doc/user_guide.texi:
	Add a "Quick overview" section to the debugger chapter.
	Document mdb's Emacs interface.

doc/mdb_categories:
	Fix a bug: it didn't mention the "context" command.

Workspace: /d-drive/home/hg/fjh/mercury
Index: doc/mdb_categories
===================================================================
RCS file: /home/mercury1/repository/mercury/doc/mdb_categories,v
retrieving revision 1.5
diff -u -d -r1.5 mdb_categories
--- doc/mdb_categories	1999/11/18 13:33:23	1.5
+++ doc/mdb_categories	1999/12/09 14:31:02
@@ -37,8 +37,8 @@
 end
 document_category 600 parameter
 parameter  - Commands that let users access debugger parameters.
-             The parameter commands are `printlevel', `echo', `scroll',
-             `mmc_options', `alias' and `unalias'.
+             The parameter commands are `printlevel', `echo', `context',
+	     `scroll', `mmc_options', `alias' and `unalias'.
 
 end
 document_category 700 help
Index: doc/user_guide.texi
===================================================================
RCS file: /home/mercury1/repository/mercury/doc/user_guide.texi,v
retrieving revision 1.194
diff -u -d -r1.194 user_guide.texi
--- doc/user_guide.texi	1999/11/15 00:58:13	1.194
+++ doc/user_guide.texi	1999/12/09 14:47:04
@@ -909,6 +909,8 @@
 @chapter Debugging
 
 @menu
+* Quick overview::
+* GNU Emacs interface::
 * Tracing of Mercury programs::
 * Preparing a program for debugging::
 * Selecting trace events::
@@ -916,6 +918,210 @@
 * Mercury debugger concepts::
 * Debugger commands::
 @end menu
+
+ at node Quick overview
+ at section Quick overview
+
+This section gives a quick and simple guide to getting
+started with the debugger.  The remainder of this chapter
+contains more detailed documentation.
+
+To use the debugger, you must
+first compile your program with debugging enabled.
+You can do this by using the @samp{--debug} option to @samp{mdb},
+or by including @samp{GRADEFLAGS = --debug} in your @file{Mmakefile}.
+
+ at example
+bash$ mmc --debug hello.m
+ at end example
+
+Once you've compiled with debugging enabled, you can use the @samp{mdb}
+command to invoke your program under the debugger:
+
+ at example
+bash$ mdb ./hello arg1 arg2 ...
+ at end example
+
+Any arguments (such as @samp{arg1 arg2 ...} in this example)
+that you pass after the program name will be given as arguments
+to the program.
+
+The debugger will print a start-up message
+and will then show you the first trace event,
+namely the call to @code{main/2}:
+
+ at example
+       1:      1  1 CALL pred hello:main/2-0 (det)
+                         hello.m:13
+mdb>
+ at end example
+
+By hitting enter at the @samp{mdb>} prompt, you can step through
+the execution of your program to the next trace event:
+
+ at example
+       2:      2  2 CALL pred io:write_string/3-0 (det)
+                         io.m:2837 (hello.m:14)
+mdb>
+Hello, world
+       3:      2  2 EXIT pred io:write_string/3-0 (det)
+                         io.m:2837 (hello.m:14)
+mdb>
+
+ at end example
+
+For each trace event, the debugger prints out several pieces of
+information.  The three numbers at the start of the display are the
+event number, the sequence number, and the call depth. 
+(You don't really need to pay too much attention to those.)
+They are followed by the event type (e.g. @samp{CALL} or @samp{EXIT}).
+After that comes the module name (@samp{io}),
+procedure name (@samp{write_string}), arity (@samp{3}),
+mode number (@samp{0}), and determinism (@samp{det}).
+This may sometimes be followed by a "path"
+(@pxref{Tracing of Mercury programs}).
+At the end is the file name and line number of the
+called procedure and (if available) also the file name
+and line number of the call.
+
+The most useful @code{mdb} commands have single-letter abbreviations.
+The @samp{alias} command will show these abbreviations:
+
+ at example
+mdb> alias
+?      =>    help
+EMPTY  =>    step
+NUMBER =>    step
+P      =>    print *
+b      =>    break
+c      =>    continue
+d      =>    stack
+f      =>    finish
+g      =>    goto
+h      =>    help
+p      =>    print
+r      =>    retry
+s      =>    step
+v      =>    vars
+ at end example
+
+The @samp{P} or @samp{print *} command will display the values
+of any live variables in scope.
+The @samp{f} or @samp{finish} command can be used if you want
+to skip over a call.
+The @samp{b} or @samp{break} command can be used to set break-points.
+The @samp{d} or @samp{stack} command will display the call stack.
+The @samp{quit} command will exit the debugger.
+
+That should be enough to get you started.
+But if you have GNU Emacs installed, you should strongly
+consider using the Emacs interface to @samp{mdb} --- see
+the following section.
+
+For more information about the available commands,
+use the @samp{?} or @samp{help} command, or see @ref{Debugger commands}.
+
+ at node GNU Emacs interface
+ at section GNU Emacs interface
+
+As well as the command-line debugger, mdb, there is also an Emacs
+interface to this debugger.  Note that the Emacs interface only
+works with GNU Emacs, not with XEmacs.
+
+With the Emacs interface, the debugger will display your source code
+as you trace through it, marking the line that is currently being
+executed, and allowing you to easily set breakpoints on particular
+lines in your source code.  You can have separate windows for
+the debugger prompt, the source code being executed, and for
+the output of the program being executed.
+In addition, most of the mdb commands are accessible via menus.
+
+To start the Emacs interface, you first need to put the following
+text in the file @file{.emacs} in your home directory,
+replacing "/usr/local/mercury-1.0" with the directory
+that your Mercury implementation was installed in.
+
+ at example
+(setq load-path (cons (expand-file-name
+  "/usr/local/mercury-1.0/lib/mercury/elisp")
+  load-path))
+(autoload 'mdb "gud" "Invoke the Mercury debugger" t)
+ at end example
+
+Build your program with debugging enabled, as described
+in @ref{Quick overview} or @ref{Preparing a program for debugging}.
+Then start up Emacs, e.g. using the command @samp{emacs},
+and type @kbd{M-x mdb @key{RET}}. Emacs will prompt you for
+the mdb command to invoke; you should type in the name
+of the program that you want to debug and any arguments
+that you want to pass to it:
+
+ at example
+Run mdb (like this): mdb ./hello
+ at end example
+
+Emacs will then create several "buffers": one for the debugger prompt,
+one for the output of the program being executed, and one or more for
+the source files.  By default, Emacs will split the display into two
+parts, called "windows", so that two of these buffers will be visible.
+You can use the command @kbd{C-x o} to switch between windows,
+and you can use the command @kbd{C-x 2} to split a window into two
+windows.  You can use the "Buffers" menu to select which buffer is
+displayed in each window.
+
+If you're using X-Windows, then it is a good idea
+to set the Emacs variable @samp{pop-up-frames} to @samp{t}
+before starting mdb, since this will cause each buffer to be
+displayed in a new "frame" (i.e. a new X window).
+You can set this variable interactively using the
+ at samp{set-variable} command, i.e.
+ at kbd{M-x set-variable @key{RET} pop-up-frames @key{RET} t @key{RET}}.
+Or you can put @samp{(setq pop-up-frames t)} in the @file{.emacs}
+file in your home directory.
+
+For more information on buffers, windows, and frames,
+see the Emacs documentation.
+
+Another useful Emacs variable is @samp{gud-mdb-search-directories}.
+This specifies the list of directories to search for source files.
+You can use a command such as
+ at kbd{M-x set-variable @key{RET}
+gud-mdb-search-directories @key{RET}
+(list "/foo/bar" "../other" "/home/guest") @key{RET}}
+to set it interactively, or you can put a command like
+
+ at example
+(setq gud-mdb-search-directories
+  (list "/foo/bar" "../other" "/home/guest"))
+ at end example
+
+ at noindent
+in your @file{.emacs} file.
+
+At each trace event, the debugger will search for the
+source file corresponding to that event, first in the
+same directory as the program, and then in the directories
+specified by the @samp{gud-mdb-search-directories} variable.
+It will display the source file, with the line number
+corresponding to that trace event marked by
+an arrow (@samp{=>}) at the start of the line.
+
+Several of the debugger features can be accessed by moving
+the cursor to the relevant part of the source code and then
+selecting a command from the menu.
+You can set a break point on a line by moving the cursor to the
+appropriate line in your source code (e.g. with the arrow keys,
+or by clicking the mouse there), and then selecting
+the "Set breakpoint on line" command from the "Breakpoints"
+sub-menu of the "MDB" menu.  You can set a breakpoint on
+a procedure by moving the cursor over the procedure name
+and then selecting the "Set breakpoint on procedure"
+command from the same menu.  And you can display the value of
+a variable by moving the cursor over the variable name
+and then selecting the "Print variable" command from the
+"Data browsing" sub-menu of the "MDB" menu.
+Most of the menu commands also have keyboard short-cuts,
+which are displayed on the menu.
 
 @node Tracing of Mercury programs
 @section Tracing of Mercury programs

-- 
Fergus Henderson <fjh at cs.mu.oz.au>  |  "I have always known that the pursuit
WWW: <http://www.cs.mu.oz.au/~fjh>  |  of excellence is a lethal habit"
PGP: finger fjh at 128.250.37.3        |     -- the last words of T. S. Garp.
--------------------------------------------------------------------------
mercury-developers mailing list
Post messages to:       mercury-developers at cs.mu.oz.au
Administrative Queries: owner-mercury-developers at cs.mu.oz.au
Subscriptions:          mercury-developers-request at cs.mu.oz.au
--------------------------------------------------------------------------