View source for Haskell program coverage

[[Category:Development tools]] [[Category:Applications]]
== 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).

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

== Examples ==

=== Example textual output from hpc-report ===

<nowiki>-----<module Main>-----</nowiki>
  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

=== Example of HTML output from hpc-markup ===

[[Image:hpcexample.gif]]

The HTML output highlights parts of the program <font style="background: yellow">never evaluated</font>; it also highlights boolean conditions for which recorded evaluations are <font style="background: green">always True</font>
or <font style="background: red">always False</font>.

=== Example of HTML Summary from hpc-markup ===

This is an example of the table that provides the summary of coverage,
with links the the individually marked-up files.

<table width="100%" border=1>
<tr><th rowspan=2>module</th><th colspan=3>Top Level Definitions</th><th colspan=3>Alternatives</th><th colspan=3>Expressions</th></tr><tr><th>%</th><th colspan=2>covered / total</th><th>%</th><th colspan=2>covered / total</th><th>%</th><th colspan=2>covered / total</th></tr><tr>
<td>&nbsp;&nbsp;<tt>module CSG</tt></td>
<td align="right">100 %</td><td>0/0</td><td width=100><table cellpadding=0 cellspacing=0 width="100" style="background-color: #f25913"><tr><td><table cellpadding=0 cellspacing=0 width="100%"><tr><td height=12 style="background-color: #60de51"></td></tr></table></td></tr></table><td align="right">100 %</td><td>0/0</td><td width=100><table cellpadding=0 cellspacing=0 width="100" style="background-color: #f25913"><tr><td><table cellpadding=0 cellspacing=0 width="100%"><tr><td height=12 style="background-color: #60de51"></td></tr></table></td></tr></table><td align="right">100 %</td><td>0/0</td><td width=100><table cellpadding=0 cellspacing=0 width="100" style="background-color: #f25913"><tr><td><table cellpadding=0 cellspacing=0 width="100%"><tr><td height=12 style="background-color: #60de51"></td></tr></table></td></tr></table></tr>

<tr>
<td>&nbsp;&nbsp;<tt>module Construct</tt></td>
<td align="right">48 %</td><td>17/35</td><td width=100><table cellpadding=0 cellspacing=0 width="100" style="background-color: #f25913"><tr><td><table cellpadding=0 cellspacing=0 width="48%"><tr><td height=12 style="background-color: #60de51"></td></tr></table></td></tr></table><td align="right">52 %</td><td>25/48</td><td width=100><table cellpadding=0 cellspacing=0 width="100" style="background-color: #f25913"><tr><td><table cellpadding=0 cellspacing=0 width="52%"><tr><td height=12 style="background-color: #60de51"></td></tr></table></td></tr></table><td align="right">60 %</td><td>381/635</td><td width=100><table cellpadding=0 cellspacing=0 width="100" style="background-color: #f25913"><tr><td><table cellpadding=0 cellspacing=0 width="60%"><tr><td height=12 style="background-color: #60de51"></td></tr></table></td></tr></table></tr>
<tr>
<td>&nbsp;&nbsp;<tt>module Data</tt></td>
<td align="right">24 %</td><td>6/25</td><td width=100><table cellpadding=0 cellspacing=0 width="100" style="background-color: #f25913"><tr><td><table cellpadding=0 cellspacing=0 width="24%"><tr><td height=12 style="background-color: #60de51"></td></tr></table></td></tr></table><td align="right">13 %</td><td>11/81</td><td width=100><table cellpadding=0 cellspacing=0 width="100" style="background-color: #f25913"><tr><td><table cellpadding=0 cellspacing=0 width="13%"><tr><td height=12 style="background-color: #60de51"></td></tr></table></td></tr></table><td align="right">39 %</td><td>254/646</td><td width=100><table cellpadding=0 cellspacing=0 width="100" style="background-color: #f25913"><tr><td><table cellpadding=0 cellspacing=0 width="39%"><tr><td height=12 style="background-color: #60de51"></td></tr></table></td></tr></table></tr>

