[m-rev.] for review: document the .decldebug grades

[Julien Fischer]

For review by anyone.

Estimated hours taken: 1 (by Ian and myself)
Branches: main, release

Uncomment the documentation for the .decldebug grades.
Add some other documentation about these grades.
This is now necessary because you need to compile in a
.decldebug grade in order to use subterm dependency tracking.

compiler/options.m:
doc/user_guide.texi:
	Document the .decldebug grades.

Julien.

Index: compiler/options.m
===================================================================
RCS file: /home/mercury1/repository/mercury/compiler/options.m,v
retrieving revision 1.448
diff -u -r1.448 options.m
--- compiler/options.m	25 Feb 2005 12:13:04 -0000	1.448
+++ compiler/options.m	3 Mar 2005 05:40:37 -0000
@@ -3110,17 +3110,14 @@
 		"\tSee the Debugging chapter of the Mercury User's Guide",
 		"\tfor details.",
 		"\tThis option is not yet supported for the `--high-level-code'",
+		"\tback-ends.",
+		"--decl-debug\t\t\t\t(grade modifier: `.decldebug')",
+		"\tEnable full support for declarative debugging.",
+		"\tThis allows subterm dependency tracking in the declarative debugger.",
+		"\tSee the Debugging chapter of the Mercury User's Guide",
+		"\tfor details.",
+		"\tThis option is not yet supported for the `--high-level-code'",
 		"\tback-ends."
