debugging.rst 18.3 KB
Newer Older
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
.. _options-debugging:

Debugging the compiler
======================

.. index::
   single: debugging options (for GHC)

HACKER TERRITORY. HACKER TERRITORY. (You were warned.)

.. _dumping-output:

Dumping out compiler intermediate structures
--------------------------------------------

.. index::
   single: dumping GHC intermediates
   single: intermediate passes, output

``-ddump-`` ⟨pass⟩
    .. index::
       single: -ddump options

    Make a debugging dump after pass ``<pass>`` (may be common enough to
    need a short form…). You can get all of these at once (*lots* of
    output) by using ``-v5``, or most of them with ``-v4``. You can
    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
32
33
        :shortdesc: Dump to files instead of stdout
        :type: dynamic
        :category:
34
35
36
37
38
39
40

        Causes the output from all of the flags listed below to be dumped
        to a file. The file name depends upon the output produced; for instance,
        output from :ghc-flag:`-ddump-simpl` will end up in
        :file:`{module}.dump-simpl`.

    .. ghc-flag:: -ddump-parsed
41
42
43
        :shortdesc: Dump parse tree
        :type: dynamic
        :category:
44
45
46

        Dump parser output

47
    .. ghc-flag:: -ddump-parsed-ast
48
49
50
        :shortdesc: Dump parser output as a syntax tree
        :type: dynamic
        :category:
51
52
53

        Dump parser output as a syntax tree

54
    .. ghc-flag:: -ddump-rn
55
56
57
        :shortdesc: Dump renamer output
        :type: dynamic
        :category:
58
59
60

        Dump renamer output

61
    .. ghc-flag:: -ddump-rn-ast
62
63
64
        :shortdesc: Dump renamer output as a syntax tree
        :type: dynamic
        :category:
65
66
67

        Dump renamer output as a syntax tree

68
    .. ghc-flag:: -ddump-tc
69
70
71
        :shortdesc: Dump typechecker output
        :type: dynamic
        :category:
72
73
74

        Dump typechecker output

75
    .. ghc-flag:: -ddump-tc-ast
76
77
78
        :shortdesc: Dump typechecker output as a syntax tree
        :type: dynamic
        :category:
79
80
81

        Dump typechecker output as a syntax tree

82
    .. ghc-flag:: -ddump-splices
83
84
85
        :shortdesc: Dump TH spliced expressions, and what they evaluate to
        :type: dynamic
        :category:
86
87
88
89

        Dump Template Haskell expressions that we splice in, and what
        Haskell code the expression evaluates to.

90
    .. ghc-flag:: -dth-dec-file=⟨file⟩
91
92
93
        :shortdesc: Show evaluated TH declarations in a .th.hs file
        :type: dynamic
        :category:
94
95
96

        Dump expansions of all top-level Template Haskell splices into ⟨file⟩.

97
    .. ghc-flag:: -ddump-types
98
99
100
        :shortdesc: Dump type signatures
        :type: dynamic
        :category:
101
102
103

        Dump a type signature for each value defined at the top level of
        the module. The list is sorted alphabetically. Using
104
        :ghc-flag:`-dppr-debug` dumps a type signature for all the imported and
105
106
107
        system-defined things as well; useful for debugging the
        compiler.

108
    .. ghc-flag:: -ddump-deriv
109
110
111
        :shortdesc: Dump deriving output
        :type: dynamic
        :category:
112
113
114

        Dump derived instances

115
    .. ghc-flag:: -ddump-ds
116
117
118
        :shortdesc: Dump desugarer output
        :type: dynamic
        :category:
119
120
121

        Dump desugarer output

122
    .. ghc-flag:: -ddump-spec
123
124
125
        :shortdesc: Dump specialiser output
        :type: dynamic
        :category:
126
127
128

        Dump output of specialisation pass

129
    .. ghc-flag:: -ddump-rules
130
131
132
        :shortdesc: Dump rewrite rules
        :type: dynamic
        :category:
133
134
135
136

        Dumps all rewrite rules specified in this module; see
        :ref:`controlling-rules`.

137
    .. ghc-flag:: -ddump-rule-firings
138
139
140
        :shortdesc: Dump rule firing info
        :type: dynamic
        :category:
141
142
143

        Dumps the names of all rules that fired in this module