<tr>
<td>&nbsp;&nbsp;<tt>module Eval</tt></td>
<td align="right">70 %</td><td>22/31</td><td width=100><table cellpadding=0 cellspacing=0 width="100" style="background-color: #f25913"><tr><td><table cellpadding=0 cellspacing=0 width="70%"><tr><td height=12 style="background-color: #60de51"></td></tr></table></td></tr></table><td align="right">60 %</td><td>65/108</td><td width=100><table cellpadding=0 cellspacing=0 width="100" style="background-color: #f25913"><tr><td><table cellpadding=0 cellspacing=0 width="60%"><tr><td height=12 style="background-color: #60de51"></td></tr></table></td></tr></table><td align="right">57 %</td><td>361/628</td><td width=100><table cellpadding=0 cellspacing=0 width="100" style="background-color: #f25913"><tr><td><table cellpadding=0 cellspacing=0 width="57%"><tr><td height=12 style="background-color: #60de51"></td></tr></table></td></tr></table></tr>
<tr>
<td>&nbsp;&nbsp;<tt>module Geometry</tt></td>
<td align="right">75 %</td><td>42/56</td><td width=100><table cellpadding=0 cellspacing=0 width="100" style="background-color: #f25913"><tr><td><table cellpadding=0 cellspacing=0 width="75%"><tr><td height=12 style="background-color: #60de51"></td></tr></table></td></tr></table><td align="right">69 %</td><td>45/65</td><td width=100><table cellpadding=0 cellspacing=0 width="100" style="background-color: #f25913"><tr><td><table cellpadding=0 cellspacing=0 width="69%"><tr><td height=12 style="background-color: #60de51"></td></tr></table></td></tr></table><td align="right">70 %</td><td>300/427</td><td width=100><table cellpadding=0 cellspacing=0 width="100" style="background-color: #f25913"><tr><td><table cellpadding=0 cellspacing=0 width="70%"><tr><td height=12 style="background-color: #60de51"></td></tr></table></td></tr></table></tr>

<tr>
<td>&nbsp;&nbsp;<tt>module Illumination</tt></td>
<td align="right">61 %</td><td>11/18</td><td width=100><table cellpadding=0 cellspacing=0 width="100" style="background-color: #f25913"><tr><td><table cellpadding=0 cellspacing=0 width="61%"><tr><td height=12 style="background-color: #60de51"></td></tr></table></td></tr></table><td align="right">49 %</td><td>46/93</td><td width=100><table cellpadding=0 cellspacing=0 width="100" style="background-color: #f25913"><tr><td><table cellpadding=0 cellspacing=0 width="49%"><tr><td height=12 style="background-color: #60de51"></td></tr></table></td></tr></table><td align="right">46 %</td><td>279/600</td><td width=100><table cellpadding=0 cellspacing=0 width="100" style="background-color: #f25913"><tr><td><table cellpadding=0 cellspacing=0 width="46%"><tr><td height=12 style="background-color: #60de51"></td></tr></table></td></tr></table></tr>
<tr>
<td>&nbsp;&nbsp;<tt>module Intersections</tt></td>
<td align="right">63 %</td><td>14/22</td><td width=100><table cellpadding=0 cellspacing=0 width="100" style="background-color: #f25913"><tr><td><table cellpadding=0 cellspacing=0 width="63%"><tr><td height=12 style="background-color: #60de51"></td></tr></table></td></tr></table><td align="right">38 %</td><td>83/213</td><td width=100><table cellpadding=0 cellspacing=0 width="100" style="background-color: #f25913"><tr><td><table cellpadding=0 cellspacing=0 width="38%"><tr><td height=12 style="background-color: #60de51"></td></tr></table></td></tr></table><td align="right">38 %</td><td>382/1001</td><td width=100><table cellpadding=0 cellspacing=0 width="100" style="background-color: #f25913"><tr><td><table cellpadding=0 cellspacing=0 width="38%"><tr><td height=12 style="background-color: #60de51"></td></tr></table></td></tr></table></tr>

<tr>
<td>&nbsp;&nbsp;<tt>module Interval</tt></td>
<td align="right">47 %</td><td>8/17</td><td width=100><table cellpadding=0 cellspacing=0 width="100" style="background-color: #f25913"><tr><td><table cellpadding=0 cellspacing=0 width="47%"><tr><td height=12 style="background-color: #60de51"></td></tr></table></td></tr></table><td align="right">41 %</td><td>16/39</td><td width=100><table cellpadding=0 cellspacing=0 width="100" style="background-color: #f25913"><tr><td><table cellpadding=0 cellspacing=0 width="41%"><tr><td height=12 style="background-color: #60de51"></td></tr></table></td></tr></table><td align="right">41 %</td><td>69/165</td><td width=100><table cellpadding=0 cellspacing=0 width="100" style="background-color: #f25913"><tr><td><table cellpadding=0 cellspacing=0 width="41%"><tr><td height=12 style="background-color: #60de51"></td></tr></table></td></tr></table></tr>
<tr>
<td>&nbsp;&nbsp;<tt>module Main</tt></td>
<td align="right">100 %</td><td>1/1</td><td width=100><table cellpadding=0 cellspacing=0 width="100" style="background-color: #f25913"><tr><td><table cellpadding=0 cellspacing=0 width="100%"><tr><td height=12 style="background-color: #60de51"></td></tr></table></td></tr></table><td align="right">100 %</td><td>1/1</td><td width=100><table cellpadding=0 cellspacing=0 width="100" style="background-color: #f25913"><tr><td><table cellpadding=0 cellspacing=0 width="100%"><tr><td height=12 style="background-color: #60de51"></td></tr></table></td></tr></table><td align="right">100 %</td><td>6/6</td><td width=100><table cellpadding=0 cellspacing=0 width="100" style="background-color: #f25913"><tr><td><table cellpadding=0 cellspacing=0 width="100%"><tr><td height=12 style="background-color: #60de51"></td></tr></table></td></tr></table></tr>

