for review: the new debugger command set (part 2 of 5)
Zoltan Somogyi
zs at cs.mu.OZ.AU
Wed Sep 16 18:20:41 AEST 1998
cvs diff: Diffing doc
Index: doc/Mmakefile
===================================================================
RCS file: /home/mercury1/repository/mercury/doc/Mmakefile,v
retrieving revision 1.11
diff -u -u -r1.11 Mmakefile
--- Mmakefile 1998/09/01 05:17:38 1.11
+++ Mmakefile 1998/09/16 04:48:02
@@ -47,7 +47,7 @@
#-----------------------------------------------------------------------------#
.PHONY: all
-all: info dvi html manpages # ps text
+all: info dvi html manpages mdb_doc # ps text
#-----------------------------------------------------------------------------#
@@ -93,6 +93,11 @@
#-----------------------------------------------------------------------------#
+mdb_doc: generate_mdb_doc mercury_user_guide.info mdb_categories
+ ./generate_mdb_doc
+
+#-----------------------------------------------------------------------------#
+
# The following rules automatically build the library documentation
# by extracting the module interfaces from the library source code.
# Note that the debugger_interface.m module is just an implementation
@@ -160,7 +165,7 @@
#-----------------------------------------------------------------------------#
.PHONY: install
-install: install_info install_html install_dvi install_manpages
+install: install_info install_html install_dvi install_manpages install_doc
# install_text install_ps
.PHONY: install_info
@@ -193,6 +198,11 @@
-[ -d $(INSTALL_MAN_DIR)/man1 ] || \
mkdir -p $(INSTALL_MAN_DIR)/man1
cp *.1 $(INSTALL_MAN_DIR)/man1
+
+.PHONY: install_doc
+install_doc: mdbrc mdb_doc
+ -[ -d $(INSTALL_DOC_DIR) ] || mkdir -p $(INSTALL_DOC_DIR)
+ cp mdbrc mdb_doc $(INSTALL_DOC_DIR)
# The uninstall rule here only removes the info files; the others
# are removed by the top-level uninstall rule.
Index: doc/generate_mdb_doc
===================================================================
RCS file: generate_mdb_doc
diff -N generate_mdb_doc
--- /dev/null Wed May 28 10:49:58 1997
+++ generate_mdb_doc Thu Sep 10 15:24:46 1998
@@ -0,0 +1,17 @@
+#!/bin/sh
+
+# the info menu items that get us to the chapter on debugger commands
+cat mdb_categories > mdb_doc
+
+tmp="mdb_doc_tmp.$$"
+trap '/bin/rm -f $tmp' 0 1 2 3 15
+
+info -f mercury_user_guide.info -o $tmp -n "Mercury debugger concepts"
+../util/info_to_mdb concepts $tmp >> mdb_doc
+
+debug_cmd_path="debug debugger"
+for section in forward backward browsing breakpoint parameter help exp developer misc
+do
+ info -f mercury_user_guide.info -o $tmp $debug_cmd_path $section
+ ../util/info_to_mdb $section $tmp >> mdb_doc
+done
Index: doc/mdb_categories
===================================================================
RCS file: mdb_categories
diff -N mdb_categories
--- /dev/null Wed May 28 10:49:58 1997
+++ mdb_categories Wed Sep 9 17:14:31 1998
@@ -0,0 +1,53 @@
+document_category 100 concepts
+concepts - the concepts on which the Mercury debugger is based.
+
+end
+document_category 200 forward
+forward - The commands that move execution forward.
+ The forward commands are step, goto, finish, forward, and continue.
+
+end
+document_category 300 backward
+backward - The commands that move execution backward.
+ The backward command is retry.
+
+end
+document_category 400 browsing
+browse - The commands that let users explore the state of the computation.
+ The browse commands are vars, print, stack, up, down, level,
+ and event.
+
+end
+document_category 500 breakpoint
+breakpoint - The commands that let users set and control breakpoints.
+ The breakpoint commands are break, disable, enable,
+ modules, procedures and register,
+
+end
+document_category 600 parameter
+parameter - The commands that let users access debugger parameters.
+ The params commands are printlevel, echo, scroll, alias and
+ unalias.
+
+end
+document_category 700 help
+help - The commands that let users access and control the help system.
+ The help commands are document_category, document and help.
+
+end
+document_category 800 exp
+exp - The commands that let users collect and inspect experimental
+ data about the behavior of the program. The exp commands are
+ histogram_all, histogram_exp, and clear_histogram.
+
+end
+document_category 900 developer
+developer - The commands that should be of interest to developers only.
+ The developer commands are nondet_stack and stack_regs.
+
+end
+document_category 1000 misc
+misc - The commands that do not fit into other categories.
+ The misc commands are alias, source and quit.
+
+end
Index: doc/mdbrc.in
===================================================================
RCS file: mdbrc.in
diff -N mdbrc.in
--- /dev/null Wed May 28 10:49:58 1997
+++ mdbrc.in Wed Sep 16 15:43:29 1998
@@ -0,0 +1,12 @@
+source @DEFAULT_MERCURY_DEBUGGER_INIT_DIR@/mdb_doc
+alias s step
+alias g goto
+alias f finish
+alias r retry
+alias v vars
+alias p print *
+alias d stack
+alias c continue
+alias b break
+alias h help
+alias ? help
Index: doc/user_guide.texi
===================================================================
RCS file: /home/mercury1/repository/mercury/doc/user_guide.texi,v
retrieving revision 1.134
diff -u -u -r1.134 user_guide.texi
--- user_guide.texi 1998/09/10 06:55:21 1.134
+++ user_guide.texi 1998/09/10 09:57:28
@@ -83,6 +83,7 @@
* Profiling:: The Mercury profiler @samp{mprof}, a tool for analyzing
program performance
* Invocation:: List of options for the Mercury compiler
+* Debugging:: The Mercury debugger @samp{mdb}
* Environment:: Environment variables used by the compiler and utilities
* C compilers:: How to use a C compiler other than GNU C
@end menu
@@ -321,9 +322,8 @@
certain options to the Mercury runtime system.
The Mercury runtime accepts
options via the @samp{MERCURY_OPTIONS} environment variable.
-Setting @samp{MERCURY_OPTIONS} to @samp{-h}
-will list the available options.
The most useful of these are the options that set the size of the stacks.
+(For the full list of available options, see @ref{Environment}.)
The det stack and the nondet stack
are allocated fixed sizes at program start-up.
@@ -984,10 +984,10 @@
modules, so long as the top-level module imports all
the necessary modules. For example:
- @example
- :- module blah.
- :- import_module fee, fie, foe, fum.
- @end example
+ at example
+:- module blah.
+:- import_module fee, fie, foe, fum.
+ at end example
@noindent
This example defines a module @samp{blah}, which has
@@ -1766,13 +1766,26 @@
do not assume the availability of GNU Make extensions.
This makes these files significantly larger.
- at item --trace @var{level}
+ at item --trace-level @var{level}
Generate code that includes the specified level of execution tracing.
The @var{level} should be one of
- at samp{minimum}, @samp{interfaces} and @samp{all}.
- at c XXX should include a pointer here to the as-yet-unwritten
- at c section on debugging
+ at samp{none}, @samp{shallow}, @samp{deep}, and @samp{default}.
+See @ref{Debugging}.
+
+ at item --no-trace-internal
+Do not generate code for internal events even if the trace level is deep.
+
+ at item --no-trace-return
+Do not generate trace information for call return sites.
+Prevents the printing of the values of variables in ancestors
+of the current call.
+
+ at item --no-trace-redo
+Do not generate code for REDO events.
+ at item --trace-optimized
+Do not disable optimizations that can change the trace.
+
@item --generate-bytecode
@c Output a bytecode version of the module
@c into the @file{@var{module}.bytecode} file,
@@ -1782,6 +1795,15 @@
Output a bytecode form of the module for use
by an experimental debugger.
+ at item --generate-bytecode
+ at c Output a bytecode version of the module
+ at c into the @file{@var{module}.bytecode} file,
+ at c and a human-readable version of the bytecode
+ at c into the @file{@var{module}.bytedebug} file.
+ at c The bytecode is for an experimental debugger.
+Output a bytecode form of the module for use
+by an experimental debugger.
+
@item --generate-prolog
Convert the program to Prolog. Output to file @file{@var{module}.pl}
or @file{@var{module}.nl} (depending the the dialect).
@@ -2159,17 +2181,12 @@
@sp 1
@item @code{--debug} (grades: any grade containing @samp{.debug})
-Enable debugging.
-
-To try this out, compile your program with @samp{--debug},
-run @samp{mdb @var{program}}, and then type @samp{h}
-at the @samp{mdb} prompt.
-
-XXX We should document this in more detail.
+Enables the inclusion in the executable of code and data structures
+that allow the program to be debugged with @samp{mdb} (see @ref{Debugging}).
@sp 1
- at item @code{--args @{old, compact@}}
- at item @code{--arg-convention @{old, compact@}}
+ at item @code{--args @{simple, compact@}}
+ at item @code{--arg-convention @{simple, compact@}}
(This option is not intended for general use.)
Use the specified argument passing convention
in the generated low-level C code.
@@ -2752,6 +2769,752 @@
@item --link-object @var{object}
Link with the specified object file.
+ at end table
+
+ at node Debugging
+ at chapter Debugging
+
+ at menu
+* Tracing of Mercury programs::
+* Preparing a program for debugging::
+* Mercury debugger invocation::
+* Mercury debugger concepts::
+* Debugger commands::
+ at end menu
+
+ at node Tracing of Mercury programs
+ at section Tracing of Mercury programs
+
+The Mercury debugger is based on a modified version of the box model
+on which the four-port debuggers of most Prolog systems are based.
+Such debuggers abstract the execution of a program
+into a sequence or @emph{trace} of execution events of various kinds.
+The four kinds of events supported by most Prolog systems (their @emph{ports})
+are
+
+ at table @var
+ at item call events
+A call event occurs just after a procedure has been called,
+and control has just reached the start of the body of the procedure.
+ at item exit events
+An exit event occurs when a procedure call has succeeded,
+and control is about to return to its caller.
+ at item redo events
+A redo event occurs when all computations
+to the right of a procedure call have failed,
+and control is about to return to this call
+to try to find alternative solutions.
+ at item fail events
+A fail event occurs when a procedure call has run out of alternatives,
+and control is about to return to the rightmost computation to its left
+that still has possibly successful alternatives left.
+ at end table
+
+Mercury also supports these four kinds of events,
+but not all events can occur for every procedure call.
+Which events can occur for a procedure call, and in what order,
+depend on the determinism of the procedure.
+The possible event sequences for procedures of the various determinisms
+are as follows.
+
+ at table @var
+ at item nondet procedures
+a call event, zero or more repeats of (exit event, redo event), and a fail event
+ at item multi procedures
+a call event, one or more repeats of (exit event, redo event), and a fail event
+ at item semidet and cc_nondet procedures
+a call event, and either an exit event or a fail event
+ at item det and cc_multi procedures
+a call event and an exit event
+ at item failure procedures
+a call event and a fail event
+ at item erroneous procedures
+a call event
+ at end table
+
+Besides the event types call, exit, redo and fail,
+which describe the @emph{interface} of a call,
+Mercury also supports several types of events
+that report on what is happening @emph{internal} to a call.
+Each of these internal event types has an associated parameter called a path.
+The internal event types are:
+
+ at table @var
+ at item then events
+A then event occurs when execution reaches
+the start of the then part of an if-then-else.
+The path associated with the event specifies which if-then-else this is.
+ at item else events
+An else event occurs when execution reaches
+the start of the else part of an if-then-else.
+The path associated with the event specifies which if-then-else this is.
+ at item disj events
+A disj event occurs when execution reaches
+the start of a disjunct in a disjunction.
+The path associated with the event specifies
+which disjunct of which disjunction this is.
+ at item switch events
+A switch event occurs when execution reaches
+the start of one arm of a switch
+(a disjunction in which each disjunct unifies a bound variable
+with different function symbol).
+The path associated with the event specifies
+which arm of which switch this is.
+ at c @item pragma_first
+ at c @item pragma_later
+ at end table
+
+XXX to be filled in later
+
+ at table @code
+ at item c at var{num}
+The @var{num}'th conjunct of a conjunction.
+ at item d at var{num}
+The @var{num}'th disjunct of a disjunction.
+ at item s at var{num}
+The @var{num}'th arm of a switch.
+ at item ?
+The condition of an if-then-else.
+ at item t
+The then part of an if-then-else.
+ at item e
+The else part of an if-then-else.
+ at item ~
+The goal inside a negation.
+ at item q
+The goal inside an existential quantification.
+ at end table
+
+ at node Preparing a program for debugging
+ at section Preparing a program for debugging
+
+Mercury debugging works by embedding calls to the debugging system
+into the executable code of Mercury procedures,
+at the execution points that represent trace events.
+At each event, the debugging system decides
+whether to give control to the user,
+who can then examine the state of the computation and issue commands,
+or whether to give control back to the executable.
+
+XXX
+Most programs include
+
+XXX
+Programmers can control
+The fewer events are to be traced
+the smaller the size of the executable
+
+ at table @var
+ at item trace level none
+A procedure compiled with trace level none
+will never generate any events.
+ at item trace level deep
+A procedure compiled with trace level deep
+will always generate all the events requested by the user.
+ at item trace level shallow
+A procedure compiled with trace level shallow
+will generate interface events
+if it is called from a procedure compiled with trace level deep,
+while it will generate no events
+if it is called from a procedure compiled with trace level shallow.
+Which way it will behave
+if it is called from a procedure compiled with trace level none
+depends on whether its nearest anscestor whose trace level is not none
+has trace level deep or shallow.
+ at end table
+
+XXX explain --trace
+XXX --debug and not --debug
+
+ at table @var
+ at item --trace minimum
+With --require-tracing, this sets the trace level to shallow;
+with --no-require-tracing, it sets the trace level to none.
+ at item --trace shallow
+This always sets the trace level to shallow.
+ at item --trace deep
+This always sets the trace level to deep.
+ at item --trace default
+With --require-tracing, this sets the trace level to deep;
+with --no-require-tracing, it sets the trace level to none.
+ at end table
+
+c2init -i
+
+ at node Mercury debugger invocation
+ at section Mercury debugger invocation
+
+The executables of Mercury programs
+by default do not invoke the Mercury debugger
+even if some or all of their modules were compiled with some form of tracing,
+and even if the grade of the executable includes @code{debug}.
+This is similar to the behavior of executables
+created by the implementations of other languages;
+for example the executable of a C program compiled with -g
+does not autonomously invoke gdb or dbx etc when it is executed.
+
+ at example
+mdb @var{prog} @var{arg1} ...
+ at end example
+
+ at node Mercury debugger concepts
+ at section Mercury debugger concepts
+
+The operation of the Mercury debugger @samp{mdb}
+is based on the following concepts.
+
+ at table @var
+ at item break points
+The user may associate a break point
+with some events that occur inside a procedure;
+the invocation condition of the break point says which events these are.
+The four possible invocation conditions are:
+ at sp 1
+ at itemize @bullet
+ at item
+the call event,
+ at item
+all interface events,
+ at item
+all events, and
+ at item
+the event at a specific point in the procedure.
+ at end itemize
+ at sp 1
+The effect of a break point depends on the state of the break point.
+ at sp 1
+ at itemize @bullet
+ at item
+If the state of the break point is @samp{stop},
+execution will stop and user interaction will start
+at any event within the procedure that matches the invocation conditions,
+unless the current debugger command has specifically disabled this behavior
+(see the concept @samp{strict commands} below).
+ at sp 1
+ at item
+If the state of the break point is @samp{print},
+the debugger will print any event within the procedure
+that matches the invocation conditions,
+unless the current debugger command has specifically disabled this behavior
+(see the concept @samp{print level} below).
+ at end itemize
+ at sp 1
+Neither of these will happen if the break point is disabled.
+ at sp 1
+ at item strict commands
+When a debugger command steps over some events
+without user interaction at those events,
+the *strictness* of the command controls whether
+the debugger will stop execution and resume user interaction
+at events to which a break point with state @samp{stop} applies.
+By default, the debugger will stop at such events.
+However, if the debugger is executing a strict command,
+it will not stop at an event
+just because a break point in the stop state applies to it.
+ at sp 1
+ at item print level
+When a debugger command steps over some events
+without user interaction at those events,
+the *print level* controls under what circumstances
+the stepped over events will be printed.
+ at sp 1
+ at itemize @bullet
+ at item
+When the print level is @samp{none},
+none of the stepped over events will be printed.
+ at sp 1
+ at item
+When the print level is @samp{all},
+all the stepped over events will be printed.
+ at sp 1
+ at item
+When the print level is @samp{some},
+the debugger will print the event only if a break point applies to the event.
+ at end itemize
+ at sp 1
+Regardless of the print level, the debugger will print
+any event that causes execution to stop and user interaction to start.
+ at sp 1
+ at item default print level
+The debugger maintains a default print level.
+The initial value of this variable is @samp{some},
+but this value can be overridden by the user.
+ at sp 1
+ at item current environment
+Whenever execution stops at an event, the current environment
+is reset to refer to the stack frame of the call specified by the event.
+However, the @samp{up}, @samp{down} and @samp{level} commands can set the current environment
+to refer to one of the ancestors of the current call.
+This will then be the current environment until another of these commands
+changes the environment yet again or execution continues to another event.
+ at sp 1
+ at item procedure specification
+Some debugger commands, e.g. @samp{break},
+require a parameter that specifies a procedure.
+Such a procedure specification has
+the following components in the following order:
+ at itemize @bullet
+ at item
+An optional prefix of the form @samp{pred*} or @samp{func*}
+that specifies whether the procedure belongs to a predicate or a function.
+ at item
+An optional prefix of the form @samp{@var{module}:} or @samp{@var{module}__}
+that specifies the name of the module that defines
+the predicate or function to which the procedure belongs.
+ at item
+The name of the predicate or function to which the procedure belongs.
+ at item
+An optional suffix of the form @samp{/@var{arity}}
+that specifies the arity of the predicate or function
+to which the procedure belongs.
+ at item
+An optional suffix of the form @samp{- at var{modenum}}
+that specifies the mode number of the procedure
+within the predicate or function to which the procedure belongs.
+ at end itemize
+ at c @sp 1
+ at c XXX interrupts:
+ at c If the debugger recieves an interrupt, it will stop at the next event
+ at c regardless of what command it is executing at the time.
+ at c (INTERRUPT HANDLING IS NOT YET IMPLEMENTED.)
+ at end table
+
+ at node Debugger commands
+ at section Debugger commands
+
+When the debugger (as opposed to the program being debugged) is interacting
+with the user, the debugger prints a prompt and reads in a line of text,
+which it will interpret as its next command. Each command line consists
+of several words separated by white space. The first word is the name of
+the command, while any other words give options and/or parameters to the
+command.
+
+Some commands take a number as their first parameter.
+For such commands, users can type `@var{number} @var{command}'
+as well as `@var{command} @var{number}'.
+The debugger will internally transform the former into the latter,
+even if the number and the command are not separated by white space.
+
+ at menu
+* Forward movement commands::
+* Backward movement commands::
+* Browsing commands::
+* Breakpoint commands::
+* Parameter commands::
+* Help commands::
+* Experimental commands::
+* Developer commands::
+* Miscellaneous commands::
+ at end menu
+
+ at node Forward movement commands
+ at subsection Forward movement commands
+
+ at table @code
+ at item step [-NSans] [@var{num}]
+Steps forward @var{num} events.
+If this command is given at event @var{cur}, continues execution until
+event @var{cur} + @var{num}. The default value of @var{num} is 1.
+ at sp 1
+The options @samp{-n} or @samp{--none}, @samp{-s} or @samp{--some},
+ at samp{-a} or @samp{--all} specify the print level to use
+for the duration of the command,
+while the options @samp{-S} or @samp{--strict}
+and @samp{-N} or @samp{--nostrict} specify
+the strictness of the command.
+ at sp 1
+By default, this command is not strict, and it uses the default print level.
+ at sp 1
+A command line containing only a number @var{num} is interpreted as
+if it were `step @var{num}'.
+ at sp 1
+An empty command line is interpreted as `step 1'.
+ at sp 1
+ at item goto [-NSans] @var{num}
+Continues execution until the program reaches event number @var{num}.
+If the current event number is larger than @var{num}, it reports an error.
+ at sp 1
+The options @samp{-n} or @samp{--none}, @samp{-s} or @samp{--some},
+ at samp{-a} or @samp{--all} specify the print level to use
+for the duration of the command,
+while the options @samp{-S} or @samp{--strict}
+and @samp{-N} or @samp{--nostrict} specify
+the strictness of the command.
+ at sp 1
+By default, this command is strict, and it uses the default print level.
+ at sp 1
+ at item finish [-NSans] [@var{num}]
+Continues execution until it reaches a final (EXIT or FAIL) port of
+the @var{num}'th ancestor of the call to which the current event refers.
+The default value of @var{num} is zero,
+which means skipping to the end of the current call.
+Reports an error if execution is already at the desired port.
+ at sp 1
+The options @samp{-n} or @samp{--none}, @samp{-s} or @samp{--some},
+ at samp{-a} or @samp{--all} specify the print level to use
+for the duration of the command,
+while the options @samp{-S} or @samp{--strict}
+and @samp{-N} or @samp{--nostrict} specify
+the strictness of the command.
+ at sp 1
+By default, this command is strict, and it uses the default print level.
+ at sp 1
+ at item forward [-NSans]
+Continues the program until the program resumes forward execution,
+i.e. until it reaches a non-final port inside any predicate. Reports
+an error if the current event refers to a non-final port.
+ at sp 1
+The options @samp{-n} or @samp{--none}, @samp{-s} or @samp{--some},
+ at samp{-a} or @samp{--all} specify the print level to use
+for the duration of the command,
+while the options @samp{-S} or @samp{--strict}
+and @samp{-N} or @samp{--nostrict} specify
+the strictness of the command.
+ at sp 1
+By default, this command is strict, and it uses the default print level.
+ at sp 1
+ at item continue [-NSans]
+Continues execution until it reaches the end of the program.
+ at sp 1
+The options @samp{-n} or @samp{--none}, @samp{-s} or @samp{--some},
+ at samp{-a} or @samp{--all} specify the print level to use
+for the duration of the command,
+while the options @samp{-S} or @samp{--strict}
+and @samp{-N} or @samp{--nostrict} specify
+the strictness of the command.
+ at sp 1
+By default, this command is not strict. The print level used
+by the command by default depends on the final strictness level:
+if the command is strict, it is @samp{none}, otherwise it is @samp{some}.
+ at end table
+ at sp 1
+ at node Backward movement commands
+ at subsection Backward movement commands
+ at sp 1
+ at table @code
+ at item retry
+Restarts execution at the call port
+of the call corresponding to the current event.
+ at sp 1
+The command will report an error unless
+the values of all the input arguments are available at the current port.
+(The compiler will keep the values
+of the input arguments of traced predicates as long as possible,
+but it cannot keep them beyond the point where they are destructively updated.)
+ at c XXX THE EXCEPTION IS NOT YET IMPLEMENTED.
+ at c The exception is values of type `io__state';
+ at c the debugger can perform a retry if the only missing value is of
+ at c type `io__state' (there can be only one io__state at any given time).
+ at c @sp 1
+ at c A retry in which the values of all input arguments are available
+ at c works fine, provided that the predicates defined in C code that are
+ at c called inside the repeated computation do not pose any problems.
+ at c A retry in which a value of type `io__state' is missing has the
+ at c following effects:
+ at c @sp 1
+ at c @itemize @bullet
+ at c @item
+ at c Any input and/or output actions in the repeated code will be repeated.
+ at c @item
+ at c Any file close actions in the repeated code
+ at c for which the corresponding file open action is not also in the repeated code
+ at c may cause later I/O actions referring to the file to fail.
+ at c @item
+ at c Any file open actions in the repeated code
+ at c for which the corresponding file close action
+ at c is not also in the repeated code
+ at c may cause later file open actions to fail due to file descriptor leak.
+ at c @end itemize
+ at sp 1
+The debugger can perform a retry only from an exit or fail port;
+only at these ports does the debugger have enough information
+to figure out how to reset the stacks.
+If the debugger is not at such a port when a retry command is given,
+the debugger will continue forward execution
+until it reaches an exit or fail port of the call to be retries
+before it performs the retry.
+This may require a noticeable amount of time.
+ at c XXX not yet
+ at c and may result in the execution of I/O and/or other side-effects.
+ at sp 1
+ at item retry @var{num}
+Restarts execution at the call port of the call corresponding to
+the @var{num}'th ancestor of the call to which the current event belongs.
+For example, if @var{num} is 1, it restarts the parent of the current call.
+ at end table
+ at sp 1
+ at node Browsing commands
+ at subsection Browsing commands
+ at sp 1
+ at table @code
+ at item vars
+Prints the names of all the known variables in the current environment,
+together with an ordinal number for each variable.
+ at sp 1
+ at item print @var{num}
+Prints the value of the variable with the given ordinal number
+in the current environment.
+ at sp 1
+At the moment this command prints the entire value of the variable,
+even if this is very big. Later it will merely invoke a configurable
+dynamic term browser, which will eventually have its own sublanguage.
+ at sp 1
+ at item print *
+Prints the values of all the known variables in the current environment.
+ at sp 1
+At the moment this command prints the entire value of every variable,
+even if this is very big. Later it will merely invoke a configurable
+dynamic term browser, which will eventually have its own sublanguage.
+ at sp 1
+ at item stack
+Prints the names of the ancestors of the call specified by the
+current event. If two or more ancestor calls are for the same
+predicate, the procedure identification will be printed once
+with the appropriate multiplicity annotation.
+ at sp 1
+This command will report an error if there is no stack trace
+information available about any ancestor.
+ at sp 1
+ at item up [@var{num}]
+Sets the current environment to the stack frame
+of the @var{num}'th level ancestor of the current environment
+(the immediate caller is the first-level ancestor).
+ at sp 1
+If @var{num} is not specified, the default value is one.
+ at sp 1
+This command will report an error
+if the current environment doesn't have the required number of ancestors,
+or if there is no execution trace information about the requested ancestor,
+or if there is no stack trace information about any of the ancestors
+between the current environment and the requested ancestor.
+ at sp 1
+ at item down [@var{num}]
+Sets the current environment to the stack frame
+of the @var{num}'th level descendant of the current environment
+(the immediate caller is the first-level ancestor).
+ at sp 1
+If @var{num} is not specified, the default value is one.
+ at sp 1
+This command will report an error if the current environment
+doesn't have the required number of descendants.
+ at sp 1
+ at item level [@var{num}]
+Sets the current environment to the stack frame of the @var{num}'th
+level ancestor of the call to which the current event belongs.
+The zero'th ancestor is the call of the event itself.
+ at sp 1
+ at item current
+Prints the current event.
+This is useful if the details of the event,
+which were printed when control arrived at the event,
+have since scrolled off the screen.
+ at end table
+ at sp 1
+ at node Breakpoint commands
+ at subsection Breakpoint commands
+ at sp 1
+ at table @code
+ at item break [-PSaei] @var{proc_spec}
+ at c <module name> <predicate name> [<arity> [<mode> [<predfunc>]]]
+Puts a break point on the specified procedure.
+ at sp 1
+The options @samp{-P} or @samp{--print}, and @samp{-S} or @samp{--stop}
+specify the action to be taken at the break point,
+while the options @samp{-a} or @samp{--all},
+ at samp{-e} or @samp{--entry}, and @samp{-i} or @samp{--interface}
+specify the invocation conditions of the break point.
+ at sp 1
+By default, the action of the break point is @samp{stop},
+and its invocation condition is @samp{interface}.
+ at sp 1
+ at item break [-PS] here
+Puts a break point on the procedure referred to by the current event,
+with the invocation condition being the event at the current location
+in the procedure body.
+ at sp 1
+The options @samp{-P} or @samp{--print}, and @samp{-S} or @samp{--stop}
+specify the action to be taken at the break point.
+ at sp 1
+By default, the initial state of the break point is @samp{stop}.
+ at sp 1
+ at item break info
+Lists the details and status of all break points.
+ at sp 1
+ at item disable @var{num}
+Disables the break point with the given number.
+Reports an error if there is no break point with that number.
+ at sp 1
+ at item disable *
+Disables all break points.
+ at sp 1
+ at item enable @var{num}
+Enables the break point with the given number.
+Reports an error if there is no break point with that number.
+ at sp 1
+ at item enable *
+Enables all break points.
+ at sp 1
+ at item modules
+Lists all the debuggable modules
+(i.e. modules that have debugging information).
+ at sp 1
+ at item procedures @var{module}
+Lists all the procedures in the debuggable module @var{module}.
+ at sp 1
+ at item register
+Registers all debuggable modules with the debugger.
+Has no effect if this registration has already been done.
+The debugger will perform this registration when creating breakpoints
+and when listing debuggable modules and/or procedures.
+ at end table
+ at sp 1
+ at node Parameter commands
+ at subsection Parameter commands
+ at sp 1
+ at table @code
+ at item printlevel none
+Sets the default print level to @samp{none}.
+ at sp 1
+ at item printlevel some
+Sets the default print level to @samp{some}.
+ at sp 1
+ at item printlevel all
+Sets the default print level to @samp{all}.
+ at sp 1
+ at item printlevel
+Reports the current default print level.
+ at sp 1
+ at item echo on
+Turns on the echoing of commands.
+ at sp 1
+ at item echo off
+Turns off the echoing of commands.
+ at sp 1
+ at item echo
+Reports whether commands are being echoed or not.
+ at sp 1
+ at item scroll on
+Turns on user control over the scrolling of sequences of event reports.
+This means that every screenful of event reports
+will be followed by a --more-- prompt.
+You may type an empty line, which allows the debugger
+to continue to print the next screenful of event reports.
+By typing a line that starts with @samp{a}, @samp{s} or @samp{n},
+you can override the print level of the current command,
+setting it to @samp{all}, @samp{some} or @samp{none} respectively.
+By typing a line that starts with @samp{q},
+you can abort the current debugger command
+and get back control at the next event.
+ at sp 1
+ at item scroll off
+Turns off user control over the scrolling of sequences of event reports.
+ at sp 1
+ at item scroll @var{size}
+Sets the scroll window size to @var{size},
+which tells scroll control to stop and print a --more-- prompt
+after every @var{size - 1} events.
+The default value of @var{size} is the value of the LINES environment variable,
+which should correspond to the number of lines available on the terminal.
+ at sp 1
+ at item scroll
+Reports whether user scroll control is enabled and what the window size is.
+ at sp 1
+ at item alias @var{name} @var{command} [@var{command_parameter} ...]
+Introduces @var{name} as an alias
+for the given command with the given parameters.
+Whenever a command line has @var{name} as its first word,
+the debugger will substitute the given command and parameters for this word
+before executing the command line.
+ at sp 1
+If @var{command} is the upper-case word @samp{EMPTY},
+the debugger will substitute the given command and parameters
+whenever the user types in an empty command line.
+ at sp 1
+ at sp 1
+If @var{command} is the upper-case word @samp{NUMBER},
+the debugger will insert the given command and parameters
+before the command line
+whenever the user types in a command line that consists of a single number.
+ at sp 1
+ at item unalias @var{name}
+Removes any existing alias for @var{name}.
+ at end table
+ at sp 1
+ at node Help commands
+ at subsection Help commands
+ at sp 1
+ at table @code
+ at item document_category @var{slot} @var{category}
+Create a new category of help items, named @var{category}.
+The summary text for the category is given by the lines following this command,
+up to but not including a line containing only the lower-case word @samp{end}.
+The list of category summaries printed in response to the command @samp{help}
+is ordered on the integer @var{slot} numbers of the categories involved.
+ at sp 1
+ at item document @var{category} @var{slot} @var{item}
+Create a new help item named @var{item} in the help category @var{category}.
+The text for the help item is given by the lines following this command,
+up to but not including a line containing only the lower-case word @samp{end}.
+The list of items printed in response to the command @samp{help @var{category}}
+is ordered on the integer @var{slot} numbers of the items involved.
+ at sp 1
+ at item help @var{category} @var{item}
+Prints help text about the item @var{item} in category @var{category}.
+ at sp 1
+ at item help @var{word}
+Prints help text about @var{word},
+which may be the name of a help category or a help item.
+ at sp 1
+ at item help
+Prints summary information about all the available help categories.
+ at end table
+ at sp 1
+ at node Experimental commands
+ at subsection Experimental commands
+ at sp 1
+ at table @code
+ at item histogram_all @var{filename}
+Prints (to file @var{filename})
+a histogram that counts all events at various depths
+since the start of the program.
+This histogram is available
+only in some experimental versions of the Mercury runtime system.
+ at sp 1
+ at item histogram_exp @var{filename}
+Prints (to file @var{filename})
+a histogram that counts all events at various depths
+since the start of the program or since the histogram was last cleared.
+This histogram is available
+only in some experimental versions of the Mercury runtime system.
+ at sp 1
+ at item clear_histogram
+Clears the histogram printed by @samp{histogram_exp},
+i.e. sets the counts for all depths to zero.
+ at end table
+ at node Developer commands
+ at subsection Developer commands
+ at sp 1
+ at table @code
+ at item nondet_stack
+Prints the contents of the fixed slots of the frames on the nondet stack.
+ at sp 1
+ at item stack_regs
+Prints the contents of the virtual machine registers
+that point to the det and nondet stacks.
+ at end table
+ at node Miscellaneous commands
+ at subsection Miscellaneous commands
+ at sp 1
+ at table @code
+ at item source @var{filename}
+Executes the commands in the file named @var{filename}.
+ at sp 1
+ at item quit [-y]
+Quits the debugger and aborts the execution of the program.
+If the option @samp{-y} is not present, asks for confirmation first.
+Any answer starting with @samp{y}, or end-of-file, is considered confirmation.
+ at sp 1
+End-of-file on the debugger's input is considered a quit command.
@end table
@node Environment
cvs diff: Diffing extras
cvs diff: Diffing extras/cgi
cvs diff: Diffing extras/complex_numbers
cvs diff: Diffing extras/complex_numbers/samples
cvs diff: Diffing extras/complex_numbers/tests
cvs diff: Diffing extras/exceptions
cvs diff: Diffing extras/graphics
cvs diff: Diffing extras/graphics/Togl-1.2
cvs diff: Diffing extras/graphics/mercury_opengl
cvs diff: Diffing extras/graphics/mercury_tcltk
cvs diff: Diffing extras/graphics/samples
cvs diff: Diffing extras/graphics/samples/calc
cvs diff: Diffing extras/graphics/samples/maze
cvs diff: Diffing extras/graphics/samples/pent
cvs diff: Diffing extras/odbc
cvs diff: Diffing extras/references
cvs diff: Diffing extras/references/samples
cvs diff: Diffing extras/references/tests
cvs diff: Diffing extras/trailed_update
cvs diff: Diffing extras/trailed_update/samples
cvs diff: Diffing extras/trailed_update/tests
cvs diff: Diffing library
Index: library/io.m
===================================================================
RCS file: /home/mercury1/repository/mercury/library/io.m,v
retrieving revision 1.163
diff -u -u -r1.163 io.m
--- io.m 1998/09/09 06:05:07 1.163
+++ io.m 1998/09/10 09:35:57
@@ -1736,11 +1736,15 @@
io__write_float(Stream, F),
io__write_many(Stream, Rest).
+:- pragma export(io__print(in, in, di, uo), "ML_io_print_to_stream").
+
io__print(Stream, Term) -->
io__set_output_stream(Stream, OrigStream),
io__print(Term),
io__set_output_stream(OrigStream, _Stream).
+:- pragma export(io__print(in, di, uo), "ML_io_print_to_cur_stream").
+
io__print(Term) -->
% `string', `char' and `univ' are special cases for io__print
{ type_to_univ(Term, Univ) },
@@ -2833,6 +2837,10 @@
}").
/* stream predicates */
+
+:- pragma export(io__stdin_stream(out, di, uo), "ML_io_stdin_stream").
+:- pragma export(io__stdout_stream(out, di, uo), "ML_io_stdout_stream").
+:- pragma export(io__stderr_stream(out, di, uo), "ML_io_stderr_stream").
:- pragma c_code(io__stdin_stream(Stream::out, IO0::di, IO::uo),
[will_not_call_mercury, thread_safe], "
Index: library/library.m
===================================================================
RCS file: /home/mercury1/repository/mercury/library/library.m,v
retrieving revision 1.41
diff -u -u -r1.41 library.m
--- library.m 1998/04/15 06:48:17 1.41
+++ library.m 1998/09/10 09:41:10
@@ -32,7 +32,7 @@
:- import_module std_util, string, term, term_io, tree234, varset.
:- import_module store, rbtree, parser, lexer, ops.
:- import_module prolog.
-:- import_module debugger_interface.
+:- import_module help, debugger_interface.
:- import_module integer, rational.
% library__version must be implemented using pragma c_code,
Index: library/std_util.m
===================================================================
RCS file: /home/mercury1/repository/mercury/library/std_util.m,v
retrieving revision 1.129
diff -u -u -r1.129 std_util.m
--- std_util.m 1998/09/04 11:26:06 1.129
+++ std_util.m 1998/09/15 08:22:49
@@ -489,26 +489,53 @@
Declare_label(mercury__std_util__builtin_aggregate_4_0_i1);
Declare_label(mercury__std_util__builtin_aggregate_4_0_i2);
Declare_label(mercury__std_util__builtin_aggregate_4_0_i3);
-MR_MAKE_STACK_LAYOUT_ENTRY(mercury__std_util__builtin_aggregate_4_0);
-MR_MAKE_STACK_LAYOUT_ENTRY(mercury__std_util__builtin_aggregate_4_1);
-MR_MAKE_STACK_LAYOUT_ENTRY(mercury__std_util__builtin_aggregate_4_2);
-MR_MAKE_STACK_LAYOUT_ENTRY(mercury__std_util__builtin_aggregate_4_3);
-MR_MAKE_STACK_LAYOUT_ENTRY(mercury__std_util__builtin_aggregate_4_4);
-MR_MAKE_STACK_LAYOUT_ENTRY(mercury__std_util__builtin_aggregate_4_5);
-MR_MAKE_STACK_LAYOUT_INTERNAL(mercury__std_util__builtin_aggregate_4_0, 1);
-MR_MAKE_STACK_LAYOUT_INTERNAL(mercury__std_util__builtin_aggregate_4_0, 2);
-MR_MAKE_STACK_LAYOUT_INTERNAL(mercury__std_util__builtin_aggregate_4_0, 3);
+#ifndef CONSERVATIVE_GC
+ #ifdef MR_USE_TRAIL
+ #define num_framevars 7
+ #else
+ #define num_framevars 6
+ #endif
+#else
+ #ifdef MR_USE_TRAIL
+ #define num_framevars 3
+ #else
+ #define num_framevars 2
+ #endif
+#endif
+
+const struct MR_Stack_Layout_Entry_Struct
+mercury_data__layout__mercury__std_util__builtin_aggregate_4_0 = {
+ STATIC(mercury__std_util__builtin_aggregate_4_0),
+ MR_DETISM_MULTI, /* We must lie because even though the pred */
+ /* is det, it lives on the nondet stack. */
+ num_framevars,
+ -1,
+
+ MR_PREDICATE,
+ ""std_util"",
+ ""std_util"",
+ ""builtin_aggregate"",
+ 4,
+ 0,
+
+ NULL
+};
+
+MR_DEFINE_STACK_LAYOUT_INTERNAL(mercury__std_util__builtin_aggregate_4_0, 1);
+MR_DEFINE_STACK_LAYOUT_INTERNAL(mercury__std_util__builtin_aggregate_4_0, 2);
+MR_DEFINE_STACK_LAYOUT_INTERNAL(mercury__std_util__builtin_aggregate_4_0, 3);
+
BEGIN_MODULE(builtin_aggregate_module)
- init_entry_sl(mercury__std_util__builtin_aggregate_4_0);
- init_entry_sl(mercury__std_util__builtin_aggregate_4_1);
- init_entry_sl(mercury__std_util__builtin_aggregate_4_2);
- init_entry_sl(mercury__std_util__builtin_aggregate_4_3);
- init_entry_sl(mercury__std_util__builtin_aggregate_4_4);
- init_entry_sl(mercury__std_util__builtin_aggregate_4_5);
- init_label_sl(mercury__std_util__builtin_aggregate_4_0_i1);
- init_label_sl(mercury__std_util__builtin_aggregate_4_0_i2);
- init_label_sl(mercury__std_util__builtin_aggregate_4_0_i3);
+ MR_always_init_entry_asl(mercury__std_util__builtin_aggregate_4_0);
+ init_entry(mercury__std_util__builtin_aggregate_4_1);
+ init_entry(mercury__std_util__builtin_aggregate_4_2);
+ init_entry(mercury__std_util__builtin_aggregate_4_3);
+ init_entry(mercury__std_util__builtin_aggregate_4_4);
+ init_entry(mercury__std_util__builtin_aggregate_4_5);
+ MR_always_init_label_asl(mercury__std_util__builtin_aggregate_4_0_i1);
+ MR_always_init_label_asl(mercury__std_util__builtin_aggregate_4_0_i2);
+ MR_always_init_label_asl(mercury__std_util__builtin_aggregate_4_0_i3);
BEGIN_CODE
/*
@@ -566,7 +593,7 @@
/*
** In order to implement any sort of code that requires terms to survive
** backtracking, we need to (deeply) copy them out of the heap and into some
-** other area before backtracking. The obious thing to do then is just call
+** other area before backtracking. The obvious thing to do then is just call
** the generator predicate, let it run to completion, and copy its result into
** another memory area (call it the solutions heap) before forcing
** backtracking. When we get the next solution, we do the same, this time
@@ -624,17 +651,15 @@
** Finally, we store the collection of solutions so far in sofar_fv.
*/
-#define saved_hp_fv (framevar(0))
-#define saved_solhp_fv (framevar(1))
-#define collector_pred_fv (framevar(2))
-#define sofar_fv (framevar(3))
-#define element_type_info_fv (framevar(4))
-#define collection_type_info_fv (framevar(5))
+/* This must be kept in sync with the definition of num_framevars above. */
+#define saved_hp_fv (MR_framevar(1))
+#define saved_solhp_fv (MR_framevar(2))
+#define collector_pred_fv (MR_framevar(3))
+#define sofar_fv (MR_framevar(4))
+#define element_type_info_fv (MR_framevar(5))
+#define collection_type_info_fv (MR_framevar(6))
#ifdef MR_USE_TRAIL
- #define saved_trail_ticket_fv (framevar(6))
- #define num_framevars 7
-#else
- #define num_framevars 6
+ #define saved_trail_ticket_fv (MR_framevar(7))
#endif
/*
@@ -771,7 +796,6 @@
#undef sofar_fv
#undef element_type_info_fv
#undef collection_type_info_fv
-#undef num_framevars
#else
@@ -783,13 +807,11 @@
** make deep copies of the solutions. This is a `copy-zero' implementation ;-)
*/
-#define collector_pred_fv (framevar(0))
-#define sofar_fv (framevar(1))
+/* This must be kept in sync with the definition of num_framevars above. */
+#define collector_pred_fv (MR_framevar(1))
+#define sofar_fv (MR_framevar(2))
#ifdef MR_USE_TRAIL
- #define saved_trail_ticket_fv (framevar(2))
- #define num_framevars 3
-#else
- #define num_framevars 2
+ #define saved_trail_ticket_fv (MR_framevar(3))
#endif
/* create a nondet stack frame with two slots, to hold the collector
@@ -871,15 +893,15 @@
#undef collector_pred_fv
#undef sofar_fv
-#undef num_framevars
#endif
-
+
+END_MODULE
+
+#undef num_framevars
#undef builtin_aggregate_output
#undef swap_heap_and_solutions_heap
-END_MODULE
-
/* Ensure that the initialization code for the above module gets run. */
/*
INIT sys_init_builtin_aggregate_module
cvs diff: Diffing lp_solve
cvs diff: Diffing lp_solve/lp_examples
cvs diff: Diffing profiler
More information about the developers
mailing list