-% The --decl-debug option is not documented because the .decldebug grade
-% is not installed by default, and because the .decldebug grade is not
-% usefully different from the .debug grade.
-%		"--decl-debug\t\t\t\t(grade modifier: `.decldebug')",
-%		"\tEnable full support for declarative debugging.",
-%		"\tThis ensures that .",
-%		"\tSee the Debugging chapter of the Mercury User's Guide",
-%		"\tfor details.",
-%		"\tThis option is not yet supported for the `--high-level-code'",
-%		"\tback-ends."
 	]),
 	io__write_string("      Profiling\n"),
 	write_tabbed_lines([
Index: doc/user_guide.texi
===================================================================
RCS file: /home/mercury1/repository/mercury/doc/user_guide.texi,v
retrieving revision 1.424
diff -u -r1.424 user_guide.texi
--- doc/user_guide.texi	2 Mar 2005 01:20:17 -0000	1.424
+++ doc/user_guide.texi	3 Mar 2005 06:20:59 -0000
@@ -1218,13 +1218,10 @@
 To use the debugger, you must
 first compile your program with debugging enabled.
 You can do this by using
- at c XXX .decldebug isn't usefully different from .debug
- at c one of the @samp{--debug} and @samp{--decl-debug} options
-the @samp{--debug} option
+one of the @samp{--debug} or @samp{--decl-debug} options
 when invoking @samp{mmc},
 or by including @samp{GRADEFLAGS = --debug}
- at c XXX .decldebug isn't usefully different from .debug
- at c or @samp{GRADEFLAGS = --decl-debug}
+or @samp{GRADEFLAGS = --decl-debug}
 in your @file{Mmakefile}.

 @findex --debug
@@ -1653,12 +1650,10 @@
 Mercury supports two broad ways of preparing a program for debugging.
 The simpler way is to compile a program in a debugging grade,
 which you can do directly by specifying a grade
-that includes the word ``debug'' (e.g.@: @samp{asm_fast.gc.debug}),
- at c XXX .decldebug isn't usefully different from .debug
- at c or indirectly by specifying one of the @samp{--debug} or @samp{--decl-debug}
- at c grade options to the compiler, linker, and other tools
-or indirectly by specifying the @samp{--debug}
-grade option to the compiler, linker, and other tools
+that includes the word ``debug'' or ``decldebug''
+(e.g.@: @samp{asm_fast.gc.debug}, or @samp{asm_fast.gc.decldebug}),
+or indirectly by specifying one of the @samp{--debug} or @samp{--decl-debug}
+grade options to the compiler, linker, and other tools
 (in particular @code{mmc}, @code{mgnuc}, @code{ml}, and @code{c2init}).
 If you follow this way,
 and accept the default settings of the various compiler options
@@ -1667,6 +1662,14 @@
 at every execution point that represents a potential trace event,
 which is very convenient.

+The ``decldebug'' grades improve declarative debugging by tracking
+the source of marked subterms (see @ref{Improving the search}).
+Doing this substantially increases the size of executables so these
+grades should only be used when the subterm dependency tracking feature
+of the declarative debugger is required.
+Note that declarative debugging, with the exception of the subterm dependency
+tracking features, also works in the .debug grades.
+
 The two drawbacks of using a debugging grade
 are the large size of the resulting executables,
 and the fact that often you discover that you need to debug a big program
@@ -1707,10 +1710,7 @@
 to help it avoid asking unnecessary questions,
 so this trace level has the effect of better declarative debugging
 at the cost of increased executable size.
- at c XXX The following line is commented out because we don't currently mention
- at c the effect of this trace level in the declarative debugging section; this
- at c will change when term dependency tracking is documented:
- at c For more details see @ref{Declarative debugging}.
+For more details see @ref{Declarative debugging}.
 @item shallow
 A procedure compiled with trace level @samp{shallow}
 will generate interface events
@@ -3407,12 +3407,7 @@
 failing test run.  Before using the @samp{dice} command one or more passing
 execution summaries and one failing execution summary need to be generated.
 This can be done by compiling the program with deep tracing enabled (either by
-compiling in the .debug
- at c XXX The following line removed until the .decldebug grade has been
- at c documented.
- at c or .decldebug
-grade
-or with the @samp{--trace deep}
+compiling in a .debug or .decldebug grade or with the @samp{--trace deep}
 compiler option) and then running the program with the MERCURY_OPTIONS
 environment variable set to @samp{--trace-count}.
 This will generate a file called @samp{.mercury_trace_counts} which contains a
@@ -4190,7 +4185,7 @@
 searching for a bug.  The mode to use can be specified as an option to the
 @samp{dd} command.  See @ref{Declarative debugging mdb commands} for
 information on how to do this.  The specified search mode will always be used
-unless a sub-term is marked or the user hasn't answered `no' to any questions
+unless a subterm is marked or the user hasn't answered `no' to any questions
 yet (In which case top-down search is used until `no' is answered to at least
 one question).

@@ -4307,6 +4302,12 @@
 Issue a @samp{pd} command at this point to return to the procedural debugger.
 It will now show the final event of the call that bound the term.

+Note that this feature is only available if the executable is compiled
+in a .decldebug grade or with the @samp{--trace rep} option.  If a module
+is compiled with the @samp{--trace rep} option but other modules in the
+program are not then you will not be able to track subterms through those
+other modules.
+
 @subsubsection Trusting predicates, functions and modules

 The declarative debugger can also be told to assume that certain predicates,
@@ -5848,8 +5849,7 @@
 @cindex .agc (grade modifier)
 @cindex .rt (grade modifier)
 @cindex .debug (grade modifier)
- at c XXX .decldebug isn't usefully different from .debug
- at c @cindex .decldebug (grade modifier)
+ at cindex .decldebug (grade modifier)
 @cindex .par (grade modifier)
 @cindex prof (grade modifier)
 @cindex memprof (grade modifier)
@@ -5859,8 +5859,7 @@
 @cindex agc (grade modifier)
 @cindex rt (grade modifier)
 @cindex debug (grade modifier)
- at c XXX .decldebug isn't usefully different from .debug
- at c @cindex decldebug (grade modifier)
+ at cindex decldebug (grade modifier)
 @cindex par (grade modifier)
 @table @asis
 @item What target language to use, what data representation to use, and (for C) what combination of GNU C extensions to use:
@@ -5884,9 +5883,7 @@
 @samp{rt} (the default is no reserved tag)

 @item What debugging features to enable:
- at c XXX .decldebug isn't usefully different from .debug
- at c @samp{debug} and @samp{decldebug} (the default is no debugging features).
- at samp{debug} (the default is no debugging features).
+ at samp{debug} and @samp{decldebug} (the default is no debugging features).

 @item Whether to use a thread-safe version of the runtime environment:
 @samp{par} (the default is a non-thread-safe environment).
@@ -6006,9 +6003,8 @@
 @item @samp{.debug}
 @code{--debug}.

- at c XXX .decldebug isn't usefully different from .debug
- at c @item @samp{.decldebug}
- at c @code{--decl-debug}.
+ at item @samp{.decldebug}
+ at code{--decl-debug}.

 @end table

@@ -6148,16 +6144,13 @@
 that allow the program to be debugged with @samp{mdb} (@pxref{Debugging}).
 This option is not yet supported for the @samp{--high-level-code} back-ends.

- at c XXX .decldebug isn't usefully different from .debug
- at c @sp 1
- at c @item @code{--decl-debug} (grades: any grade containing @samp{.decldebug})
- at c @findex --decl-debug
- at c @cindex Debugging
- at c Enables the inclusion in the executable of code and data structures
- at c that allow the program to be debugged
- at c with the declarative debugging facilities of @samp{mdb}
- at c (@pxref{Debugging}).
- at c This option is not yet supported for the @samp{--high-level-code} back-ends.
+ at sp 1
+ at item @code{--decl-debug} (grades: any grade containing @samp{.decldebug})
+ at findex --decl-debug
+ at cindex Debugging
+Enables the inclusion in the executable of code and data structures
+that allow subterm dependency tracking in the declarative debugger.
+This option is not yet supported for the @samp{--high-level-code} back-ends.

 @sp 1
 @item @code{--profiling}, @code{--time-profiling} (grades: any grade containing @samp{.prof})
--------------------------------------------------------------------------
mercury-reviews mailing list
post:  mercury-reviews at cs.mu.oz.au
administrative address: owner-mercury-reviews at cs.mu.oz.au
unsubscribe: Address: mercury-reviews-request at cs.mu.oz.au Message: unsubscribe
subscribe:   Address: mercury-reviews-request at cs.mu.oz.au Message: subscribe
--------------------------------------------------------------------------