<tr>
<td>&nbsp;&nbsp;<tt>module Misc</tt></td>
<td align="right">0 %</td><td>0/1</td><td width=100><table cellpadding=0 cellspacing=0 width="100" style="background-color: #f25913"><tr><td><table cellpadding=0 cellspacing=0 width="0%"><tr><td height=12 style="background-color: #60de51"></td></tr></table></td></tr></table><td align="right">0 %</td><td>0/1</td><td width=100><table cellpadding=0 cellspacing=0 width="100" style="background-color: #f25913"><tr><td><table cellpadding=0 cellspacing=0 width="0%"><tr><td height=12 style="background-color: #60de51"></td></tr></table></td></tr></table><td align="right">0 %</td><td>0/10</td><td width=100><table cellpadding=0 cellspacing=0 width="100" style="background-color: #f25913"><tr><td><table cellpadding=0 cellspacing=0 width="0%"><tr><td height=12 style="background-color: #60de51"></td></tr></table></td></tr></table></tr>
<tr>
<td>&nbsp;&nbsp;<tt>module Parse</tt></td>
<td align="right">80 %</td><td>16/20</td><td width=100><table cellpadding=0 cellspacing=0 width="100" style="background-color: #f25913"><tr><td><table cellpadding=0 cellspacing=0 width="80%"><tr><td height=12 style="background-color: #60de51"></td></tr></table></td></tr></table><td align="right">68 %</td><td>26/38</td><td width=100><table cellpadding=0 cellspacing=0 width="100" style="background-color: #f25913"><tr><td><table cellpadding=0 cellspacing=0 width="68%"><tr><td height=12 style="background-color: #60de51"></td></tr></table></td></tr></table><td align="right">72 %</td><td>192/264</td><td width=100><table cellpadding=0 cellspacing=0 width="100" style="background-color: #f25913"><tr><td><table cellpadding=0 cellspacing=0 width="72%"><tr><td height=12 style="background-color: #60de51"></td></tr></table></td></tr></table></tr>

<tr>
<td>&nbsp;&nbsp;<tt>module Primitives</tt></td>
<td align="right">16 %</td><td>1/6</td><td width=100><table cellpadding=0 cellspacing=0 width="100" style="background-color: #f25913"><tr><td><table cellpadding=0 cellspacing=0 width="16%"><tr><td height=12 style="background-color: #60de51"></td></tr></table></td></tr></table><td align="right">16 %</td><td>1/6</td><td width=100><table cellpadding=0 cellspacing=0 width="100" style="background-color: #f25913"><tr><td><table cellpadding=0 cellspacing=0 width="16%"><tr><td height=12 style="background-color: #60de51"></td></tr></table></td></tr></table><td align="right">20 %</td><td>5/24</td><td width=100><table cellpadding=0 cellspacing=0 width="100" style="background-color: #f25913"><tr><td><table cellpadding=0 cellspacing=0 width="20%"><tr><td height=12 style="background-color: #60de51"></td></tr></table></td></tr></table></tr>
<tr>
<td>&nbsp;&nbsp;<tt>module Surface</tt></td>
<td align="right">36 %</td><td>4/11</td><td width=100><table cellpadding=0 cellspacing=0 width="100" style="background-color: #f25913"><tr><td><table cellpadding=0 cellspacing=0 width="36%"><tr><td height=12 style="background-color: #60de51"></td></tr></table></td></tr></table><td align="right">24 %</td><td>13/53</td><td width=100><table cellpadding=0 cellspacing=0 width="100" style="background-color: #f25913"><tr><td><table cellpadding=0 cellspacing=0 width="24%"><tr><td height=12 style="background-color: #60de51"></td></tr></table></td></tr></table><td align="right">18 %</td><td>43/231</td><td width=100><table cellpadding=0 cellspacing=0 width="100" style="background-color: #f25913"><tr><td><table cellpadding=0 cellspacing=0 width="18%"><tr><td height=12 style="background-color: #60de51"></td></tr></table></td></tr></table></tr>

</table>

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

=== Hpc tools ===

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

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.

=== Hpc scripts ===

* hpc-build
* hpc-run


=== 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 (andy@galois.com)
Colin Runciman (colin@cs.york.ac.uk)