From: andy@galois.com Date: Wed, 26 Sep 2007 05:53:31 +0000 (+0000) Subject: Fixing #1340, adding HPC Documentation X-Git-Url: http://git.megacz.com/?p=ghc-hetmet.git;a=commitdiff_plain;h=478c200d59021e15a713f769eb6f6148e5183ba4 Fixing #1340, adding HPC Documentation --- diff --git a/docs/users_guide/flags.xml b/docs/users_guide/flags.xml index e787626..d994220 100644 --- a/docs/users_guide/flags.xml +++ b/docs/users_guide/flags.xml @@ -1433,7 +1433,7 @@ - Directory to deposit .mix files during compilation + Directory to deposit .mix files during compilation (default is .hpc) dynamic 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 -
- 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. + +