144
    .. ghc-flag:: -ddump-rule-rewrites
145
146
147
        :shortdesc: Dump detailed rule firing info
        :type: dynamic
        :category:
148
149
150
151

        Dumps detailed information about all rules that fired in this
        module

152
    .. ghc-flag:: -ddump-vect
153
154
155
        :shortdesc: Dump vectoriser input and output
        :type: dynamic
        :category:
156
157
158

        Dumps the output of the vectoriser.

159
    .. ghc-flag:: -ddump-simpl
160
161
162
        :shortdesc: Dump final simplifier output
        :type: dynamic
        :category:
163
164
165

        Dump simplifier output (Core-to-Core passes)

166
    .. ghc-flag:: -ddump-inlinings
167
168
169
        :shortdesc: Dump inlining info
        :type: dynamic
        :category:
170

171
172
173
174
        Dumps inlining info from the simplifier. Note that if used in
        conjunction with :ghc-flag:`-dverbose-core2core` the compiler will
        also dump the inlinings that it considers but passes up, along with
        its rationale.
175

176
    .. ghc-flag:: -ddump-stranal
177
178
179
        :shortdesc: Dump strictness analyser output
        :type: dynamic
        :category:
180
181
182

        Dump strictness analyser output

manav's avatar
manav committed
183
    .. ghc-flag:: -ddump-str-signatures
184
185
186
        :shortdesc: Dump strictness signatures
        :type: dynamic
        :category:
187
188
189

        Dump strictness signatures

190
    .. ghc-flag:: -ddump-cse
191
192
193
        :shortdesc: Dump CSE output
        :type: dynamic
        :category:
194
195
196

        Dump common subexpression elimination (CSE) pass output

197
    .. ghc-flag:: -ddump-worker-wrapper
198
199
200
        :shortdesc: Dump worker-wrapper output
        :type: dynamic
        :category:
201
202
203

        Dump worker/wrapper split output

204
    .. ghc-flag:: -ddump-occur-anal
205
206
207
        :shortdesc: Dump occurrence analysis output
        :type: dynamic
        :category:
208
209
210

        Dump "occurrence analysis" output

211
    .. ghc-flag:: -ddump-prep
212
213
214
        :shortdesc: Dump prepared core
        :type: dynamic
        :category:
215
216
217

        Dump output of Core preparation pass

218
    .. ghc-flag:: -ddump-stg
219
220
221
        :shortdesc: Dump final STG
        :type: dynamic
        :category:
222
223
224

        Dump output of STG-to-STG passes

225
    .. ghc-flag:: -ddump-cmm
226
227
228
        :shortdesc: Dump the final C-- output
        :type: dynamic
        :category:
229

230
231
232
        Dump the result of the C-- pipeline processing

    .. ghc-flag:: -ddump-cmm-from-stg
233
234
235
        :shortdesc: Dump STG-to-C-- output
        :type: dynamic
        :category:
236
237
238
239

        Dump the result of STG-to-C-- conversion

    .. ghc-flag:: -ddump-cmm-verbose
240
241
242
        :shortdesc: Show output from each C-- pipeline pass
        :type: dynamic
        :category:
243
244
245
246

        Dump output from all C-- pipeline stages. In case of
        ``.cmm`` compilation this also dumps the result of
        file parsing.
247

248
    .. ghc-flag:: -ddump-opt-cmm
249
250
251
        :shortdesc: Dump the results of C-- to C-- optimising passes
        :type: dynamic
        :category:
252
253
254

        Dump the results of C-- to C-- optimising passes.

255
    .. ghc-flag:: -ddump-asm
256
257
258
        :shortdesc: Dump assembly
        :type: dynamic
        :category:
259
260
261
262

        Dump assembly language produced by the :ref:`native code
        generator <native-code-gen>`

263
    .. ghc-flag:: -ddump-llvm
264
265
266
267
        :shortdesc: Dump LLVM intermediate code.
            Implies :ghc-flag:`-fllvm`.
        :type: dynamic
        :category:
268

269
270
        :implies: :ghc-flag:`-fllvm`

271
272
        LLVM code from the :ref:`LLVM code generator <llvm-code-gen>`

273
    .. ghc-flag:: -ddump-bcos
274
275
276
        :shortdesc: Dump interpreter byte code
        :type: dynamic
        :category:
277
278
279

        Dump byte-code compiler output

280
    .. ghc-flag:: -ddump-foreign
281
282
283
        :shortdesc: Dump ``foreign export`` stubs
        :type: dynamic
        :category:
284
285
286

        dump foreign export stubs

287
    .. ghc-flag:: -ddump-json
288
289
290
        :shortdesc: Dump error messages as JSON documents
        :type: dynamic
        :category:
291
292
293
294
295

         Dump error messages as JSON documents. This is intended to be consumed
         by external tooling. A good way to use it is in conjunction with
         :ghc-flag:`-ddump-to-file`.

296
.. ghc-flag:: -ddump-simpl-iterations
297
298
299
    :shortdesc: Dump output from each simplifier iteration
    :type: dynamic
    :category:
300
301
302
303
304

    Show the output of each *iteration* of the simplifier (each run of
    the simplifier has a maximum number of iterations, normally 4). This
    outputs even more information than ``-ddump-simpl-phases``.

305
.. ghc-flag:: -ddump-simpl-stats
306
307
308
    :shortdesc: Dump simplifier stats
    :type: dynamic
    :category:
309
310
311
312

    Dump statistics about how many of each kind of transformation too
    place. If you add ``-dppr-debug`` you get more detailed information.

313
.. ghc-flag:: -ddump-if-trace
314
315
316
    :shortdesc: Trace interface files
    :type: dynamic
    :category:
317
318
319

    Make the interface loader be *real* chatty about what it is up to.

320
.. ghc-flag:: -ddump-tc-trace
321
322
323
    :shortdesc: Trace typechecker
    :type: dynamic
    :category:
324
325
326

    Make the type checker be *real* chatty about what it is up to.

327
.. ghc-flag:: -ddump-vt-trace
328
329
330
    :shortdesc: Trace vectoriser
    :type: dynamic
    :category:
331
332
333

    Make the vectoriser be *real* chatty about what it is up to.

334
.. ghc-flag:: -ddump-rn-trace
335
336
337
    :shortdesc: Trace renamer
    :type: dynamic
    :category:
338
339
340

    Make the renamer be *real* chatty about what it is up to.

341
.. ghc-flag:: -ddump-ec-trace
342
343
344
    :shortdesc: Trace exhaustiveness checker
    :type: dynamic
    :category:
345
346
347
348

    Make the pattern match exhaustiveness checker be *real* chatty about
    what it is up to.

349
.. ghc-flag:: -ddump-rn-stats
350
351
352
    :shortdesc: Renamer stats
    :type: dynamic
    :category:
353
354
355
356

    Print out summary of what kind of information the renamer had to
    bring in.

357
.. ghc-flag:: -dverbose-core2core
358
359
360
    :shortdesc: Show output from each core-to-core pass
    :type: dynamic
    :category:
361

362
363
    Show the output of the intermediate Core-to-Core pass. (*lots* of output!)
    So: when we're really desperate:
364

365
    .. code-block:: sh
366
367
368

        % ghc -noC -O -ddump-simpl -dverbose-core2core -dcore-lint Foo.hs

369
370
371
372
373
374
375
.. ghc-flag:: -dverbose-stg2stg
    :shortdesc: Show output from each STG-to-STG pass
    :type: dynamic
    :category:

    Show the output of the intermediate STG-to-STG pass. (*lots* of output!)

376
.. ghc-flag:: -dshow-passes
377
378
379
    :shortdesc: Print out each pass name as it happens
    :type: dynamic
    :category:
380

381
382
383
384
385
386
387
388
389
    Print out each pass name, its runtime and heap allocations as it happens.
    Note that this may come at a slight performance cost as the compiler will
    be a bit more eager in forcing pass results to more accurately account for
    their costs.

    Two types of messages are produced: Those beginning with ``***`` are
    denote the beginning of a compilation phase whereas those starting with
    ``!!!`` mark the end of a pass and are accompanied by allocation and
    runtime statistics.
390

391
.. ghc-flag:: -ddump-core-stats
392
393
394
395
    :shortdesc: Print a one-line summary of the size of the Core program at the
        end of the optimisation pipeline
    :type: dynamic
    :category:
396
397
398
399

    Print a one-line summary of the size of the Core program at the end
    of the optimisation pipeline.

