[m-rev.] for review: document coverage testing

Ian MacLarty maclarty at csse.unimelb.edu.au
Mon Sep 25 16:56:32 AEST 2006


On Mon, Sep 25, 2006 at 12:01:21PM +1000, Zoltan Somogyi wrote:
> For review by Ian. The test case for coverage testing will come after this
> diff is committed.
> 
> Zoltan.
> 
> Document my recent change implementing coverage testing. At the same time,
> eliminate the old hack that allowed a file containing a list of file names to
> be considered a trace count file. We haven't needed it since the addition of
> mtc_union, and it can lead to incomprensible error messages. (The presence
> of the old hack made documenting coverage testing harder.)
> 
...
> Index: doc/user_guide.texi
> ===================================================================
>  @node Trace counts
>  @section Trace counts
>  
> -A program with debugging enabled may be run in a special mode that causes it
> -to write out a summary of its execution to a file.
> -This summary is called a @emph{trace count} or @emph{slice}.
> -A slice is a record of how many times each @emph{label} in the program was
> -executed for a particular run.
> -A label is a point in the source code where a debugger event,
> -such as CALL or EXIT,
> -can be triggered.
> -
> -Slices are useful for determining what parts of a failing program are being run
> -and possibly causing the failure.
> -Slices from failing and passing runs can be compared to see which parts of the
> -program are being run in the failing runs,
> -but not the passing runs.
> +A program with debugging enabled may be run in a special mode
> +that causes it to write out to a @emph{trace count file}
> +a record of how many times each @emph{debugger event} in the program
> +was executed during that run.

I introduced the term "label" and used that instead of "debugger event",
since I thought using the term "event" would be misleading.  The
same label may generate two different events, with different event
numbers.  The trace count feature counts the number of times the
label was executed, not how may times each event was executed (each
event is always executed exactly once in the absence of retries).

I therefore think it'd be better to keep the definition of the term
"label" and use that to describe what the trace counts are counting.

...

> + at samp{mtc_diff} is invoked by issuing a command of the form:
> + at sp 1
> + at example
> +mtc_diff -o output_file file1 file2
> + at end example
> + at sp 1
> + at samp{file1} and @samp{file2} must both be trace counts files.
> +The output, written to @samp{output_file}, will contain
> +the difference between the trace counts in @samp{file1} and @samp{file2}
> +for every event that occurs in @samp{file1}.
> +Unlike @samp{mtc_union}, @samp{mtc_diff} does not preserve
> +

You're missing some text here.

...

> @@ -4778,18 +4837,19 @@
>  @item @samp{Procedure}:
>  This column displays the procedure that the label relates to.
>  @item @samp{Path/Port}:
> -For labels that generate interface events this column displays          
> -the event port and for labels that generate internal events it          
> -displays the goal path. (See @ref{Tracing of Mercury programs} for an
> -explanation of interface and internal events.)
> +For labels that generate interface events this column displays the event port,
> +while for labels that generate internal events it displays the goal path.
> +(See @ref{Tracing of Mercury programs} for an explanation
> +of interface and internal events.)

You must definitely keep the definition of label if you're going to use
that term here.

...
> -For example the string "SF" means sort the table by suspicion in descending
> -order, and if any two suspicions are the same, then by number of executions in
> -the failing run(s), also in descending order.
> - at sp 1
> -The option @samp{-l} or @samp{--limit} can be used to limit the number of lines
> -displayed.
> - at sp 1
> -The @samp{-m} or @samp{--module} option limits the output to the given module
> -and any submodules.
> +For example the string "SF" means
> +sort the table by suspicion in descending order,
> +and if any two suspicions are the same,
> +then by number of executions in the failing run(s), also in descending order.
> + at sp 1
> +The option @samp{-l} or @samp{--limit}
> +can be used to limit the number of lines displayed.
> + at sp 1
> +The @samp{-m} or @samp{--module} option
> +limits the output to the given module and any submodules.
> +the count of the test cases that contributed to its contents in any useful way.

The text above seems out of place.

...
>  @sp 1
>  @example
> -mtc_union [-v] -o output_file file1 file2 ...
> +mcov [-d] [-v] [-o output_file] tracecountfile1 ...
>  @end example
> +The arguments consist of one or more trace count files.
> +The output will normally be a list of all the procedures in the program
> +that were not executed in any of the runs
> +that generated these trace count files.
> +The output will go to standard output
> +unless this is overridden by the @samp{-o} or @samp{--output-file} option.
> + at sp 1
> +If the @samp{-d} or @samp{--detailed} option is specified,
> +then the the output will list all the @emph{events} in the program
> +that were not executed in any of these runs.

Again I'd use the term "labels" instead of "events" here and elsewhere.

...

> Index: mdbcomp/trace_counts.m
> ===================================================================
> RCS file: /home/mercury/mercury1/repository/mercury/mdbcomp/trace_counts.m,v
> retrieving revision 1.13
> diff -u -b -r1.13 trace_counts.m
> --- mdbcomp/trace_counts.m	22 Sep 2006 03:50:45 -0000	1.13
> +++ mdbcomp/trace_counts.m	22 Sep 2006 04:59:33 -0000
> @@ -126,37 +126,15 @@
>  :- pred read_trace_counts_list(bool::in, string::in,
>      read_trace_counts_list_result::out, io::di, io::uo) is det.
>  
> -:- type slice_source
> -    --->    file_list
> -    ;       single_file
> -    ;       try_single_first.
> -
> -    % read_trace_counts_source(ShowProgress, Source, FileName, Result, !IO):
> -    %
> -    % Read in trace counts stored in one or more trace count files.
> -    %
> -    % If Source is file_list, then FileName should contain a list of filenames,
> -    % and read_trace_counts_source will read in the trace counts from each
> -    % of those files.
> -    %
> -    % If Source is single_file, then FileName should itself be a file
> -    % containing trace counts data.
> -    %
> -    % If Source is try_single_first, then read_trace_counts_source will
> -    % check to see if FileName contains trace counts data. If yes, it will
> -    % get trace counts from there. If not, read_trace_counts_source will
> -    % interpret FileName as a file that itself contains filenames, and
> -    % will treat it as with Source=file_list.
> +    % read_trace_counts_source(FileName, Result, !IO):
>      %
> -    % If the source is a list of files and ShowProgress is yes then
> -    % the name of each file read will be printed to the current output
> -    % stream just before it is read.
> +    % Read in trace counts stored in one a given trace count file.

Delete "one".

That looks fine otherwise.

I am planning on removing the dice mdb command, since if you want to
view a dice from within mdb you can always use the shell command with
mdice.  Do you have any objections to me removing the dice command?

Ian.
--------------------------------------------------------------------------
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