X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=docs%2Fusers_guide%2Fprofiling.xml;fp=docs%2Fusers_guide%2Fprofiling.xml;h=d93080c5e187fa41942d08f5be5508efdc93610c;hb=478c200d59021e15a713f769eb6f6148e5183ba4;hp=76e4bcf5cf6b03e3a59fab83ba3cd89c1ab58628;hpb=6ff4beae14211e6078b2845f52b2220d72a52228;p=ghc-hetmet.git
diff --git a/docs/users_guide/profiling.xml b/docs/users_guide/profiling.xml
index 76e4bcf..d93080c 100644
--- a/docs/users_guide/profiling.xml
+++ b/docs/users_guide/profiling.xml
@@ -1260,26 +1260,25 @@ to re-read its input file:
never actually been invoked. GHC has an option for generating
instrumented code that records code coverage as part of the
Haskell Program Coverage
- (HPC) toolkit. HPC tools can be used to render the
- outputed code coverage infomation into human understandable
- format.
-
+ (HPC) toolkit, which is included with GHC. HPC tools can
+ be used to render the generated code coverage information into
+ human understandable format.
- HPC provides coverage information of two kinds: source coverage
- and boolean-control coverage. Source coverage is the extent to
- which every part of the program was used, measured at three
- different levels: declarations (both top-level and local),
- alternatives (among several equations or case branches) and
- expressions (at every level). Boolean coverage is the extent to
- which each of the values True and False is obtained in every
- syntactic boolean context (ie. guard, condition, qualifier).
-
+ Correctly instrumented code provides coverage information of two
+ kinds: source coverage and boolean-control coverage. Source
+ coverage is the extent to which every part of the program was
+ used, measured at three different levels: declarations (both
+ top-level and local), alternatives (among several equations or
+ case branches) and expressions (at every level). Boolean
+ coverage is the extent to which each of the values True and
+ False is obtained in every syntactic boolean context (ie. guard,
+ condition, qualifier).
- HPC displays both kinds of information in two different ways:
- textual reports with summary statistics (hpc-report) and sources
- with color mark-up (hpc-markup). For boolean coverage, there
+ HPC displays both kinds of information in two primary ways:
+ textual reports with summary statistics (hpc report) and sources
+ with color mark-up (hpc markup). For boolean coverage, there
are four possible outcomes for each guard, condition or
qualifier: both True and False values occur; only True; only
False; never evaluated. In hpc-markup output, highlighting with
@@ -1291,10 +1290,9 @@ to re-read its input file:
A small example: Reciprocation
- For an example we have a program which computes exact decimal
+ For an example we have a program, called Recip.hs, which computes exact decimal
representations of reciprocals, with recurring parts indicated in
- brackets. We first build an instrumented version using the
- hpc-build script. Assuming the source file is Recip.hs.
+ brackets.
reciprocal :: Int -> (String, Int)
@@ -1329,23 +1327,23 @@ main = do
main
-` The HPC intrumentation is enabled using the -fhpc flag.
+ The HPC instrumentation is enabled using the -fhpc flag.
$ ghc -fhpc Recip.hs --make
HPC index (.mix) files are placed placed in .hpc subdirectory. These can be considered like
- the .hi files for HPC. They contain information about what parts of the haskell each modules.
+ the .hi files for HPC.
$ ./Recip
1/3
= 0.(3)
- Now for a textual summary of coverage:
+ We can generate a textual summary of coverage:
-$ hpc-report Recip
+$ hpc report Recip
80% expressions used (81/101)
12% boolean coverage (1/8)
14% guards (1/7), 3 always True,
@@ -1357,17 +1355,177 @@ $ hpc-report Recip
100% local declarations used (9/9)
100% top-level declarations used (5/5)
- Finally, we generate a marked-up version of the source.
+ We can also generate a marked-up version of the source.
-$ hpc-markup Recip
+$ hpc markup Recip
writing Recip.hs.html
-
+
+ This generates one file per Haskell module, and 4 index files,
+ hpc_index.html, hpc_index_alt.html, hpc_index_exp.html,
+ hpc_index_fun.html.
+
+
+
+ Options for instrumenting code for coverage
+
+ Turning on code coverage is easy, use the -fhpc flag.
+ Instrumented and non-instrumented can be freely mixed.
+ When compiling the Main module GHC automatically detects when there
+ is an hpc compiled file, and adds the correct initialization code.
+
+
+
+
+ The hpc toolkit
+
+
+ The hpc toolkit uses a cvs/svn/darcs-like interface, where a
+ single binary contains many function units.
+
+$ hpc
+Usage: hpc COMMAND ...
+
+Commands:
+ help Display help for hpc or a single command
+Reporting Coverage:
+ report Output textual report about program coverage
+ markup Markup Haskell source with program coverage
+Processing Coverage files:
+ combine Combine multiple .tix files in a single .tix files
+Coverage Overlays:
+ overlay Generate a .tix file from an overlay file
+ draft Generate draft overlay that provides 100% coverage
+Others:
+ show Show .tix file in readable, verbose format
+ version Display version for hpc
+
+
+ In general, these options act on .tix file after an
+ instrumented binary has generated it, which hpc acting as a
+ conduit between the raw .tix file, and the more detailed reports
+ produced.
+
+
+
+ The hpc tool assumes you are in the top-level directory of
+ the location where you built your application, and the .tix
+ file is in the same top-level directory. You can use the
+ flag --srcdir to use hpc for any other directory, and use
+ --srcdir multiple times to analyse programs compiled from
+ difference locations, as is typical for packages.
+
+
+
+ We now explain in more details the major modes of hpc.
+
+
+ hpc report
+ hpc report gives a textual report of coverage. By default,
+ all modules and packages are considered in generating report,
+ unless include or exclude are used. The report is a summary
+ unless the --per-module flag is used. The --xml-output option
+ allows for tools to use hpc to glean coverage.
+
+
+$ hpc help report
+Usage: hpc report [OPTION] .. <TIX_FILE> [<MODULE> [<MODULE> ..]]
+
+Options:
+
+ --per-module show module level detail
+ --decl-list show unused decls
+ --exclude=[PACKAGE:][MODULE] exclude MODULE and/or PACKAGE
+ --include=[PACKAGE:][MODULE] include MODULE and/or PACKAGE
+ --srcdir=DIR path to source directory of .hs files
+ multi-use of srcdir possible
+ --hpcdir=DIR sub-directory that contains .mix files
+ default .hpc [rarely used]
+ --xml-output show output in XML
+
+
+ hpc markup
+ hpc markup marks up source files into colored html.
+
+
+% hpc help markup
+Usage: hpc markup [OPTION] .. <TIX_FILE> [<MODULE> [<MODULE> ..]]
+
+Options:
+
+ --exclude=[PACKAGE:][MODULE] exclude MODULE and/or PACKAGE
+ --include=[PACKAGE:][MODULE] include MODULE and/or PACKAGE
+ --srcdir=DIR path to source directory of .hs files
+ multi-use of srcdir possible
+ --hpcdir=DIR sub-directory that contains .mix files
+ default .hpc [rarely used]
+ --fun-entry-count show top-level function entry counts
+ --highlight-covered highlight covered code, rather that code gaps
+ --destdir=DIR path to write output to
+
+
+
+ hpc combine
+ hpc combine is the swiss army knife of hpc. Typically, combine is used
+ to add .tix files together to get the combined total coverage. However, it can
+ also be used to take the difference between .tix files, to subtract one
+ .tix file from another, and to zero the .tix files. hpc combine does not
+ change the original .tix file; it generates a new .tix file.
+
+
+hpc help combine
+Usage: hpc combine [OPTION] .. <TIX_FILE> [<TIX_FILE> [<TIX_FILE> ..]]
-
+Options:
+
+ --exclude=[PACKAGE:][MODULE] exclude MODULE and/or PACKAGE
+ --include=[PACKAGE:][MODULE] include MODULE and/or PACKAGE
+ --output=FILE output FILE
+ --combine=FUNCTION combine .tix files with join function, default = ADD
+ FUNCTION = ADD | DIFF | SUB | ZERO
+ --post-invert invert output; ticked becomes unticked, unticked becomes ticked
+
+
+ hpc overlay and hpc draft
+
+ Overlays are an experimental feature of HPC, a textual description
+ of coverage. hpc draft is used to generate a draft overlay from a .tix file,
+ and hpc overlay generates a .tix files from an overlay.
+
+
+% hpc help overlay
+Usage: hpc overlay [OPTION] .. <OVERLAY_FILE> [<OVERLAY_FILE> [...]]
+
+Options:
+
+ --srcdir=DIR path to source directory of .hs files
+ multi-use of srcdir possible
+ --hpcdir=DIR sub-directory that contains .mix files
+ default .hpc [rarely used]
+ --output=FILE output FILE
+% hpc help draft
+Usage: hpc draft [OPTION] .. <TIX_FILE>
+
+Options:
+
+ --exclude=[PACKAGE:][MODULE] exclude MODULE and/or PACKAGE
+ --include=[PACKAGE:][MODULE] include MODULE and/or PACKAGE
+ --srcdir=DIR path to source directory of .hs files
+ multi-use of srcdir possible
+ --hpcdir=DIR sub-directory that contains .mix files
+ default .hpc [rarely used]
+ --output=FILE output FILE
+
+
+
+ Caveats and Shortcomings of Haskell Program Coverage
+
+ HPC does not attempt to lock the .tix file, so multiple concurrently running
+ binaries in the same directory will exhibit a race condition. There is no way
+ to change the name of the .tix file generated, apart from renaming the binary.
+ HPC does not work with GHCi.
+
+