<listitem>
<para> Run your program with one of the profiling options, eg.
<literal>+RTS -p -RTS</literal>. This generates a file of
- profiling information.</para>
+ profiling information. Note that multi-processor execution
+ (e.g. <literal>+RTS -N2</literal>) is not supported while
+ profiling.</para>
<indexterm><primary><option>-p</option></primary><secondary>RTS
option</secondary></indexterm>
</listitem>
although GHC does keep information about which groups of functions
called each other recursively, this information isn't displayed in
the basic time and allocation profile, instead the call-graph is
- flattened into a tree. The XML profiling tool (described in <xref
- linkend="prof-xml-tool"/>) will be able to display real loops in
- the call-graph.</para>
+ flattened into a tree.</para>
<sect2><title>Inserting cost centres by hand</title>
in the profiling output, and
<literal><expression></literal> is any Haskell
expression. An <literal>SCC</literal> annotation extends as
- far to the right as possible when parsing.</para>
+ far to the right as possible when parsing. (SCC stands for "Set
+ Cost Centre").</para>
+
+ <para>Here is an example of a program with a couple of SCCs:</para>
+
+<programlisting>
+main :: IO ()
+main = do let xs = {-# SCC "X" #-} [1..1000000]
+ let ys = {-# SCC "Y" #-} [1..2000000]
+ print $ last xs
+ print $ last $ init xs
+ print $ last ys
+ print $ last $ init ys
+</programlisting>
+
+ <para>which gives this heap profile when run:</para>
+
+ <imagedata fileref="prof_scc"/>
</sect2>
<varlistentry>
<term>
- <option>-px</option>:
- <indexterm><primary><option>-px</option></primary></indexterm>
- </term>
- <listitem>
- <para>The <option>-px</option> option generates profiling
- information in the XML format understood by our new
- profiling tool, see <xref linkend="prof-xml-tool"/>.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
<option>-xc</option>
<indexterm><primary><option>-xc</option></primary><secondary>RTS option</secondary></indexterm>
</term>
</sect1>
- <sect1 id="prof-xml-tool">
- <title>Graphical time/allocation profile</title>
-
- <para>You can view the time and allocation profiling graph of your
- program graphically, using <command>ghcprof</command>. This is a
- new tool with GHC 4.08, and will eventually be the de-facto
- standard way of viewing GHC profiles<footnote><para>Actually this
- isn't true any more, we are working on a new tool for
- displaying heap profiles using Gtk+HS, so
- <command>ghcprof</command> may go away at some point in the future.</para>
- </footnote></para>
-
- <para>To run <command>ghcprof</command>, you need
- <productname>uDraw(Graph)</productname> installed, which can be
- obtained from <ulink
- url="http://www.informatik.uni-bremen.de/uDrawGraph/en/uDrawGraph/uDrawGraph.html"><citetitle>uDraw(Graph)</citetitle></ulink>. Install one of
- the binary
- distributions, and set your
- <envar>UDG_HOME</envar> environment variable to point to the
- installation directory.</para>
-
- <para><command>ghcprof</command> uses an XML-based profiling log
- format, and you therefore need to run your program with a
- different option: <option>-px</option>. The file generated is
- still called <filename><prog>.prof</filename>. To see the
- profile, run <command>ghcprof</command> like this:</para>
-
- <indexterm><primary><option>-px</option></primary></indexterm>
-
-<screen>
-$ ghcprof <prog>.prof
-</screen>
-
- <para>which should pop up a window showing the call-graph of your
- program in glorious detail. More information on using
- <command>ghcprof</command> can be found at <ulink
- url="http://www.dcs.warwick.ac.uk/people/academic/Stephen.Jarvis/profiler/index.html"><citetitle>The
- Cost-Centre Stack Profiling Tool for
- GHC</citetitle></ulink>.</para>
-
- </sect1>
-
<sect1 id="hp2ps">
<title><command>hp2ps</command>––heap profile to PostScript</title>
</screen>
</para>
</sect2>
+ </sect1>
+
+ <sect1 id="hpc">
+ <title>Observing Code Coverage</title>
+ <indexterm><primary>code coverage</primary></indexterm>
+ <indexterm><primary>Haskell Program Coverage</primary></indexterm>
+ <indexterm><primary>hpc</primary></indexterm>
+
+ <para>
+ Code coverage tools allow a programmer to determine what parts of
+ their code have been actually executed, and which parts have
+ never actually been invoked. GHC has an option for generating
+ instrumented code that records code coverage as part of the
+ <ulink url="http://www.haskell.org/hpc">Haskell Program Coverage
+ </ulink>(HPC) toolkit, which is included with GHC. HPC tools can
+ be used to render the generated code coverage information into
+ human understandable format. </para>
+
+ <para>
+ 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). </para>
+
+ <para>
+ 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
+ a yellow background indicates a part of the program that was
+ never evaluated; a green background indicates an always-True
+ expression and a red background indicates an always-False one.
+ </para>
+
+ <sect2><title>A small example: Reciprocation</title>
+
+ <para>
+ For an example we have a program, called Recip.hs, which computes exact decimal
+ representations of reciprocals, with recurring parts indicated in
+ brackets.
+ </para>
+<programlisting>
+reciprocal :: Int -> (String, Int)
+reciprocal n | n > 1 = ('0' : '.' : digits, recur)
+ | otherwise = error
+ "attempting to compute reciprocal of number <= 1"
+ where
+ (digits, recur) = divide n 1 []
+divide :: Int -> Int -> [Int] -> (String, Int)
+divide n c cs | c `elem` cs = ([], position c cs)
+ | r == 0 = (show q, 0)
+ | r /= 0 = (show q ++ digits, recur)
+ where
+ (q, r) = (c*10) `quotRem` n
+ (digits, recur) = divide n r (c:cs)
+
+position :: Int -> [Int] -> Int
+position n (x:xs) | n==x = 1
+ | otherwise = 1 + position n xs
+
+showRecip :: Int -> String
+showRecip n =
+ "1/" ++ show n ++ " = " ++
+ if r==0 then d else take p d ++ "(" ++ drop p d ++ ")"
+ where
+ p = length d - r
+ (d, r) = reciprocal n
+
+main = do
+ number <- readLn
+ putStrLn (showRecip number)
+ main
+</programlisting>
+
+ <para>The HPC instrumentation is enabled using the -fhpc flag.
+ </para>
+
+<screen>
+$ ghc -fhpc Recip.hs --make
+</screen>
+ <para>HPC index (.mix) files are placed placed in .hpc subdirectory. These can be considered like
+ the .hi files for HPC.
+ </para>
+<screen>
+$ ./Recip
+1/3
+= 0.(3)
+</screen>
+ <para>We can generate a textual summary of coverage:</para>
+<screen>
+$ hpc report Recip
+ 80% expressions used (81/101)
+ 12% boolean coverage (1/8)
+ 14% guards (1/7), 3 always True,
+ 1 always False,
+ 2 unevaluated
+ 0% 'if' conditions (0/1), 1 always False
+ 100% qualifiers (0/0)
+ 55% alternatives used (5/9)
+100% local declarations used (9/9)
+100% top-level declarations used (5/5)
+</screen>
+ <para>We can also generate a marked-up version of the source.</para>
+<screen>
+$ hpc markup Recip
+writing Recip.hs.html
+</screen>
+ <para>
+ 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.
+ </para>
+ </sect2>
+
+ <sect2><title>Options for instrumenting code for coverage</title>
+ <para>
+ 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.
+ </para>
+
+ </sect2>
+
+ <sect2><title>The hpc toolkit</title>
+
+ <para>
+ The hpc toolkit uses a cvs/svn/darcs-like interface, where a
+ single binary contains many function units.</para>
+<screen>
+$ 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:
+ sum Sum multiple .tix files in a single .tix file
+ combine Combine two .tix files in a single .tix file
+ map Map a function over a single .tix file
+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
+</screen>
+
+ <para>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.
+ </para>
+
+ <para>
+ 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.
+ </para>
+
+ <para>
+ We now explain in more details the major modes of hpc.
+ </para>
+
+ <sect3><title>hpc report</title>
+ <para>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.
+ </para>
+<screen>
+$ 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
+</screen>
+ </sect3>
+ <sect3><title>hpc markup</title>
+ <para>hpc markup marks up source files into colored html.
+ </para>
+<screen>
+$ 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
+</screen>
+
+ </sect3>
+ <sect3><title>hpc sum</title>
+ <para>hpc sum adds together any number of .tix files into a single
+ .tix file. hpc sum does not change the original .tix file; it generates a new .tix file.
+ </para>
+<screen>
+$ hpc help sum
+Usage: hpc sum [OPTION] .. <TIX_FILE> [<TIX_FILE> [<TIX_FILE> ..]]
+Sum multiple .tix files in a single .tix file
+Options:
+ --exclude=[PACKAGE:][MODULE] exclude MODULE and/or PACKAGE
+ --include=[PACKAGE:][MODULE] include MODULE and/or PACKAGE
+ --output=FILE output FILE
+ --union use the union of the module namespace (default is intersection)
+</screen>
+ </sect3>
+ <sect3><title>hpc combine</title>
+ <para>hpc combine is the swiss army knife of hpc. It can be
+ used to take the difference between .tix files, to subtract one
+ .tix file from another, or to add two .tix files. hpc combine does not
+ change the original .tix file; it generates a new .tix file.
+ </para>
+<screen>
+$ hpc help combine
+Usage: hpc combine [OPTION] .. <TIX_FILE> <TIX_FILE>
+Combine two .tix files in a single .tix file
+
+Options:
+
+ --exclude=[PACKAGE:][MODULE] exclude MODULE and/or PACKAGE
+ --include=[PACKAGE:][MODULE] include MODULE and/or PACKAGE
+ --output=FILE output FILE
+ --function=FUNCTION combine .tix files with join function, default = ADD
+ FUNCTION = ADD | DIFF | SUB
+ --union use the union of the module namespace (default is intersection)
+</screen>
+ </sect3>
+ <sect3><title>hpc map</title>
+ <para>hpc map inverts or zeros a .tix file. hpc map does not
+ change the original .tix file; it generates a new .tix file.
+ </para>
+<screen>
+$ hpc help map
+Usage: hpc map [OPTION] .. <TIX_FILE>
+Map a function over a single .tix file
+
+Options:
+
+ --exclude=[PACKAGE:][MODULE] exclude MODULE and/or PACKAGE
+ --include=[PACKAGE:][MODULE] include MODULE and/or PACKAGE
+ --output=FILE output FILE
+ --function=FUNCTION apply function to .tix files, default = ID
+ FUNCTION = ID | INV | ZERO
+ --union use the union of the module namespace (default is intersection)
+</screen>
+ </sect3>
+ <sect3><title>hpc overlay and hpc draft</title>
+ <para>
+ 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.
+ </para>
+<screen>
+% 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
+</screen>
+ </sect3>
+ </sect2>
+ <sect2><title>Caveats and Shortcomings of Haskell Program Coverage</title>
+ <para>
+ 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.
+ </para>
+ </sect2>
</sect1>
<sect1 id="ticky-ticky">
profiling system, intended for all users everywhere.</para>
<para>To be able to use ticky-ticky profiling, you will need to
- have built appropriate libraries and things when you made the
- system. See “Customising what libraries to build,” in
- the installation guide.</para>
+ have built the ticky RTS. (This should be described in
+ the building guide, but amounts to building the RTS with way
+ "t" enabled.)</para>
<para>To get your compiled program to spit out the ticky-ticky
numbers, use a <option>-r</option> RTS
projects / ghc-hetmet.git / blobdiff