Personal tools

Haskell program coverage

From HaskellWiki

(Difference between revisions)
Jump to: navigation, search
m (Wiki Style on headlines as per guidelines, fix bulleted list formats)
Line 1: Line 1:
 
[[Category:Development tools]] [[Category:Applications]]
 
[[Category:Development tools]] [[Category:Applications]]
= What is hpc? =
+
== What is hpc? ==
   
 
Hpc is a tool-kit to record and display Haskell program coverage. Hpc
 
Hpc is a tool-kit to record and display Haskell program coverage. Hpc
Line 28: Line 28:
 
mark-up (hpc-source).
 
mark-up (hpc-source).
   
= Downloading =
+
== Downloading ==
   
 
This version of hpc is available under a BSD-style license for free
 
This version of hpc is available under a BSD-style license for free
Line 38: Line 38:
 
as well as tarballs of the various tools).
 
as well as tarballs of the various tools).
   
= Examples =
+
== Examples ==
   
== Example textual output from hpc-report ==
+
=== Example textual output from hpc-report ===
   
 
<nowiki>-----<module Main>-----</nowiki>
 
<nowiki>-----<module Main>-----</nowiki>
Line 55: Line 55:
 
showRecip.p
 
showRecip.p
   
== Example of HTML output from hpc-source ==
+
=== Example of HTML output from hpc-source ===
   
 
[[Image:hpcexample.gif]]
 
[[Image:hpcexample.gif]]
Line 62: Line 62:
 
or <font style="background: red">always False</font>.
 
or <font style="background: red">always False</font>.
   
= Hpc Toolkit =
+
== Hpc Toolkit ==
   
 
The Hpc Toolkit has three parts
 
The Hpc Toolkit has three parts
Line 69: Line 69:
 
* An open common file format, uses by all the tools.
 
* An open common file format, uses by all the tools.
   
== Hpc Tools ==
+
=== Hpc Tools ===
   
 
There are currently three tools provided by hpc, as well as a new option for GHC 6.6.1.
 
There are currently three tools provided by hpc, as well as a new option for GHC 6.6.1.
Line 81: Line 81:
 
Compiler Options
 
Compiler Options
   
* -fhpc - a new GHC option, that automatically instruments Haskell
+
* -fhpc - a new GHC option, that automatically instruments Haskell programs on the fly, using a similar algorithm to hpc-trans.
programs on the fly, using a similar algorithm to hpc-trans.
 
   
 
*: This option has three variations
 
*: This option has three variations
Line 88: Line 88:
 
** -fhpc-trace - gather coverage information dynamically, for replay.
 
** -fhpc-trace - gather coverage information dynamically, for replay.
   
== Hpc Scripts ==
+
=== Hpc Scripts ===
   
* hpc - driver script to make using hpc-trans easy.
+
<code>hpc</code> - driver script to make using hpc-trans easy.
* hpc build
+
* hpc build
* hpc run
+
* hpc run
* hpc report
+
* hpc report
* hpc markup
+
* hpc markup
   
   
== Hpc File Formats ==
+
=== Hpc File Formats ===
   
 
There are two file formats used by Hpc externally, and one internally
 
There are two file formats used by Hpc externally, and one internally

Revision as of 13:42, 14 October 2006

Contents

1 What is hpc?

Hpc is a tool-kit to record and display Haskell program coverage. Hpc includes tools that instrument Haskell programs to record program coverage, run instrumented programs, and display the coverage information obtained.

Hpc works by applying a source-to-source transformation; this transformation also generates as a by-product a program-index file (.pix) and module-index files (.mix). The transformed program is compiled with a library; in addition to its usual run-time behaviour the program generates a coverage record in a program-ticks file (.tix). If the program is run more than once, coverage data is accumulated to reflect all runs.

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

Hpc displays both kinds of information in two different ways: textual reports with summary statistics (hpc-report) and sources with colour mark-up (hpc-source).

2 Downloading

This version of hpc is available under a BSD-style license for free use by all sectors of the Haskell community. The hpc-trans tool was based on components from the nhc98 compiler or from the hat tracing system, and we gladly acknowledge the contribution of the original authors.

The latest version is version 0.3, (and a DARCS repo coming soon, as well as tarballs of the various tools).

3 Examples

3.1 Example textual output from hpc-report

-----<module Main>-----

 67% expressions used (72/106)
 14% boolean coverage (1/7)
     16% guards (1/6), 2 always True, 2 always False, 1 unevaluated
      0% 'if' conditions (0/1), 1 always True
    100% qualifiers (0/0)
 42% alternatives used (3/7)
 88% local declarations used (8/9)
 80% top-level declarations used (4/5)
unused declarations:
    position
    showRecip.p

3.2 Example of HTML output from hpc-source

Hpcexample.gif

The HTML output highlights parts of the program never evaluated; it also highlights boolean conditions for which recorded evaluations are always True or always False.

4 Hpc Toolkit

The Hpc Toolkit has three parts

  • A set of tools for instrumenting Haskell, and interpreting the results on a coverage run.
  • A set of scripts to make using these tools easier.
  • An open common file format, uses by all the tools.

4.1 Hpc Tools

There are currently three tools provided by hpc, as well as a new option for GHC 6.6.1.

Tools

  • hpc-trans - translates Haskell into instrumented Haskell
  • hpc-report - Read the output of a coverage run, report a summary
  • hpc-markup - Read the output of a coverage run, markup the source

Compiler Options

  • -fhpc - a new GHC option, that automatically instruments Haskell programs on the fly, using a similar algorithm to hpc-trans.
  • This option has three variations
    • -fhpc - gather coverage information.
    • -fhpc-count - gather coverage information, with accurage usage count.
    • -fhpc-trace - gather coverage information dynamically, for replay.

4.2 Hpc Scripts

hpc - driver script to make using hpc-trans easy.

  • hpc build
  • hpc run
  • hpc report
  • hpc markup


4.3 Hpc File Formats

There are two file formats used by Hpc externally, and one internally by hpc-trans.

  • tix - Coverage information generated by the execution of an instrumented program.
  • mix - Information about each tick-box inside a module, including style of tick box, and location in the source.
  • pix - used only by hpc-trans, stores a list

We hope you find this tool-kit useful. If you have any comments or feedback, please feel free to email us.

Andy Gill ([email protected]) Colin Runciman ([email protected])