users_guide: Convert mkUserGuidePart generation to a Sphinx extension
[ghc.git] / docs / users_guide / debugging.rst
1 .. _options-debugging:
2
3 Debugging the compiler
4 ======================
5
6 .. index::
7    single: debugging options (for GHC)
8
9 HACKER TERRITORY. HACKER TERRITORY. (You were warned.)
10
11 .. _dumping-output:
12
13 Dumping out compiler intermediate structures
14 --------------------------------------------
15
16 .. index::
17    single: dumping GHC intermediates
18    single: intermediate passes, output
19
20 ``-ddump-`` ⟨pass⟩
21     .. index::
22        single: -ddump options
23
24     Make a debugging dump after pass ``<pass>`` (may be common enough to
25     need a short form…). You can get all of these at once (*lots* of
26     output) by using ``-v5``, or most of them with ``-v4``. You can
27     prevent them from clogging up your standard output by passing
28     :ghc-flag:`-ddump-to-file`. Some of the most useful ones are:
29
30     .. ghc-flag:: -ddump-to-file
31         :shortdesc: Dump to files instead of stdout
32         :type: dynamic
33         :category:
34
35         Causes the output from all of the flags listed below to be dumped
36         to a file. The file name depends upon the output produced; for instance,
37         output from :ghc-flag:`-ddump-simpl` will end up in
38         :file:`{module}.dump-simpl`.
39
40     .. ghc-flag:: -ddump-parsed
41         :shortdesc: Dump parse tree
42         :type: dynamic
43         :category:
44
45         Dump parser output
46
47     .. ghc-flag:: -ddump-parsed-ast
48         :shortdesc: Dump parser output as a syntax tree
49         :type: dynamic
50         :category:
51
52         Dump parser output as a syntax tree
53
54     .. ghc-flag:: -ddump-rn
55         :shortdesc: Dump renamer output
56         :type: dynamic
57         :category:
58
59         Dump renamer output
60
61     .. ghc-flag:: -ddump-rn-ast
62         :shortdesc: Dump renamer output as a syntax tree
63         :type: dynamic
64         :category:
65
66         Dump renamer output as a syntax tree
67
68     .. ghc-flag:: -ddump-tc
69         :shortdesc: Dump typechecker output
70         :type: dynamic
71         :category:
72
73         Dump typechecker output
74
75     .. ghc-flag:: -ddump-tc-ast
76         :shortdesc: Dump typechecker output as a syntax tree
77         :type: dynamic
78         :category:
79
80         Dump typechecker output as a syntax tree
81
82     .. ghc-flag:: -ddump-splices
83         :shortdesc: Dump TH spliced expressions, and what they evaluate to
84         :type: dynamic
85         :category:
86
87         Dump Template Haskell expressions that we splice in, and what
88         Haskell code the expression evaluates to.
89
90     .. ghc-flag:: -dth-dec-file=⟨file⟩
91         :shortdesc: Show evaluated TH declarations in a .th.hs file
92         :type: dynamic
93         :category:
94
95         Dump expansions of all top-level Template Haskell splices into ⟨file⟩.
96
97     .. ghc-flag:: -ddump-types
98         :shortdesc: Dump type signatures
99         :type: dynamic
100         :category:
101
102         Dump a type signature for each value defined at the top level of
103         the module. The list is sorted alphabetically. Using
104         :ghc-flag:`-dppr-debug` dumps a type signature for all the imported and
105         system-defined things as well; useful for debugging the
106         compiler.
107
108     .. ghc-flag:: -ddump-deriv
109         :shortdesc: Dump deriving output
110         :type: dynamic
111         :category:
112
113         Dump derived instances
114
115     .. ghc-flag:: -ddump-ds
116         :shortdesc: Dump desugarer output
117         :type: dynamic
118         :category:
119
120         Dump desugarer output
121
122     .. ghc-flag:: -ddump-spec
123         :shortdesc: Dump specialiser output
124         :type: dynamic
125         :category:
126
127         Dump output of specialisation pass
128
129     .. ghc-flag:: -ddump-rules
130         :shortdesc: Dump rewrite rules
131         :type: dynamic
132         :category:
133
134         Dumps all rewrite rules specified in this module; see
135         :ref:`controlling-rules`.
136
137     .. ghc-flag:: -ddump-rule-firings
138         :shortdesc: Dump rule firing info
139         :type: dynamic
140         :category:
141
142         Dumps the names of all rules that fired in this module
143
144     .. ghc-flag:: -ddump-rule-rewrites
145         :shortdesc: Dump detailed rule firing info
146         :type: dynamic
147         :category:
148
149         Dumps detailed information about all rules that fired in this
150         module
151
152     .. ghc-flag:: -ddump-vect
153         :shortdesc: Dump vectoriser input and output
154         :type: dynamic
155         :category:
156
157         Dumps the output of the vectoriser.
158
159     .. ghc-flag:: -ddump-simpl
160         :shortdesc: Dump final simplifier output
161         :type: dynamic
162         :category:
163
164         Dump simplifier output (Core-to-Core passes)
165
166     .. ghc-flag:: -ddump-inlinings
167         :shortdesc: Dump inlining info
168         :type: dynamic
169         :category:
170
171         Dumps inlining info from the simplifier. Note that if used in
172         conjunction with :ghc-flag:`-dverbose-core2core` the compiler will
173         also dump the inlinings that it considers but passes up, along with
174         its rationale.
175
176     .. ghc-flag:: -ddump-stranal
177         :shortdesc: Dump strictness analyser output
178         :type: dynamic
179         :category:
180
181         Dump strictness analyser output
182
183     .. ghc-flag:: -ddump-str-signatures
184         :shortdesc: Dump strictness signatures
185         :type: dynamic
186         :category:
187
188         Dump strictness signatures
189
190     .. ghc-flag:: -ddump-cse
191         :shortdesc: Dump CSE output
192         :type: dynamic
193         :category:
194
195         Dump common subexpression elimination (CSE) pass output
196
197     .. ghc-flag:: -ddump-worker-wrapper
198         :shortdesc: Dump worker-wrapper output
199         :type: dynamic
200         :category:
201
202         Dump worker/wrapper split output
203
204     .. ghc-flag:: -ddump-occur-anal
205         :shortdesc: Dump occurrence analysis output
206         :type: dynamic
207         :category:
208
209         Dump "occurrence analysis" output
210
211     .. ghc-flag:: -ddump-prep
212         :shortdesc: Dump prepared core
213         :type: dynamic
214         :category:
215
216         Dump output of Core preparation pass
217
218     .. ghc-flag:: -ddump-stg
219         :shortdesc: Dump final STG
220         :type: dynamic
221         :category:
222
223         Dump output of STG-to-STG passes
224
225     .. ghc-flag:: -ddump-cmm
226         :shortdesc: Dump the final C-- output
227         :type: dynamic
228         :category:
229
230         Dump the result of the C-- pipeline processing
231
232     .. ghc-flag:: -ddump-cmm-from-stg
233         :shortdesc: Dump STG-to-C-- output
234         :type: dynamic
235         :category:
236
237         Dump the result of STG-to-C-- conversion
238
239     .. ghc-flag:: -ddump-cmm-verbose
240         :shortdesc: Show output from each C-- pipeline pass
241         :type: dynamic
242         :category:
243
244         Dump output from all C-- pipeline stages. In case of
245         ``.cmm`` compilation this also dumps the result of
246         file parsing.
247
248     .. ghc-flag:: -ddump-opt-cmm
249         :shortdesc: Dump the results of C-- to C-- optimising passes
250         :type: dynamic
251         :category:
252
253         Dump the results of C-- to C-- optimising passes.
254
255     .. ghc-flag:: -ddump-asm
256         :shortdesc: Dump assembly
257         :type: dynamic
258         :category:
259
260         Dump assembly language produced by the :ref:`native code
261         generator <native-code-gen>`
262
263     .. ghc-flag:: -ddump-llvm
264         :shortdesc: Dump LLVM intermediate code.
265             Implies :ghc-flag:`-fllvm`.
266         :type: dynamic
267         :category:
268
269         :implies: :ghc-flag:`-fllvm`
270
271         LLVM code from the :ref:`LLVM code generator <llvm-code-gen>`
272
273     .. ghc-flag:: -ddump-bcos
274         :shortdesc: Dump interpreter byte code
275         :type: dynamic
276         :category:
277
278         Dump byte-code compiler output
279
280     .. ghc-flag:: -ddump-foreign
281         :shortdesc: Dump ``foreign export`` stubs
282         :type: dynamic
283         :category:
284
285         dump foreign export stubs
286
287     .. ghc-flag:: -ddump-json
288         :shortdesc: Dump error messages as JSON documents
289         :type: dynamic
290         :category:
291
292          Dump error messages as JSON documents. This is intended to be consumed
293          by external tooling. A good way to use it is in conjunction with
294          :ghc-flag:`-ddump-to-file`.
295
296 .. ghc-flag:: -ddump-simpl-iterations
297     :shortdesc: Dump output from each simplifier iteration
298     :type: dynamic
299     :category:
300
301     Show the output of each *iteration* of the simplifier (each run of
302     the simplifier has a maximum number of iterations, normally 4). This
303     outputs even more information than ``-ddump-simpl-phases``.
304
305 .. ghc-flag:: -ddump-simpl-stats
306     :shortdesc: Dump simplifier stats
307     :type: dynamic
308     :category:
309
310     Dump statistics about how many of each kind of transformation too
311     place. If you add ``-dppr-debug`` you get more detailed information.
312
313 .. ghc-flag:: -ddump-if-trace
314     :shortdesc: Trace interface files
315     :type: dynamic
316     :category:
317
318     Make the interface loader be *real* chatty about what it is up to.
319
320 .. ghc-flag:: -ddump-tc-trace
321     :shortdesc: Trace typechecker
322     :type: dynamic
323     :category:
324
325     Make the type checker be *real* chatty about what it is up to.
326
327 .. ghc-flag:: -ddump-vt-trace
328     :shortdesc: Trace vectoriser
329     :type: dynamic
330     :category:
331
332     Make the vectoriser be *real* chatty about what it is up to.
333
334 .. ghc-flag:: -ddump-rn-trace
335     :shortdesc: Trace renamer
336     :type: dynamic
337     :category:
338
339     Make the renamer be *real* chatty about what it is up to.
340
341 .. ghc-flag:: -ddump-ec-trace
342     :shortdesc: Trace exhaustiveness checker
343     :type: dynamic
344     :category:
345
346     Make the pattern match exhaustiveness checker be *real* chatty about
347     what it is up to.
348
349 .. ghc-flag:: -ddump-rn-stats
350     :shortdesc: Renamer stats
351     :type: dynamic
352     :category:
353
354     Print out summary of what kind of information the renamer had to
355     bring in.
356
357 .. ghc-flag:: -dverbose-core2core
358     :shortdesc: Show output from each core-to-core pass
359     :type: dynamic
360     :category:
361
362     Show the output of the intermediate Core-to-Core pass. (*lots* of output!)
363     So: when we're really desperate:
364
365     .. code-block:: sh
366
367         % ghc -noC -O -ddump-simpl -dverbose-core2core -dcore-lint Foo.hs
368
369 .. ghc-flag:: -dverbose-stg2stg
370     :shortdesc: Show output from each STG-to-STG pass
371     :type: dynamic
372     :category:
373
374     Show the output of the intermediate STG-to-STG pass. (*lots* of output!)
375
376 .. ghc-flag:: -dshow-passes
377     :shortdesc: Print out each pass name as it happens
378     :type: dynamic
379     :category:
380
381     Print out each pass name, its runtime and heap allocations as it happens.
382     Note that this may come at a slight performance cost as the compiler will
383     be a bit more eager in forcing pass results to more accurately account for
384     their costs.
385
386     Two types of messages are produced: Those beginning with ``***`` are
387     denote the beginning of a compilation phase whereas those starting with
388     ``!!!`` mark the end of a pass and are accompanied by allocation and
389     runtime statistics.
390
391 .. ghc-flag:: -ddump-core-stats
392     :shortdesc: Print a one-line summary of the size of the Core program at the
393         end of the optimisation pipeline
394     :type: dynamic
395     :category:
396
397     Print a one-line summary of the size of the Core program at the end
398     of the optimisation pipeline.
399
400 .. ghc-flag:: -dfaststring-stats
401     :shortdesc: Show statistics for fast string usage when finished
402     :type: dynamic
403     :category:
404
405     Show statistics on the usage of fast strings by the compiler.
406
407 .. ghc-flag:: -dppr-debug
408     :shortdesc: Turn on debug printing (more verbose)
409     :type: dynamic
410     :category:
411
412     Debugging output is in one of several "styles." Take the printing of
413     types, for example. In the "user" style (the default), the
414     compiler's internal ideas about types are presented in Haskell
415     source-level syntax, insofar as possible. In the "debug" style
416     (which is the default for debugging output), the types are printed
417     in with explicit foralls, and variables have their unique-id
418     attached (so you can check for things that look the same but
419     aren't). This flag makes debugging output appear in the more verbose
420     debug style.
421
422
423 .. _formatting dumps:
424
425 Formatting dumps
426 ----------------
427
428 .. index::
429    single: formatting dumps
430
431 .. ghc-flag:: -dppr-user-length
432     :shortdesc: Set the depth for printing expressions in error msgs
433     :type: dynamic
434     :category:
435
436     In error messages, expressions are printed to a certain "depth",
437     with subexpressions beyond the depth replaced by ellipses. This flag
438     sets the depth. Its default value is 5.
439
440 .. ghc-flag:: -dppr-cols=⟨n⟩
441     :shortdesc: Set the width of debugging output. For example ``-dppr-cols200``
442     :type: dynamic
443     :category:
444
445     Set the width of debugging output. Use this if your code is wrapping
446     too much. For example: ``-dppr-cols=200``.
447
448 .. ghc-flag:: -dppr-case-as-let
449     :shortdesc: Print single alternative case expressions as strict lets.
450     :type: dynamic
451     :category:
452
453     Print single alternative case expressions as though they were strict
454     let expressions. This is helpful when your code does a lot of
455     unboxing.
456
457 .. ghc-flag:: -dno-debug-output
458     :shortdesc: Suppress unsolicited debugging output
459     :type: dynamic
460     :category:
461
462     Suppress any unsolicited debugging output. When GHC has been built
463     with the ``DEBUG`` option it occasionally emits debug output of
464     interest to developers. The extra output can confuse the testing
465     framework and cause bogus test failures, so this flag is provided to
466     turn it off.
467
468 .. _suppression:
469
470 Suppressing unwanted information
471 --------------------------------
472
473 .. index::
474    single: suppression; of unwanted dump output
475
476 Core dumps contain a large amount of information. Depending on what you
477 are doing, not all of it will be useful. Use these flags to suppress the
478 parts that you are not interested in.
479
480 .. ghc-flag:: -dsuppress-all
481     :shortdesc: In core dumps, suppress everything (except for uniques) that is
482         suppressible.
483     :type: dynamic
484     :category:
485
486     Suppress everything that can be suppressed, except for unique ids as
487     this often makes the printout ambiguous. If you just want to see the
488     overall structure of the code, then start here.
489
490 .. ghc-flag:: -dsuppress-ticks
491     :shortdesc: Suppress "ticks" in the pretty-printer output.
492     :type: dynamic
493     :category:
494
495     Suppress "ticks" in the pretty-printer output.
496
497 .. ghc-flag:: -dsuppress-uniques
498     :shortdesc: Suppress the printing of uniques in debug output (easier to use
499         ``diff``)
500     :type: dynamic
501     :category:
502
503     Suppress the printing of uniques. This may make the printout
504     ambiguous (e.g. unclear where an occurrence of 'x' is bound), but it
505     makes the output of two compiler runs have many fewer gratuitous
506     differences, so you can realistically apply ``diff``. Once ``diff``
507     has shown you where to look, you can try again without
508     :ghc-flag:`-dsuppress-uniques`
509
510 .. ghc-flag:: -dsuppress-idinfo
511     :shortdesc: Suppress extended information about identifiers where they
512         are bound
513     :type: dynamic
514     :category:
515
516     Suppress extended information about identifiers where they are
517     bound. This includes strictness information and inliner templates.
518     Using this flag can cut the size of the core dump in half, due to
519     the lack of inliner templates
520
521 .. ghc-flag:: -dsuppress-unfoldings
522     :shortdesc: Suppress the printing of the stable unfolding of a variable at
523         its binding site
524     :type: dynamic
525     :category:
526
527     Suppress the printing of the stable unfolding of a variable at its
528     binding site.
529
530 .. ghc-flag:: -dsuppress-module-prefixes
531     :shortdesc: Suppress the printing of module qualification prefixes
532     :type: dynamic
533     :category:
534
535     Suppress the printing of module qualification prefixes. This is the
536     ``Data.List`` in ``Data.List.length``.
537
538 .. ghc-flag:: -dsuppress-type-signatures
539     :shortdesc: Suppress type signatures
540     :type: dynamic
541     :category:
542
543     Suppress the printing of type signatures.
544
545 .. ghc-flag:: -dsuppress-type-applications
546     :shortdesc: Suppress type applications
547     :type: dynamic
548     :category:
549
550     Suppress the printing of type applications.
551
552 .. ghc-flag:: -dsuppress-coercions
553     :shortdesc: Suppress the printing of coercions in Core dumps to make them
554         shorter
555     :type: dynamic
556     :category:
557
558     Suppress the printing of type coercions.
559
560 .. _checking-consistency:
561
562 Checking for consistency
563 ------------------------
564
565 .. index::
566    single: consistency checks
567    single: lint
568
569 .. ghc-flag:: -dcore-lint
570     :shortdesc: Turn on internal sanity checking
571     :type: dynamic
572     :category:
573
574     Turn on heavyweight intra-pass sanity-checking within GHC, at Core
575     level. (It checks GHC's sanity, not yours.)
576
577 .. ghc-flag:: -dstg-lint
578     :shortdesc: STG pass sanity checking
579     :type: dynamic
580     :category:
581
582     Ditto for STG level. (note: currently doesn't work).
583
584 .. ghc-flag:: -dcmm-lint
585     :shortdesc: C-- pass sanity checking
586     :type: dynamic
587     :category:
588
589     Ditto for C-- level.
590
591 .. ghc-flag:: -fllvm-fill-undef-with-garbage
592     :shortdesc: Intruct LLVM to fill dead STG registers with garbage
593     :type: dynamic
594     :category:
595
596     Instructs the LLVM code generator to fill dead STG registers with garbage
597     instead of ``undef`` in calls. This makes it easier to catch subtle
598     code generator and runtime system bugs (e.g. see :ghc-ticket:`11487`).
599
600 .. ghc-flag:: -fcatch-bottoms
601     :shortdesc: Insert ``error`` expressions after bottoming expressions; useful
602         when debugging the compiler.
603     :type: dynamic
604     :category:
605
606     Instructs the simplifier to emit ``error`` expressions in the continuation
607     of empty case analyses (which should bottom and consequently not return).
608     This is helpful when debugging demand analysis bugs which can sometimes
609     manifest as segmentation faults.
610
611 .. _checking-determinism:
612
613 Checking for determinism
614 ------------------------
615
616 .. index::
617    single: deterministic builds
618
619 .. ghc-flag:: -dinitial-unique=⟨s⟩
620     :shortdesc: Start ``UniqSupply`` allocation from ⟨s⟩.
621     :type: dynamic
622     :category:
623
624     Start ``UniqSupply`` allocation from ⟨s⟩.
625
626 .. ghc-flag:: -dunique-increment=⟨i⟩
627     :shortdesc: Set the increment for the generated ``Unique``'s to ⟨i⟩.
628     :type: dynamic
629     :category:
630
631     Set the increment for the generated ``Unique``'s to ⟨i⟩.
632
633     This is useful in combination with :ghc-flag:`-dinitial-unique=⟨s⟩` to test
634     if the generated files depend on the order of ``Unique``'s.
635
636     Some interesting values:
637
638     * ``-dinitial-unique=0 -dunique-increment=1`` - current sequential
639       ``UniqSupply``
640     * ``-dinitial-unique=16777215 -dunique-increment=-1`` - ``UniqSupply`` that
641       generates in decreasing order
642     * ``-dinitial-unique=1 -dunique-increment=PRIME`` - where PRIME big enough
643       to overflow often - nonsequential order