3f2e592944d0155c9f1b046da68ad7da35ef37e5
[ghc.git] / docs / users_guide / profiling.rst
1 .. _profiling:
2
3 Profiling
4 =========
5
6 .. index::
7    single: profiling
8    single: cost-centre profiling
9    single: -p; RTS option
10
11 GHC comes with a time and space profiling system, so that you can answer
12 questions like "why is my program so slow?", or "why is my program using
13 so much memory?".
14
15 Profiling a program is a three-step process:
16
17 1. Re-compile your program for profiling with the :ghc-flag:`-prof` option, and
18    probably one of the options for adding automatic annotations:
19    :ghc-flag:`-fprof-auto` is the most common [1]_.
20
21    If you are using external packages with :command:`cabal`, you may need to
22    reinstall these packages with profiling support; typically this is
23    done with ``cabal install -p package --reinstall``.
24
25 2. Having compiled the program for profiling, you now need to run it to
26    generate the profile. For example, a simple time profile can be
27    generated by running the program with ``+RTS -p`` (see :rts-flag:`-p`), which
28    generates a file named :file:`{prog}.prof` where ⟨prog⟩ is the name of your
29    program (without the ``.exe`` extension, if you are on Windows).
30
31    There are many different kinds of profile that can be generated,
32    selected by different RTS options. We will be describing the various
33    kinds of profile throughout the rest of this chapter. Some profiles
34    require further processing using additional tools after running the
35    program.
36
37 3. Examine the generated profiling information, use the information to
38    optimise your program, and repeat as necessary.
39
40 .. _cost-centres:
41
42 Cost centres and cost-centre stacks
43 -----------------------------------
44
45 GHC's profiling system assigns costs to cost centres. A cost is simply
46 the time or space (memory) required to evaluate an expression. Cost
47 centres are program annotations around expressions; all costs incurred
48 by the annotated expression are assigned to the enclosing cost centre.
49 Furthermore, GHC will remember the stack of enclosing cost centres for
50 any given expression at run-time and generate a call-tree of cost
51 attributions.
52
53 Let's take a look at an example: ::
54
55     main = print (fib 30)
56     fib n = if n < 2 then 1 else fib (n-1) + fib (n-2)
57
58 Compile and run this program as follows:
59
60 .. code-block:: none
61
62     $ ghc -prof -fprof-auto -rtsopts Main.hs
63     $ ./Main +RTS -p
64     121393
65     $
66
67 When a GHC-compiled program is run with the :rts-flag:`-p` RTS option, it
68 generates a file called :file:`prog.prof`. In this case, the file will contain
69 something like this:
70
71 .. code-block:: none
72
73             Wed Oct 12 16:14 2011 Time and Allocation Profiling Report  (Final)
74
75                Main +RTS -p -RTS
76
77             total time  =        0.68 secs   (34 ticks @ 20 ms)
78             total alloc = 204,677,844 bytes  (excludes profiling overheads)
79
80     COST CENTRE MODULE  %time %alloc
81
82     fib         Main    100.0  100.0
83
84
85                                                           individual     inherited
86     COST CENTRE MODULE                  no.     entries  %time %alloc   %time %alloc
87
88     MAIN        MAIN                    102           0    0.0    0.0   100.0  100.0
89      CAF        GHC.IO.Handle.FD        128           0    0.0    0.0     0.0    0.0
90      CAF        GHC.IO.Encoding.Iconv   120           0    0.0    0.0     0.0    0.0
91      CAF        GHC.Conc.Signal         110           0    0.0    0.0     0.0    0.0
92      CAF        Main                    108           0    0.0    0.0   100.0  100.0
93       main      Main                    204           1    0.0    0.0   100.0  100.0
94        fib      Main                    205     2692537  100.0  100.0   100.0  100.0
95
96 The first part of the file gives the program name and options, and the
97 total time and total memory allocation measured during the run of the
98 program (note that the total memory allocation figure isn't the same as
99 the amount of *live* memory needed by the program at any one time; the
100 latter can be determined using heap profiling, which we will describe
101 later in :ref:`prof-heap`).
102
103 The second part of the file is a break-down by cost centre of the most
104 costly functions in the program. In this case, there was only one
105 significant function in the program, namely ``fib``, and it was
106 responsible for 100% of both the time and allocation costs of the
107 program.
108
109 The third and final section of the file gives a profile break-down by
110 cost-centre stack. This is roughly a call-tree profile of the program.
111 In the example above, it is clear that the costly call to ``fib`` came
112 from ``main``.
113
114 The time and allocation incurred by a given part of the program is
115 displayed in two ways: “individual”, which are the costs incurred by the
116 code covered by this cost centre stack alone, and “inherited”, which
117 includes the costs incurred by all the children of this node.
118
119 The usefulness of cost-centre stacks is better demonstrated by modifying
120 the example slightly: ::
121
122     main = print (f 30 + g 30)
123       where
124         f n  = fib n
125         g n  = fib (n `div` 2)
126
127     fib n = if n < 2 then 1 else fib (n-1) + fib (n-2)
128
129 Compile and run this program as before, and take a look at the new
130 profiling results:
131
132 .. code-block:: none
133
134     COST CENTRE MODULE                  no.     entries  %time %alloc   %time %alloc
135
136     MAIN        MAIN                    102           0    0.0    0.0   100.0  100.0
137      CAF        GHC.IO.Handle.FD        128           0    0.0    0.0     0.0    0.0
138      CAF        GHC.IO.Encoding.Iconv   120           0    0.0    0.0     0.0    0.0
139      CAF        GHC.Conc.Signal         110           0    0.0    0.0     0.0    0.0
140      CAF        Main                    108           0    0.0    0.0   100.0  100.0
141       main      Main                    204           1    0.0    0.0   100.0  100.0
142        main.g   Main                    207           1    0.0    0.0     0.0    0.1
143         fib     Main                    208        1973    0.0    0.1     0.0    0.1
144        main.f   Main                    205           1    0.0    0.0   100.0   99.9
145         fib     Main                    206     2692537  100.0   99.9   100.0   99.9
146
147 Now although we had two calls to ``fib`` in the program, it is
148 immediately clear that it was the call from ``f`` which took all the
149 time. The functions ``f`` and ``g`` which are defined in the ``where``
150 clause in ``main`` are given their own cost centres, ``main.f`` and
151 ``main.g`` respectively.
152
153 The actual meaning of the various columns in the output is:
154
155     The number of times this particular point in the call tree was
156     entered.
157
158     The percentage of the total run time of the program spent at this
159     point in the call tree.
160
161     The percentage of the total memory allocations (excluding profiling
162     overheads) of the program made by this call.
163
164     The percentage of the total run time of the program spent below this
165     point in the call tree.
166
167     The percentage of the total memory allocations (excluding profiling
168     overheads) of the program made by this call and all of its
169     sub-calls.
170
171 In addition you can use the :rts-flag:`-P` RTS option to get the
172 following additional information:
173
174 ``ticks``
175     The raw number of time “ticks” which were attributed to this
176     cost-centre; from this, we get the ``%time`` figure mentioned above.
177
178 ``bytes``
179     Number of bytes allocated in the heap while in this cost-centre;
180     again, this is the raw number from which we get the ``%alloc``
181     figure mentioned above.
182
183 What about recursive functions, and mutually recursive groups of
184 functions? Where are the costs attributed? Well, although GHC does keep
185 information about which groups of functions called each other
186 recursively, this information isn't displayed in the basic time and
187 allocation profile, instead the call-graph is flattened into a tree as
188 follows: a call to a function that occurs elsewhere on the current stack
189 does not push another entry on the stack, instead the costs for this
190 call are aggregated into the caller [2]_.
191
192 .. _scc-pragma:
193
194 Inserting cost centres by hand
195 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
196
197 Cost centres are just program annotations. When you say ``-fprof-auto``
198 to the compiler, it automatically inserts a cost centre annotation
199 around every binding not marked INLINE in your program, but you are
200 entirely free to add cost centre annotations yourself.
201
202 The syntax of a cost centre annotation for expressions is ::
203
204     {-# SCC "name" #-} <expression>
205
206 where ``"name"`` is an arbitrary string, that will become the name of
207 your cost centre as it appears in the profiling output, and
208 ``<expression>`` is any Haskell expression. An ``SCC`` annotation
209 extends as far to the right as possible when parsing. (SCC stands for
210 "Set Cost Centre"). The double quotes can be omitted if ``name`` is a
211 Haskell identifier, for example: ::
212
213     {-# SCC id #-} <expression>
214
215 Cost centre annotations can also appear in the top-level or in a
216 declaration context. In that case you need to pass a function name
217 defined in the same module or scope with the annotation. Example: ::
218
219     f x y = ...
220       where
221         g z = ...
222         {-# SCC g #-}
223
224     {-# SCC f #-}
225
226 If you want to give a cost centre different name than the function name,
227 you can pass a string to the annotation ::
228
229     f x y = ...
230     {-# SCC f "cost_centre_name" #-}
231
232 Here is an example of a program with a couple of SCCs: ::
233
234     main :: IO ()
235     main = do let xs = [1..1000000]
236               let ys = [1..2000000]
237               print $ {-# SCC last_xs #-} last xs
238               print $ {-# SCC last_init_xs #-} last $ init xs
239               print $ {-# SCC last_ys #-} last ys
240               print $ {-# SCC last_init_ys #-} last $ init ys
241
242 which gives this profile when run:
243
244 .. code-block:: none
245
246     COST CENTRE     MODULE                  no.     entries  %time %alloc   %time %alloc
247
248     MAIN            MAIN                    102           0    0.0    0.0   100.0  100.0
249      CAF            GHC.IO.Handle.FD        130           0    0.0    0.0     0.0    0.0
250      CAF            GHC.IO.Encoding.Iconv   122           0    0.0    0.0     0.0    0.0
251      CAF            GHC.Conc.Signal         111           0    0.0    0.0     0.0    0.0
252      CAF            Main                    108           0    0.0    0.0   100.0  100.0
253       main          Main                    204           1    0.0    0.0   100.0  100.0
254        last_init_ys Main                    210           1   25.0   27.4    25.0   27.4
255        main.ys      Main                    209           1   25.0   39.2    25.0   39.2
256        last_ys      Main                    208           1   12.5    0.0    12.5    0.0
257        last_init_xs Main                    207           1   12.5   13.7    12.5   13.7
258        main.xs      Main                    206           1   18.8   19.6    18.8   19.6
259        last_xs      Main                    205           1    6.2    0.0     6.2    0.0
260
261 .. _prof-rules:
262
263 Rules for attributing costs
264 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
265
266 While running a program with profiling turned on, GHC maintains a
267 cost-centre stack behind the scenes, and attributes any costs (memory
268 allocation and time) to whatever the current cost-centre stack is at the
269 time the cost is incurred.
270
271 The mechanism is simple: whenever the program evaluates an expression
272 with an SCC annotation, ``{-# SCC c -#} E``, the cost centre ``c`` is
273 pushed on the current stack, and the entry count for this stack is
274 incremented by one. The stack also sometimes has to be saved and
275 restored; in particular when the program creates a thunk (a lazy
276 suspension), the current cost-centre stack is stored in the thunk, and
277 restored when the thunk is evaluated. In this way, the cost-centre stack
278 is independent of the actual evaluation order used by GHC at runtime.
279
280 At a function call, GHC takes the stack stored in the function being
281 called (which for a top-level function will be empty), and *appends* it
282 to the current stack, ignoring any prefix that is identical to a prefix
283 of the current stack.
284
285 We mentioned earlier that lazy computations, i.e. thunks, capture the
286 current stack when they are created, and restore this stack when they
287 are evaluated. What about top-level thunks? They are "created" when the
288 program is compiled, so what stack should we give them? The technical
289 name for a top-level thunk is a CAF ("Constant Applicative Form"). GHC
290 assigns every CAF in a module a stack consisting of the single cost
291 centre ``M.CAF``, where ``M`` is the name of the module. It is also
292 possible to give each CAF a different stack, using the option
293 :ghc-flag:`-fprof-cafs`. This is especially useful when
294 compiling with :ghc-flag:`-ffull-laziness` (as is default with :ghc-flag:`-O`
295 and higher), as constants in function bodies will be lifted to the top-level
296 and become CAFs. You will probably need to consult the Core
297 (:ghc-flag:`-ddump-simpl`) in order to determine what these CAFs correspond to.
298
299 .. index::
300    single: -fprof-cafs
301
302 .. _prof-compiler-options:
303
304 Compiler options for profiling
305 ------------------------------
306
307 .. index::
308    single: profiling; options
309    single: options; for profiling
310
311 .. ghc-flag:: -prof
312
313     To make use of the profiling system *all* modules must be compiled
314     and linked with the :ghc-flag:`-prof` option. Any ``SCC`` annotations you've
315     put in your source will spring to life.
316
317     Without a :ghc-flag:`-prof` option, your ``SCC``\ s are ignored; so you can
318     compile ``SCC``-laden code without changing it.
319
320 There are a few other profiling-related compilation options. Use them
321 *in addition to* :ghc-flag:`-prof`. These do not have to be used consistently
322 for all modules in a program.
323
324 .. ghc-flag:: -fprof-auto
325
326     *All* bindings not marked INLINE, whether exported or not, top level
327     or nested, will be given automatic ``SCC`` annotations. Functions
328     marked INLINE must be given a cost centre manually.
329
330 .. ghc-flag:: -fprof-auto-top
331
332     .. index::
333        single: cost centres; automatically inserting
334
335     GHC will automatically add ``SCC`` annotations for all top-level
336     bindings not marked INLINE. If you want a cost centre on an INLINE
337     function, you have to add it manually.
338
339 .. ghc-flag:: -fprof-auto-exported
340
341     .. index::
342        single: cost centres; automatically inserting
343
344     GHC will automatically add ``SCC`` annotations for all exported
345     functions not marked INLINE. If you want a cost centre on an INLINE
346     function, you have to add it manually.
347
348 .. ghc-flag:: -fprof-auto-calls
349
350     Adds an automatic ``SCC`` annotation to all *call sites*. This is
351     particularly useful when using profiling for the purposes of
352     generating stack traces; see the function :base-ref:`Debug.Trace.traceShow`,
353     or the :rts-flag:`-xc` RTS flag (:ref:`rts-options-debugging`) for more
354     details.
355
356 .. ghc-flag:: -fprof-cafs
357
358     The costs of all CAFs in a module are usually attributed to one
359     "big" CAF cost-centre. With this option, all CAFs get their own
360     cost-centre. An “if all else fails” option…
361
362 .. ghc-flag:: -fno-prof-auto
363
364     Disables any previous :ghc-flag:`-fprof-auto`, :ghc-flag:`-fprof-auto-top`, or
365     :ghc-flag:`-fprof-auto-exported` options.
366
367 .. ghc-flag:: -fno-prof-cafs
368
369     Disables any previous :ghc-flag:`-fprof-cafs` option.
370
371 .. ghc-flag:: -fno-prof-count-entries
372
373     Tells GHC not to collect information about how often functions are
374     entered at runtime (the "entries" column of the time profile), for
375     this module. This tends to make the profiled code run faster, and
376     hence closer to the speed of the unprofiled code, because GHC is
377     able to optimise more aggressively if it doesn't have to maintain
378     correct entry counts. This option can be useful if you aren't
379     interested in the entry counts (for example, if you only intend to
380     do heap profiling).
381
382 .. _prof-time-options:
383
384 Time and allocation profiling
385 -----------------------------
386
387 To generate a time and allocation profile, give one of the following RTS
388 options to the compiled program when you run it (RTS options should be
389 enclosed between ``+RTS ... -RTS`` as usual):
390
391 .. rts-flag:: -p
392               -P
393               -pa
394
395     .. index::
396        single: time profile
397
398     The :rts-flag:`-p` option produces a standard *time profile* report. It is
399     written into the file :file:`<stem>.prof`; the stem is taken to be the
400     program name by default, but can be overridden by the :rts-flag:`-po
401     ⟨stem⟩` flag.
402
403     The :rts-flag:`-P` option produces a more detailed report containing the
404     actual time and allocation data as well. (Not used much.)
405
406     The :rts-flag:`-pa` option produces the most detailed report containing all
407     cost centres in addition to the actual time and allocation data.
408
409 .. rts-flag:: -pj
410
411     The :rts-flag:`-pj` option produces a time/allocation profile report in JSON
412     format written into the file :file:`<program>.prof`.
413
414 .. rts-flag:: -po ⟨stem⟩
415
416     The :rts-flag:`-po ⟨stem⟩` option overrides the stem used to form the
417     output file paths for the cost-centre profiler (see :rts-flag:`-p` and
418     :rts-flag:`-pj` flags above) and heap profiler (see :rts-flag:`-h`).
419
420     For instance, running a program with ``+RTS -h -p -pohello-world`` would
421     produce a heap profile named :file:`hello-world.hp` and a cost-centre
422     profile named :file:`hello-world.prof`.
423
424 .. rts-flag:: -V ⟨secs⟩
425
426     :default: 0.02
427
428     Sets the interval that the RTS clock ticks at, which is also the sampling
429     interval of the time and allocation profile. The default is 0.02 seconds.
430     The runtime uses a single timer signal to count ticks; this timer signal is
431     used to control the context switch timer (:ref:`using-concurrent`) and the
432     heap profiling timer :ref:`rts-options-heap-prof`. Also, the time profiler
433     uses the RTS timer signal directly to record time profiling samples.
434
435     Normally, setting the :rts-flag:`-V ⟨secs⟩` option directly is not
436     necessary: the resolution of the RTS timer is adjusted automatically if a
437     short interval is requested with the :rts-flag:`-C ⟨s⟩` or :rts-flag:`-i
438     ⟨secs⟩` options. However, setting :rts-flag:`-V ⟨secs⟩` is required in
439     order to increase the resolution of the time profiler.
440
441     Using a value of zero disables the RTS clock completely, and has the
442     effect of disabling timers that depend on it: the context switch
443     timer and the heap profiling timer. Context switches will still
444     happen, but deterministically and at a rate much faster than normal.
445     Disabling the interval timer is useful for debugging, because it
446     eliminates a source of non-determinism at runtime.
447
448
449 .. rts-flag:: -xc
450
451     This option causes the runtime to print out the current cost-centre
452     stack whenever an exception is raised. This can be particularly
453     useful for debugging the location of exceptions, such as the
454     notorious ``Prelude.head: empty list`` error. See
455     :ref:`rts-options-debugging`.
456
457
458 JSON profile format
459 ~~~~~~~~~~~~~~~~~~~
460
461 When invoked with the :rts-flag:`-pj` flag the runtime will emit the cost-centre
462 profile in a machine-readable JSON format. The top-level object of this format
463 has the following properties,
464
465 ``program`` (string)
466     The name of the program
467 ``arguments`` (list of strings)
468     The command line arguments passed to the program
469 ``rts_arguments`` (list of strings)
470     The command line arguments passed to the runtime system
471 ``initial_capabilities`` (integral number)
472     How many capabilities the program was started with (e.g. using the
473     :rts-flag:`-N ⟨x⟩` option). Note that the number of capabilities may change
474     during execution due to the ``setNumCapabilities`` function.
475 ``total_time`` (number)
476     The total wall time of the program's execution in seconds.
477 ``total_ticks`` (integral number)
478     How many profiler "ticks" elapsed over the course of the program's execution.
479 ``end_time`` (number)
480     The approximate time when the program finished execution as a UNIX epoch timestamp.
481 ``tick_interval`` (float)
482     How much time between profiler ticks.
483 ``total_alloc`` (integer)
484     The cumulative allocations of the program in bytes.
485 ``cost_centres`` (list of objects)
486     A list of the program's cost centres
487 ``profile`` (object)
488     The profile tree itself
489
490 Each entry in ``cost_centres`` is an object describing a cost-centre of the
491 program having the following properies,
492
493 ``id`` (integral number)
494     A unique identifier used to refer to the cost-centre
495 ``is_caf`` (boolean)
496     Whether the cost-centre is a Constant Applicative Form (CAF)
497 ``label`` (string)
498     A descriptive string roughly identifying the cost-centre.
499 ``src_loc`` (string)
500     A string describing the source span enclosing the cost-centre.
501
502 The profile data itself is described by the ``profile`` field, which contains a
503 tree-like object (which we'll call a "cost-centre stack" here) with the
504 following properties,
505
506 ``id`` (integral number)
507     The ``id`` of a cost-centre listed in the ``cost_centres`` list.
508 ``entries`` (integral number)
509     How many times was this cost-centre entered?
510 ``ticks`` (integral number)
511     How many ticks was the program's execution inside of this cost-centre? This
512     does not include child cost-centres.
513 ``alloc`` (integral number)
514     How many bytes did the program allocate while inside of this cost-centre?
515     This does not include allocations while in child cost-centres.
516 ``children`` (list)
517     A list containing child cost-centre stacks.
518
519 For instance, a simple profile might look like this,
520
521 .. code-block:: json
522
523     {
524       "program": "Main",
525       "arguments": [
526         "nofib/shootout/n-body/Main",
527         "50000"
528       ],
529       "rts_arguments": [
530         "-pj",
531         "-hy"
532       ],
533       "end_time": "Thu Feb 23 17:15 2017",
534       "initial_capabilities": 0,
535       "total_time": 1.7,
536       "total_ticks": 1700,
537       "tick_interval": 1000,
538       "total_alloc": 3770785728,
539       "cost_centres": [
540         {
541           "id": 168,
542           "label": "IDLE",
543           "module": "IDLE",
544           "src_loc": "<built-in>",
545           "is_caf": false
546         },
547         {
548           "id": 156,
549           "label": "CAF",
550           "module": "GHC.Integer.Logarithms.Internals",
551           "src_loc": "<entire-module>",
552           "is_caf": true
553         },
554         {
555           "id": 155,
556           "label": "CAF",
557           "module": "GHC.Integer.Logarithms",
558           "src_loc": "<entire-module>",
559           "is_caf": true
560         },
561         {
562           "id": 154,
563           "label": "CAF",
564           "module": "GHC.Event.Array",
565           "src_loc": "<entire-module>",
566           "is_caf": true
567         }
568       ],
569       "profile": {
570         "id": 162,
571         "entries": 0,
572         "alloc": 688,
573         "ticks": 0,
574         "children": [
575           {
576             "id": 1,
577             "entries": 0,
578             "alloc": 208,
579             "ticks": 0,
580             "children": [
581               {
582                 "id": 22,
583                 "entries": 1,
584                 "alloc": 80,
585                 "ticks": 0,
586                 "children": []
587               }
588             ]
589           },
590           {
591             "id": 42,
592             "entries": 1,
593             "alloc": 1632,
594             "ticks": 0,
595             "children": []
596           }
597         ]
598       }
599     }
600
601
602
603
604
605 .. _prof-heap:
606
607 Profiling memory usage
608 ----------------------
609
610 In addition to profiling the time and allocation behaviour of your
611 program, you can also generate a graph of its memory usage over time.
612 This is useful for detecting the causes of space leaks, when your
613 program holds on to more memory at run-time that it needs to. Space
614 leaks lead to slower execution due to heavy garbage collector activity,
615 and may even cause the program to run out of memory altogether.
616
617 To generate a heap profile from your program:
618
619 1. Compile the program for profiling (:ref:`prof-compiler-options`).
620
621 2. Run it with one of the heap profiling options described below (eg.
622    :rts-flag:`-h` for a basic producer profile). This generates the file
623    :file:`{prog}.hp`.
624
625    If the :ref:`event log <rts-eventlog>` is enabled (with the :rts-flag:`-l`
626    runtime system flag) heap samples will additionally be emitted to the GHC
627    event log (see :ref:`heap-profiler-events` for details about event format).
628
629 3. Run :command:`hp2ps` to produce a Postscript file, :file:`{prog}.ps`. The
630    :command:`hp2ps` utility is described in detail in :ref:`hp2ps`.
631
632 4. Display the heap profile using a postscript viewer such as Ghostview,
633    or print it out on a Postscript-capable printer.
634
635 For example, here is a heap profile produced for the ``sphere`` program
636 from GHC's ``nofib`` benchmark suite,
637
638 .. image:: images/prof_scc.*
639
640 You might also want to take a look at
641 `hp2any <http://www.haskell.org/haskellwiki/Hp2any>`__, a more advanced
642 suite of tools (not distributed with GHC) for displaying heap profiles.
643
644 .. _rts-options-heap-prof:
645
646 RTS options for heap profiling
647 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
648
649 There are several different kinds of heap profile that can be generated.
650 All the different profile types yield a graph of live heap against time,
651 but they differ in how the live heap is broken down into bands. The
652 following RTS options select which break-down to use:
653
654 .. rts-flag:: -hc
655               -h
656
657     (can be shortened to :rts-flag:`-h`). Breaks down the graph by the
658     cost-centre stack which produced the data.
659
660 .. rts-flag:: -hm
661
662     Break down the live heap by the module containing the code which
663     produced the data.
664
665 .. rts-flag:: -hd
666
667     Breaks down the graph by closure description. For actual data, the
668     description is just the constructor name, for other closures it is a
669     compiler-generated string identifying the closure.
670
671 .. rts-flag:: -hy
672
673     Breaks down the graph by type. For closures which have function type
674     or unknown/polymorphic type, the string will represent an
675     approximation to the actual type.
676
677 .. rts-flag:: -hr
678
679     Break down the graph by retainer set. Retainer profiling is
680     described in more detail below (:ref:`retainer-prof`).
681
682 .. rts-flag:: -hb
683
684     Break down the graph by biography. Biographical profiling is
685     described in more detail below (:ref:`biography-prof`).
686
687 .. rts-flag:: -l
688
689     :noindex:
690
691     .. index::
692        single: eventlog; and heap profiling
693
694     Emit profile samples to the :ref:`GHC event log <rts-eventlog>`.
695     This format is both more expressive than the old ``.hp`` format
696     and can be correlated with other events over the program's runtime.
697     See :ref:`heap-profiler-events` for details on the produced event structure.
698
699 In addition, the profile can be restricted to heap data which satisfies
700 certain criteria - for example, you might want to display a profile by
701 type but only for data produced by a certain module, or a profile by
702 retainer for a certain type of data. Restrictions are specified as
703 follows:
704
705 .. comment
706
707     The flags below are marked with ``:noindex:`` to avoid duplicate
708     ID warnings from Sphinx.
709
710 .. rts-flag:: -hc ⟨name⟩
711     :noindex:
712
713     Restrict the profile to closures produced by cost-centre stacks with
714     one of the specified cost centres at the top.
715
716 .. rts-flag:: -hC ⟨name⟩
717     :noindex:
718
719     Restrict the profile to closures produced by cost-centre stacks with
720     one of the specified cost centres anywhere in the stack.
721
722 .. rts-flag:: -hm ⟨module⟩
723     :noindex:
724
725     Restrict the profile to closures produced by the specified modules.
726
727 .. rts-flag:: -hd ⟨desc⟩
728     :noindex:
729
730     Restrict the profile to closures with the specified description
731     strings.
732
733 .. rts-flag:: -hy ⟨type⟩
734     :noindex:
735
736     Restrict the profile to closures with the specified types.
737
738 .. rts-flag:: -hr ⟨cc⟩
739     :noindex:
740
741     Restrict the profile to closures with retainer sets containing
742     cost-centre stacks with one of the specified cost centres at the
743     top.
744
745 .. rts-flag:: -hb ⟨bio⟩
746     :noindex:
747
748     Restrict the profile to closures with one of the specified
749     biographies, where ⟨bio⟩ is one of ``lag``, ``drag``, ``void``, or
750     ``use``.
751
752 For example, the following options will generate a retainer profile
753 restricted to ``Branch`` and ``Leaf`` constructors:
754
755 .. code-block:: none
756
757     prog +RTS -hr -hdBranch,Leaf
758
759 There can only be one "break-down" option (eg. :rts-flag:`-hr` in the example
760 above), but there is no limit on the number of further restrictions that
761 may be applied. All the options may be combined, with one exception: GHC
762 doesn't currently support mixing the :rts-flag:`-hr` and :rts-flag:`-hb` options.
763
764 There are three more options which relate to heap profiling:
765
766 .. rts-flag:: -i ⟨secs⟩
767
768     Set the profiling (sampling) interval to ⟨secs⟩ seconds (the default
769     is 0.1 second). Fractions are allowed: for example ``-i0.2`` will
770     get 5 samples per second. This only affects heap profiling; time
771     profiles are always sampled with the frequency of the RTS clock. See
772     :ref:`prof-time-options` for changing that.
773
774 .. rts-flag:: -xt
775
776     Include the memory occupied by threads in a heap profile. Each
777     thread takes up a small area for its thread state in addition to the
778     space allocated for its stack (stacks normally start small and then
779     grow as necessary).
780
781     This includes the main thread, so using :rts-flag:`-xt` is a good way to see
782     how much stack space the program is using.
783
784     Memory occupied by threads and their stacks is labelled as “TSO” and
785     “STACK” respectively when displaying the profile by closure
786     description or type description.
787
788 .. rts-flag:: -L ⟨num⟩
789
790     Sets the maximum length of a cost-centre stack name in a heap
791     profile. Defaults to 25.
792
793 .. _retainer-prof:
794
795 Retainer Profiling
796 ~~~~~~~~~~~~~~~~~~
797
798 Retainer profiling is designed to help answer questions like “why is
799 this data being retained?”. We start by defining what we mean by a
800 retainer:
801
802     A retainer is either the system stack, an unevaluated closure
803     (thunk), or an explicitly mutable object.
804
805 In particular, constructors are *not* retainers.
806
807 An object ``B`` retains object ``A`` if (i) ``B`` is a retainer object and (ii)
808 object ``A`` can be reached by recursively following pointers starting from
809 object ``B``, but not meeting any other retainer objects on the way. Each
810 live object is retained by one or more retainer objects, collectively
811 called its retainer set, or its retainer set, or its retainers.
812
813 When retainer profiling is requested by giving the program the ``-hr``
814 option, a graph is generated which is broken down by retainer set. A
815 retainer set is displayed as a set of cost-centre stacks; because this
816 is usually too large to fit on the profile graph, each retainer set is
817 numbered and shown abbreviated on the graph along with its number, and
818 the full list of retainer sets is dumped into the file ``prog.prof``.
819
820 Retainer profiling requires multiple passes over the live heap in order
821 to discover the full retainer set for each object, which can be quite
822 slow. So we set a limit on the maximum size of a retainer set, where all
823 retainer sets larger than the maximum retainer set size are replaced by
824 the special set ``MANY``. The maximum set size defaults to 8 and can be
825 altered with the :rts-flag:`-R ⟨size⟩` RTS option:
826
827 .. rts-flag:: -R ⟨size⟩
828
829     Restrict the number of elements in a retainer set to ⟨size⟩ (default
830     8).
831
832 Hints for using retainer profiling
833 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
834
835 The definition of retainers is designed to reflect a common cause of
836 space leaks: a large structure is retained by an unevaluated
837 computation, and will be released once the computation is forced. A good
838 example is looking up a value in a finite map, where unless the lookup
839 is forced in a timely manner the unevaluated lookup will cause the whole
840 mapping to be retained. These kind of space leaks can often be
841 eliminated by forcing the relevant computations to be performed eagerly,
842 using ``seq`` or strictness annotations on data constructor fields.
843
844 Often a particular data structure is being retained by a chain of
845 unevaluated closures, only the nearest of which will be reported by
846 retainer profiling - for example ``A`` retains ``B``, ``B`` retains ``C``, and
847 ``C`` retains a large structure. There might be a large number of ``B``\s but
848 only a single ``A``, so ``A`` is really the one we're interested in eliminating.
849 However, retainer profiling will in this case report ``B`` as the retainer of
850 the large structure. To move further up the chain of retainers, we can ask for
851 another retainer profile but this time restrict the profile to ``B`` objects, so
852 we get a profile of the retainers of ``B``:
853
854 .. code-block:: none
855
856     prog +RTS -hr -hcB
857
858 This trick isn't foolproof, because there might be other ``B`` closures in
859 the heap which aren't the retainers we are interested in, but we've
860 found this to be a useful technique in most cases.
861
862 .. _biography-prof:
863
864 Biographical Profiling
865 ~~~~~~~~~~~~~~~~~~~~~~
866
867 A typical heap object may be in one of the following four states at each
868 point in its lifetime:
869
870 -  The lag stage, which is the time between creation and the first use
871    of the object,
872
873 -  the use stage, which lasts from the first use until the last use of
874    the object, and
875
876 -  The drag stage, which lasts from the final use until the last
877    reference to the object is dropped.
878
879 -  An object which is never used is said to be in the void state for its
880    whole lifetime.
881
882 A biographical heap profile displays the portion of the live heap in
883 each of the four states listed above. Usually the most interesting
884 states are the void and drag states: live heap in these states is more
885 likely to be wasted space than heap in the lag or use states.
886
887 It is also possible to break down the heap in one or more of these
888 states by a different criteria, by restricting a profile by biography.
889 For example, to show the portion of the heap in the drag or void state
890 by producer:
891
892 .. code-block:: none
893
894     prog +RTS -hc -hbdrag,void
895
896 Once you know the producer or the type of the heap in the drag or void
897 states, the next step is usually to find the retainer(s):
898
899 .. code-block:: none
900
901     prog +RTS -hr -hccc...
902
903 .. note::
904     This two stage process is required because GHC cannot currently
905     profile using both biographical and retainer information simultaneously.
906
907 .. _mem-residency:
908
909 Actual memory residency
910 ~~~~~~~~~~~~~~~~~~~~~~~
911
912 How does the heap residency reported by the heap profiler relate to the
913 actual memory residency of your program when you run it? You might see a
914 large discrepancy between the residency reported by the heap profiler,
915 and the residency reported by tools on your system (eg. ``ps`` or
916 ``top`` on Unix, or the Task Manager on Windows). There are several
917 reasons for this:
918
919 -  There is an overhead of profiling itself, which is subtracted from
920    the residency figures by the profiler. This overhead goes away when
921    compiling without profiling support, of course. The space overhead is
922    currently 2 extra words per heap object, which probably results in
923    about a 30% overhead.
924
925 -  Garbage collection requires more memory than the actual residency.  The
926    factor depends on the kind of garbage collection algorithm in use: a major GC
927    in the standard generation copying collector will usually require :math:`3L`
928    bytes of memory, where :math:`L` is the amount of live data. This is because
929    by default (see the RTS :rts-flag:`-F ⟨factor⟩` option) we allow the old
930    generation to grow to twice its size (:math:`2L`) before collecting it, and
931    we require additionally :math:`L` bytes to copy the live data into. When
932    using compacting collection (see the :rts-flag:`-c` option), this is reduced
933    to :math:`2L`, and can further be reduced by tweaking the :rts-flag:`-F
934    ⟨factor⟩` option. Also add the size of the allocation area (see :rts-flag:`-A
935    ⟨size⟩`).
936
937 -  The stack isn't counted in the heap profile by default. See the
938    RTS :rts-flag:`-xt` option.
939
940 -  The program text itself, the C stack, any non-heap data (e.g. data
941    allocated by foreign libraries, and data allocated by the RTS), and
942    ``mmap()``\'d memory are not counted in the heap profile.
943
944 .. _hp2ps:
945
946 ``hp2ps`` -- Rendering heap profiles to PostScript
947 --------------------------------------------------
948
949 .. index::
950    single: hp2ps
951    single: heap profiles
952    single: postscript, from heap profiles
953    single: -h⟨break-down⟩
954
955 Usage:
956
957 .. code-block:: none
958
959     hp2ps [flags] [<file>[.hp]]
960
961 The program :command:`hp2ps` program converts a ``.hp`` file produced
962 by the ``-h<break-down>`` runtime option into a PostScript graph of the
963 heap profile. By convention, the file to be processed by :command:`hp2ps` has a
964 ``.hp`` extension. The PostScript output is written to :file:`{file}@.ps`.
965 If ``<file>`` is omitted entirely, then the program behaves as a filter.
966
967 :command:`hp2ps` is distributed in :file:`ghc/utils/hp2ps` in a GHC source
968 distribution. It was originally developed by Dave Wakeling as part of
969 the HBC/LML heap profiler.
970
971 The flags are:
972
973 .. program:: hp2ps
974
975 .. option:: -d
976
977     In order to make graphs more readable, ``hp2ps`` sorts the shaded
978     bands for each identifier. The default sort ordering is for the
979     bands with the largest area to be stacked on top of the smaller
980     ones. The ``-d`` option causes rougher bands (those representing
981     series of values with the largest standard deviations) to be stacked
982     on top of smoother ones.
983
984 .. option:: -b
985
986     Normally, ``hp2ps`` puts the title of the graph in a small box at
987     the top of the page. However, if the JOB string is too long to fit
988     in a small box (more than 35 characters), then ``hp2ps`` will choose
989     to use a big box instead. The ``-b`` option forces ``hp2ps`` to use
990     a big box.
991
992 .. option:: -e⟨float⟩[in|mm|pt]
993
994     Generate encapsulated PostScript suitable for inclusion in LaTeX
995     documents. Usually, the PostScript graph is drawn in landscape mode
996     in an area 9 inches wide by 6 inches high, and ``hp2ps`` arranges
997     for this area to be approximately centred on a sheet of a4 paper.
998     This format is convenient of studying the graph in detail, but it is
999     unsuitable for inclusion in LaTeX documents. The ``-e`` option
1000     causes the graph to be drawn in portrait mode, with float specifying
1001     the width in inches, millimetres or points (the default). The
1002     resulting PostScript file conforms to the Encapsulated PostScript
1003     (EPS) convention, and it can be included in a LaTeX document using
1004     Rokicki's dvi-to-PostScript converter ``dvips``.
1005
1006 .. option:: -g
1007
1008     Create output suitable for the ``gs`` PostScript previewer (or
1009     similar). In this case the graph is printed in portrait mode without
1010     scaling. The output is unsuitable for a laser printer.
1011
1012 .. option:: -l
1013
1014     Normally a profile is limited to 20 bands with additional
1015     identifiers being grouped into an ``OTHER`` band. The ``-l`` flag
1016     removes this 20 band and limit, producing as many bands as
1017     necessary. No key is produced as it won't fit!. It is useful for
1018     creation time profiles with many bands.
1019
1020 .. option:: -m⟨int⟩
1021
1022     Normally a profile is limited to 20 bands with additional
1023     identifiers being grouped into an ``OTHER`` band. The ``-m`` flag
1024     specifies an alternative band limit (the maximum is 20).
1025
1026     ``-m0`` requests the band limit to be removed. As many bands as
1027     necessary are produced. However no key is produced as it won't fit!
1028     It is useful for displaying creation time profiles with many bands.
1029
1030 .. option:: -p
1031
1032     Use previous parameters. By default, the PostScript graph is
1033     automatically scaled both horizontally and vertically so that it
1034     fills the page. However, when preparing a series of graphs for use
1035     in a presentation, it is often useful to draw a new graph using the
1036     same scale, shading and ordering as a previous one. The ``-p`` flag
1037     causes the graph to be drawn using the parameters determined by a
1038     previous run of ``hp2ps`` on ``file``. These are extracted from
1039     ``file@.aux``.
1040
1041 .. option:: -s
1042
1043     Use a small box for the title.
1044
1045 .. option:: -t⟨float⟩
1046
1047     Normally trace elements which sum to a total of less than 1% of the
1048     profile are removed from the profile. The ``-t`` option allows this
1049     percentage to be modified (maximum 5%).
1050
1051     ``-t0`` requests no trace elements to be removed from the profile,
1052     ensuring that all the data will be displayed.
1053
1054 .. option:: -c
1055
1056     Generate colour output.
1057
1058 .. option:: -y
1059
1060     Ignore marks.
1061
1062 .. option:: -?
1063
1064     Print out usage information.
1065
1066 .. _manipulating-hp:
1067
1068 Manipulating the ``hp`` file
1069 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1070
1071 (Notes kindly offered by Jan-Willem Maessen.)
1072
1073 The ``FOO.hp`` file produced when you ask for the heap profile of a
1074 program ``FOO`` is a text file with a particularly simple structure.
1075 Here's a representative example, with much of the actual data omitted:
1076
1077 .. code-block:: none
1078
1079     JOB "FOO -hC"
1080     DATE "Thu Dec 26 18:17 2002"
1081     SAMPLE_UNIT "seconds"
1082     VALUE_UNIT "bytes"
1083     BEGIN_SAMPLE 0.00
1084     END_SAMPLE 0.00
1085     BEGIN_SAMPLE 15.07
1086       ... sample data ...
1087     END_SAMPLE 15.07
1088     BEGIN_SAMPLE 30.23
1089       ... sample data ...
1090     END_SAMPLE 30.23
1091     ... etc.
1092     BEGIN_SAMPLE 11695.47
1093     END_SAMPLE 11695.47
1094
1095 The first four lines (``JOB``, ``DATE``, ``SAMPLE_UNIT``,
1096 ``VALUE_UNIT``) form a header. Each block of lines starting with
1097 ``BEGIN_SAMPLE`` and ending with ``END_SAMPLE`` forms a single sample
1098 (you can think of this as a vertical slice of your heap profile). The
1099 hp2ps utility should accept any input with a properly-formatted header
1100 followed by a series of *complete* samples.
1101
1102 Zooming in on regions of your profile
1103 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1104
1105 You can look at particular regions of your profile simply by loading a
1106 copy of the ``.hp`` file into a text editor and deleting the unwanted
1107 samples. The resulting ``.hp`` file can be run through ``hp2ps`` and
1108 viewed or printed.
1109
1110 Viewing the heap profile of a running program
1111 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1112
1113 The ``.hp`` file is generated incrementally as your program runs. In
1114 principle, running :command:`hp2ps` on the incomplete file should produce a
1115 snapshot of your program's heap usage. However, the last sample in the
1116 file may be incomplete, causing :command:`hp2ps` to fail. If you are using a
1117 machine with UNIX utilities installed, it's not too hard to work around
1118 this problem (though the resulting command line looks rather Byzantine):
1119
1120 .. code-block:: sh
1121
1122     head -`fgrep -n END_SAMPLE FOO.hp | tail -1 | cut -d : -f 1` FOO.hp \
1123         | hp2ps > FOO.ps
1124
1125 The command ``fgrep -n END_SAMPLE FOO.hp`` finds the end of every
1126 complete sample in ``FOO.hp``, and labels each sample with its ending
1127 line number. We then select the line number of the last complete sample
1128 using :command:`tail` and :command:`cut`. This is used as a parameter to :command:`head`; the
1129 result is as if we deleted the final incomplete sample from :file:`FOO.hp`.
1130 This results in a properly-formatted .hp file which we feed directly to
1131 :command:`hp2ps`.
1132
1133 Viewing a heap profile in real time
1134 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1135
1136 The :command:`gv` and :command:`ghostview` programs have a "watch file" option
1137 can be used to view an up-to-date heap profile of your program as it runs.
1138 Simply generate an incremental heap profile as described in the previous
1139 section. Run :command:`gv` on your profile:
1140
1141 .. code-block:: sh
1142
1143       gv -watch -orientation=seascape FOO.ps
1144
1145 If you forget the ``-watch`` flag you can still select "Watch file" from
1146 the "State" menu. Now each time you generate a new profile ``FOO.ps``
1147 the view will update automatically.
1148
1149 This can all be encapsulated in a little script:
1150
1151 .. code-block:: sh
1152
1153       #!/bin/sh
1154       head -`fgrep -n END_SAMPLE FOO.hp | tail -1 | cut -d : -f 1` FOO.hp \
1155         | hp2ps > FOO.ps
1156       gv -watch -orientation=seascape FOO.ps &
1157       while [ 1 ] ; do
1158         sleep 10 # We generate a new profile every 10 seconds.
1159         head -`fgrep -n END_SAMPLE FOO.hp | tail -1 | cut -d : -f 1` FOO.hp \
1160           | hp2ps > FOO.ps
1161       done
1162
1163 Occasionally :command:`gv` will choke as it tries to read an incomplete copy of
1164 :file:`FOO.ps` (because :command:`hp2ps` is still running as an update occurs). A
1165 slightly more complicated script works around this problem, by using the
1166 fact that sending a SIGHUP to gv will cause it to re-read its input
1167 file:
1168
1169 .. code-block:: sh
1170
1171       #!/bin/sh
1172       head -`fgrep -n END_SAMPLE FOO.hp | tail -1 | cut -d : -f 1` FOO.hp \
1173         | hp2ps > FOO.ps
1174       gv FOO.ps &
1175       gvpsnum=$!
1176       while [ 1 ] ; do
1177         sleep 10
1178         head -`fgrep -n END_SAMPLE FOO.hp | tail -1 | cut -d : -f 1` FOO.hp \
1179           | hp2ps > FOO.ps
1180         kill -HUP $gvpsnum
1181       done
1182
1183 .. _prof-threaded:
1184
1185 Profiling Parallel and Concurrent Programs
1186 ------------------------------------------
1187
1188 Combining :ghc-flag:`-threaded` and :ghc-flag:`-prof` is perfectly fine, and
1189 indeed it is possible to profile a program running on multiple processors with
1190 the RTS :rts-flag:`-N ⟨x⟩` option. [3]_
1191
1192 Some caveats apply, however. In the current implementation, a profiled
1193 program is likely to scale much less well than the unprofiled program,
1194 because the profiling implementation uses some shared data structures
1195 which require locking in the runtime system. Furthermore, the memory
1196 allocation statistics collected by the profiled program are stored in
1197 shared memory but *not* locked (for speed), which means that these
1198 figures might be inaccurate for parallel programs.
1199
1200 We strongly recommend that you use :ghc-flag:`-fno-prof-count-entries` when
1201 compiling a program to be profiled on multiple cores, because the entry
1202 counts are also stored in shared memory, and continuously updating them
1203 on multiple cores is extremely slow.
1204
1205 We also recommend using
1206 `ThreadScope <http://www.haskell.org/haskellwiki/ThreadScope>`__ for
1207 profiling parallel programs; it offers a GUI for visualising parallel
1208 execution, and is complementary to the time and space profiling features
1209 provided with GHC.
1210
1211 .. _hpc:
1212
1213 Observing Code Coverage
1214 -----------------------
1215
1216 .. index::
1217    single: code coverage
1218    single: Haskell Program Coverage
1219    single: hpc
1220
1221 Code coverage tools allow a programmer to determine what parts of their
1222 code have been actually executed, and which parts have never actually
1223 been invoked. GHC has an option for generating instrumented code that
1224 records code coverage as part of the Haskell Program Coverage (HPC)
1225 toolkit, which is included with GHC. HPC tools can be used to render the
1226 generated code coverage information into human understandable format.
1227
1228 Correctly instrumented code provides coverage information of two kinds:
1229 source coverage and boolean-control coverage. Source coverage is the
1230 extent to which every part of the program was used, measured at three
1231 different levels: declarations (both top-level and local), alternatives
1232 (among several equations or case branches) and expressions (at every
1233 level). Boolean coverage is the extent to which each of the values True
1234 and False is obtained in every syntactic boolean context (ie. guard,
1235 condition, qualifier).
1236
1237 HPC displays both kinds of information in two primary ways: textual
1238 reports with summary statistics (``hpc report``) and sources with color
1239 mark-up (``hpc markup``). For boolean coverage, there are four possible
1240 outcomes for each guard, condition or qualifier: both True and False
1241 values occur; only True; only False; never evaluated. In hpc-markup
1242 output, highlighting with a yellow background indicates a part of the
1243 program that was never evaluated; a green background indicates an
1244 always-True expression and a red background indicates an always-False
1245 one.
1246
1247 A small example: Reciprocation
1248 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1249
1250 For an example we have a program, called :file:`Recip.hs`, which computes
1251 exact decimal representations of reciprocals, with recurring parts
1252 indicated in brackets. ::
1253
1254     reciprocal :: Int -> (String, Int)
1255     reciprocal n | n > 1 = ('0' : '.' : digits, recur)
1256                  | otherwise = error
1257                   "attempting to compute reciprocal of number <= 1"
1258       where
1259       (digits, recur) = divide n 1 []
1260     divide :: Int -> Int -> [Int] -> (String, Int)
1261     divide n c cs | c `elem` cs = ([], position c cs)
1262                   | r == 0      = (show q, 0)
1263                   | r /= 0      = (show q ++ digits, recur)
1264       where
1265       (q, r) = (c*10) `quotRem` n
1266       (digits, recur) = divide n r (c:cs)
1267
1268     position :: Int -> [Int] -> Int
1269     position n (x:xs) | n==x      = 1
1270                       | otherwise = 1 + position n xs
1271
1272     showRecip :: Int -> String
1273     showRecip n =
1274       "1/" ++ show n ++ " = " ++
1275       if r==0 then d else take p d ++ "(" ++ drop p d ++ ")"
1276       where
1277       p = length d - r
1278       (d, r) = reciprocal n
1279
1280     main = do
1281       number <- readLn
1282       putStrLn (showRecip number)
1283       main
1284
1285 HPC instrumentation is enabled with the :ghc-flag:`-fhpc` flag:
1286
1287 .. code-block:: sh
1288
1289     $ ghc -fhpc Recip.hs
1290
1291 GHC creates a subdirectory ``.hpc`` in the current directory, and puts
1292 HPC index (``.mix``) files in there, one for each module compiled. You
1293 don't need to worry about these files: they contain information needed
1294 by the ``hpc`` tool to generate the coverage data for compiled modules
1295 after the program is run.
1296
1297 .. code-block:: sh
1298
1299     $ ./Recip
1300     1/3
1301     = 0.(3)
1302
1303 Running the program generates a file with the ``.tix`` suffix, in this
1304 case :file:`Recip.tix`, which contains the coverage data for this run of the
1305 program. The program may be run multiple times (e.g. with different test
1306 data), and the coverage data from the separate runs is accumulated in
1307 the ``.tix`` file. To reset the coverage data and start again, just
1308 remove the ``.tix`` file. You can control where the ``.tix`` file
1309 is generated using the environment variable :envvar:`HPCTIXFILE`.
1310
1311 .. envvar:: HPCTIXFILE
1312
1313     Set the HPC ``.tix`` file output path.
1314
1315 Having run the program, we can generate a textual summary of coverage:
1316
1317 .. code-block:: none
1318
1319     $ hpc report Recip
1320      80% expressions used (81/101)
1321      12% boolean coverage (1/8)
1322           14% guards (1/7), 3 always True,
1323                             1 always False,
1324                             2 unevaluated
1325            0% 'if' conditions (0/1), 1 always False
1326          100% qualifiers (0/0)
1327      55% alternatives used (5/9)
1328     100% local declarations used (9/9)
1329     100% top-level declarations used (5/5)
1330
1331 We can also generate a marked-up version of the source.
1332
1333 .. code-block:: none
1334
1335     $ hpc markup Recip
1336     writing Recip.hs.html
1337
1338 This generates one file per Haskell module, and 4 index files,
1339 :file:`hpc_index.html`, :file:`hpc_index_alt.html`, :file:`hpc_index_exp.html`,
1340 :file:`hpc_index_fun.html`.
1341
1342 Options for instrumenting code for coverage
1343 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1344
1345 .. program:: hpc
1346
1347 .. ghc-flag:: -fhpc
1348
1349     Enable code coverage for the current module or modules being
1350     compiled.
1351
1352     Modules compiled with this option can be freely mixed with modules
1353     compiled without it; indeed, most libraries will typically be
1354     compiled without :ghc-flag:`-fhpc`. When the program is run, coverage data
1355     will only be generated for those modules that were compiled with
1356     :ghc-flag:`-fhpc`, and the :command:`hpc` tool will only show information about
1357     those modules.
1358
1359 The hpc toolkit
1360 ~~~~~~~~~~~~~~~
1361
1362 The hpc command has several sub-commands:
1363
1364 .. code-block:: none
1365
1366     $ hpc
1367     Usage: hpc COMMAND ...
1368
1369     Commands:
1370       help        Display help for hpc or a single command
1371     Reporting Coverage:
1372       report      Output textual report about program coverage
1373       markup      Markup Haskell source with program coverage
1374     Processing Coverage files:
1375       sum         Sum multiple .tix files in a single .tix file
1376       combine     Combine two .tix files in a single .tix file
1377       map         Map a function over a single .tix file
1378     Coverage Overlays:
1379       overlay     Generate a .tix file from an overlay file
1380       draft       Generate draft overlay that provides 100% coverage
1381     Others:
1382       show        Show .tix file in readable, verbose format
1383       version     Display version for hpc
1384
1385 In general, these options act on a ``.tix`` file after an instrumented
1386 binary has generated it.
1387
1388 The hpc tool assumes you are in the top-level directory of the location
1389 where you built your application, and the ``.tix`` file is in the same
1390 top-level directory. You can use the flag ``--srcdir`` to use ``hpc``
1391 for any other directory, and use ``--srcdir`` multiple times to analyse
1392 programs compiled from difference locations, as is typical for packages.
1393
1394 We now explain in more details the major modes of hpc.
1395
1396 hpc report
1397 ^^^^^^^^^^
1398
1399 ``hpc report`` gives a textual report of coverage. By default, all
1400 modules and packages are considered in generating report, unless include
1401 or exclude are used. The report is a summary unless the ``--per-module``
1402 flag is used. The ``--xml-output`` option allows for tools to use hpc to
1403 glean coverage.
1404
1405 .. code-block:: none
1406
1407     $ hpc help report
1408     Usage: hpc report [OPTION] .. <TIX_FILE> [<MODULE> [<MODULE> ..]]
1409
1410     Options:
1411
1412         --per-module                  show module level detail
1413         --decl-list                   show unused decls
1414         --exclude=[PACKAGE:][MODULE]  exclude MODULE and/or PACKAGE
1415         --include=[PACKAGE:][MODULE]  include MODULE and/or PACKAGE
1416         --srcdir=DIR                  path to source directory of .hs files
1417                                       multi-use of srcdir possible
1418         --hpcdir=DIR                  append sub-directory that contains .mix files
1419                                       default .hpc [rarely used]
1420         --reset-hpcdirs               empty the list of hpcdir's
1421                                       [rarely used]
1422         --xml-output                  show output in XML
1423
1424 hpc markup
1425 ^^^^^^^^^^
1426
1427 ``hpc markup`` marks up source files into colored html.
1428
1429 .. code-block:: none
1430
1431     $ hpc help markup
1432     Usage: hpc markup [OPTION] .. <TIX_FILE> [<MODULE> [<MODULE> ..]]
1433
1434     Options:
1435
1436         --exclude=[PACKAGE:][MODULE]  exclude MODULE and/or PACKAGE
1437         --include=[PACKAGE:][MODULE]  include MODULE and/or PACKAGE
1438         --srcdir=DIR                  path to source directory of .hs files
1439                                       multi-use of srcdir possible
1440         --hpcdir=DIR                  append sub-directory that contains .mix files
1441                                       default .hpc [rarely used]
1442         --reset-hpcdirs               empty the list of hpcdir's
1443                                       [rarely used]
1444         --fun-entry-count             show top-level function entry counts
1445         --highlight-covered           highlight covered code, rather that code gaps
1446         --destdir=DIR                 path to write output to
1447
1448 hpc sum
1449 ^^^^^^^
1450
1451 ``hpc sum`` adds together any number of ``.tix`` files into a single
1452 ``.tix`` file. ``hpc sum`` does not change the original ``.tix`` file;
1453 it generates a new ``.tix`` file.
1454
1455 .. code-block:: none
1456
1457     $ hpc help sum
1458     Usage: hpc sum [OPTION] .. <TIX_FILE> [<TIX_FILE> [<TIX_FILE> ..]]
1459     Sum multiple .tix files in a single .tix file
1460
1461     Options:
1462
1463         --exclude=[PACKAGE:][MODULE]  exclude MODULE and/or PACKAGE
1464         --include=[PACKAGE:][MODULE]  include MODULE and/or PACKAGE
1465         --output=FILE                 output FILE
1466         --union                       use the union of the module namespace (default is intersection)
1467
1468 hpc combine
1469 ^^^^^^^^^^^
1470
1471 ``hpc combine`` is the swiss army knife of ``hpc``. It can be used to
1472 take the difference between ``.tix`` files, to subtract one ``.tix``
1473 file from another, or to add two ``.tix`` files. hpc combine does not
1474 change the original ``.tix`` file; it generates a new ``.tix`` file.
1475
1476 .. code-block:: none
1477
1478     $ hpc help combine
1479     Usage: hpc combine [OPTION] .. <TIX_FILE> <TIX_FILE>
1480     Combine two .tix files in a single .tix file
1481
1482     Options:
1483
1484         --exclude=[PACKAGE:][MODULE]  exclude MODULE and/or PACKAGE
1485         --include=[PACKAGE:][MODULE]  include MODULE and/or PACKAGE
1486         --output=FILE                 output FILE
1487         --function=FUNCTION           combine .tix files with join function, default = ADD
1488                                       FUNCTION = ADD | DIFF | SUB
1489         --union                       use the union of the module namespace (default is intersection)
1490
1491 hpc map
1492 ^^^^^^^
1493
1494 hpc map inverts or zeros a ``.tix`` file. hpc map does not change the
1495 original ``.tix`` file; it generates a new ``.tix`` file.
1496
1497 .. code-block:: none
1498
1499     $ hpc help map
1500     Usage: hpc map [OPTION] .. <TIX_FILE>
1501     Map a function over a single .tix file
1502
1503     Options:
1504
1505         --exclude=[PACKAGE:][MODULE]  exclude MODULE and/or PACKAGE
1506         --include=[PACKAGE:][MODULE]  include MODULE and/or PACKAGE
1507         --output=FILE                 output FILE
1508         --function=FUNCTION           apply function to .tix files, default = ID
1509                                       FUNCTION = ID | INV | ZERO
1510         --union                       use the union of the module namespace (default is intersection)
1511
1512 hpc overlay and hpc draft
1513 ^^^^^^^^^^^^^^^^^^^^^^^^^
1514
1515 Overlays are an experimental feature of HPC, a textual description of
1516 coverage. hpc draft is used to generate a draft overlay from a .tix
1517 file, and hpc overlay generates a .tix files from an overlay.
1518
1519 .. code-block:: none
1520
1521     % hpc help overlay
1522     Usage: hpc overlay [OPTION] .. <OVERLAY_FILE> [<OVERLAY_FILE> [...]]
1523
1524     Options:
1525
1526         --srcdir=DIR   path to source directory of .hs files
1527                        multi-use of srcdir possible
1528         --hpcdir=DIR                  append sub-directory that contains .mix files
1529                                       default .hpc [rarely used]
1530         --reset-hpcdirs               empty the list of hpcdir's
1531                                       [rarely used]
1532         --output=FILE  output FILE
1533     % hpc help draft
1534     Usage: hpc draft [OPTION] .. <TIX_FILE>
1535
1536     Options:
1537
1538         --exclude=[PACKAGE:][MODULE]  exclude MODULE and/or PACKAGE
1539         --include=[PACKAGE:][MODULE]  include MODULE and/or PACKAGE
1540         --srcdir=DIR                  path to source directory of .hs files
1541                                       multi-use of srcdir possible
1542         --hpcdir=DIR                  append sub-directory that contains .mix files
1543                                       default .hpc [rarely used]
1544         --reset-hpcdirs               empty the list of hpcdir's
1545                                       [rarely used]
1546         --output=FILE                 output FILE
1547
1548 Caveats and Shortcomings of Haskell Program Coverage
1549 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1550
1551 HPC does not attempt to lock the ``.tix`` file, so multiple concurrently
1552 running binaries in the same directory will exhibit a race condition.
1553 At compile time, there is no way to change the name of the ``.tix`` file generated;
1554 at runtime, the name of the generated ``.tix`` file can be changed
1555 using :envvar:`HPCTIXFILE`; the name of the ``.tix`` file
1556 will also change if you rename the binary.  HPC does not work with GHCi.
1557
1558 .. _ticky-ticky:
1559
1560 Using “ticky-ticky” profiling (for implementors)
1561 ------------------------------------------------
1562
1563 .. index::
1564    single: ticky-ticky profiling
1565
1566 .. ghc-flag:: -ticky
1567
1568    Enable ticky-ticky profiling.
1569
1570 Because ticky-ticky profiling requires a certain familiarity with GHC
1571 internals, we have moved the documentation to the GHC developers wiki.
1572 Take a look at its
1573 :ghc-wiki:`overview of the profiling options <Commentary/Profiling>`,
1574 which includeds a link to the ticky-ticky profiling page.
1575
1576 .. [1]
1577    :ghc-flag:`-fprof-auto` was known as ``-auto-all`` prior to
1578    GHC 7.4.1.
1579
1580 .. [2]
1581    Note that this policy has changed slightly in GHC 7.4.1 relative to
1582    earlier versions, and may yet change further, feedback is welcome.
1583
1584 .. [3]
1585    This feature was added in GHC 7.4.1.