400
.. ghc-flag:: -dfaststring-stats
401
402
403
    :shortdesc: Show statistics for fast string usage when finished
    :type: dynamic
    :category:
404
405
406

    Show statistics on the usage of fast strings by the compiler.

407
.. ghc-flag:: -dppr-debug
408
409
410
    :shortdesc: Turn on debug printing (more verbose)
    :type: dynamic
    :category:
411
412
413
414
415
416
417
418
419
420
421

    Debugging output is in one of several "styles." Take the printing of
    types, for example. In the "user" style (the default), the
    compiler's internal ideas about types are presented in Haskell
    source-level syntax, insofar as possible. In the "debug" style
    (which is the default for debugging output), the types are printed
    in with explicit foralls, and variables have their unique-id
    attached (so you can check for things that look the same but
    aren't). This flag makes debugging output appear in the more verbose
    debug style.

Ben Gamari's avatar
Ben Gamari committed
422

423
424
425
426
427
428
429
430
.. _formatting dumps:

Formatting dumps
----------------

.. index::
   single: formatting dumps

431
.. ghc-flag:: -dppr-user-length
432
433
434
    :shortdesc: Set the depth for printing expressions in error msgs
    :type: dynamic
    :category:
435
436
437
438
439

    In error messages, expressions are printed to a certain "depth",
    with subexpressions beyond the depth replaced by ellipses. This flag
    sets the depth. Its default value is 5.

440
.. ghc-flag:: -dppr-cols=⟨n⟩
441
442
443
    :shortdesc: Set the width of debugging output. For example ``-dppr-cols200``
    :type: dynamic
    :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
450
451
    :shortdesc: Print single alternative case expressions as strict lets.
    :type: dynamic
    :category:
452
453
454
455
456

    Print single alternative case expressions as though they were strict
    let expressions. This is helpful when your code does a lot of
    unboxing.

457
.. ghc-flag:: -dno-debug-output
458
459
    :shortdesc: Suppress unsolicited debugging output
    :type: dynamic
460
    :reverse: -ddebug-output
461
    :category:
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480

    Suppress any unsolicited debugging output. When GHC has been built
    with the ``DEBUG`` option it occasionally emits debug output of
    interest to developers. The extra output can confuse the testing
    framework and cause bogus test failures, so this flag is provided to
    turn it off.

.. _suppression:

Suppressing unwanted information
--------------------------------

.. index::
   single: suppression; of unwanted dump output

Core dumps contain a large amount of information. Depending on what you
are doing, not all of it will be useful. Use these flags to suppress the
parts that you are not interested in.

481
.. ghc-flag:: -dsuppress-all
482
483
484
485
    :shortdesc: In core dumps, suppress everything (except for uniques) that is
        suppressible.
    :type: dynamic
    :category:
486
487
488
489
490

    Suppress everything that can be suppressed, except for unique ids as
    this often makes the printout ambiguous. If you just want to see the
    overall structure of the code, then start here.

491
.. ghc-flag:: -dsuppress-ticks
492
493
494
    :shortdesc: Suppress "ticks" in the pretty-printer output.
    :type: dynamic
    :category:
495
496
497

    Suppress "ticks" in the pretty-printer output.

498
.. ghc-flag:: -dsuppress-uniques
499
500
501
502
    :shortdesc: Suppress the printing of uniques in debug output (easier to use
        ``diff``)
    :type: dynamic
    :category:
503
504
505
506
507
508

    Suppress the printing of uniques. This may make the printout
    ambiguous (e.g. unclear where an occurrence of 'x' is bound), but it
    makes the output of two compiler runs have many fewer gratuitous
    differences, so you can realistically apply ``diff``. Once ``diff``
    has shown you where to look, you can try again without
509
    :ghc-flag:`-dsuppress-uniques`
510

511
.. ghc-flag:: -dsuppress-idinfo
512
513
514
515
    :shortdesc: Suppress extended information about identifiers where they
        are bound
    :type: dynamic
    :category:
516
517
518
519
520
521

    Suppress extended information about identifiers where they are
    bound. This includes strictness information and inliner templates.
    Using this flag can cut the size of the core dump in half, due to
    the lack of inliner templates

522
.. ghc-flag:: -dsuppress-unfoldings
523
524
525
526
    :shortdesc: Suppress the printing of the stable unfolding of a variable at
        its binding site
    :type: dynamic
    :category:
527
528
529
530

    Suppress the printing of the stable unfolding of a variable at its
    binding site.

531
.. ghc-flag:: -dsuppress-module-prefixes
532
533
534
    :shortdesc: Suppress the printing of module qualification prefixes
    :type: dynamic
    :category:
535
536
537
538

    Suppress the printing of module qualification prefixes. This is the
    ``Data.List`` in ``Data.List.length``.

539
.. ghc-flag:: -dsuppress-type-signatures
540
541
542
    :shortdesc: Suppress type signatures
    :type: dynamic
    :category:
543
544
545

    Suppress the printing of type signatures.

546
.. ghc-flag:: -dsuppress-type-applications
547
548
549
    :shortdesc: Suppress type applications
    :type: dynamic
    :category:
550
551
552

    Suppress the printing of type applications.

553
.. ghc-flag:: -dsuppress-coercions
554
555
556
557
    :shortdesc: Suppress the printing of coercions in Core dumps to make them
        shorter
    :type: dynamic
    :category:
558
559
560
561
562
563
564
565
566
567
568
569

    Suppress the printing of type coercions.

.. _checking-consistency:

Checking for consistency
------------------------

.. index::
   single: consistency checks
   single: lint

570
.. ghc-flag:: -dcore-lint
571
572
573
    :shortdesc: Turn on internal sanity checking
    :type: dynamic
    :category:
574
575
576
577

    Turn on heavyweight intra-pass sanity-checking within GHC, at Core
    level. (It checks GHC's sanity, not yours.)

578
.. ghc-flag:: -dstg-lint
579
580
581
    :shortdesc: STG pass sanity checking
    :type: dynamic
    :category:
582
583
584

    Ditto for STG level. (note: currently doesn't work).

585
.. ghc-flag:: -dcmm-lint
586
587
588
    :shortdesc: C-- pass sanity checking
    :type: dynamic
    :category:
589
590

    Ditto for C-- level.
591

592
.. ghc-flag:: -fllvm-fill-undef-with-garbage
593
594
595
    :shortdesc: Intruct LLVM to fill dead STG registers with garbage
    :type: dynamic
    :category:
596
597
598
599
600

    Instructs the LLVM code generator to fill dead STG registers with garbage
    instead of ``undef`` in calls. This makes it easier to catch subtle
    code generator and runtime system bugs (e.g. see :ghc-ticket:`11487`).

Ben Gamari's avatar
Ben Gamari committed
601
.. ghc-flag:: -fcatch-bottoms
602
603
604
605
    :shortdesc: Insert ``error`` expressions after bottoming expressions; useful
        when debugging the compiler.
    :type: dynamic
    :category:
Ben Gamari's avatar
Ben Gamari committed
606
607
608
609
610
611

    Instructs the simplifier to emit ``error`` expressions in the continuation
    of empty case analyses (which should bottom and consequently not return).
    This is helpful when debugging demand analysis bugs which can sometimes
    manifest as segmentation faults.

612
613
614
615
616
617
618
619
.. _checking-determinism:

Checking for determinism
------------------------

.. index::
   single: deterministic builds

620
.. ghc-flag:: -dinitial-unique=⟨s⟩
621
622
623
    :shortdesc: Start ``UniqSupply`` allocation from ⟨s⟩.
    :type: dynamic
    :category:
624
625
626

    Start ``UniqSupply`` allocation from ⟨s⟩.

627
.. ghc-flag:: -dunique-increment=⟨i⟩
628
629
630
    :shortdesc: Set the increment for the generated ``Unique``'s to ⟨i⟩.
    :type: dynamic
    :category:
631
632
633

    Set the increment for the generated ``Unique``'s to ⟨i⟩.

634
635
    This is useful in combination with :ghc-flag:`-dinitial-unique=⟨s⟩` to test
    if the generated files depend on the order of ``Unique``'s.
636
637
638
639
640
641
642
643
644

    Some interesting values:

    * ``-dinitial-unique=0 -dunique-increment=1`` - current sequential
      ``UniqSupply``
    * ``-dinitial-unique=16777215 -dunique-increment=-1`` - ``UniqSupply`` that
      generates in decreasing order
    * ``-dinitial-unique=1 -dunique-increment=PRIME`` - where PRIME big enough
      to overflow often - nonsequential order