bc155884c83e0107ed37987d20efd97e6548de5c
[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
32         Causes the output from all of the flags listed below to be dumped
33         to a file. The file name depends upon the output produced; for instance,
34         output from :ghc-flag:`-ddump-simpl` will end up in
35         :file:`{module}.dump-simpl`.
36
37     .. ghc-flag:: -ddump-parsed
38
39         Dump parser output
40
41     .. ghc-flag:: -ddump-parsed-ast
42
43         Dump parser output as a syntax tree
44
45     .. ghc-flag:: -ddump-rn
46
47         Dump renamer output
48
49     .. ghc-flag:: -ddump-rn-ast
50
51         Dump renamer output as a syntax tree
52
53     .. ghc-flag:: -ddump-tc
54
55         Dump typechecker output
56
57     .. ghc-flag:: -ddump-tc-ast
58
59         Dump typechecker output as a syntax tree
60
61     .. ghc-flag:: -ddump-splices
62
63         Dump Template Haskell expressions that we splice in, and what
64         Haskell code the expression evaluates to.
65
66     .. ghc-flag:: -dth-dec-file=⟨file⟩
67
68         Dump expansions of all top-level Template Haskell splices into ⟨file⟩.
69
70     .. ghc-flag:: -ddump-types
71
72         Dump a type signature for each value defined at the top level of
73         the module. The list is sorted alphabetically. Using
74         :ghc-flag:`-dppr-debug` dumps a type signature for all the imported and
75         system-defined things as well; useful for debugging the
76         compiler.
77
78     .. ghc-flag:: -ddump-deriv
79
80         Dump derived instances
81
82     .. ghc-flag:: -ddump-ds
83
84         Dump desugarer output
85
86     .. ghc-flag:: -ddump-spec
87
88         Dump output of specialisation pass
89
90     .. ghc-flag:: -ddump-rules
91
92         Dumps all rewrite rules specified in this module; see
93         :ref:`controlling-rules`.
94
95     .. ghc-flag:: -ddump-rule-firings
96
97         Dumps the names of all rules that fired in this module
98
99     .. ghc-flag:: -ddump-rule-rewrites
100
101         Dumps detailed information about all rules that fired in this
102         module
103
104     .. ghc-flag:: -ddump-vect
105
106         Dumps the output of the vectoriser.
107
108     .. ghc-flag:: -ddump-simpl
109
110         Dump simplifier output (Core-to-Core passes)
111
112     .. ghc-flag:: -ddump-inlinings
113
114         Dumps inlining info from the simplifier. Note that if used in conjunction with
115         :ghc-flag:`-dverbose-core2core` the compiler will also dump the inlinings that
116         it considers but passes up, along with its rationale.
117
118     .. ghc-flag:: -ddump-stranal
119
120         Dump strictness analyser output
121
122     .. ghc-flag:: -ddump-str-signatures
123
124         Dump strictness signatures
125
126     .. ghc-flag:: -ddump-cse
127
128         Dump common subexpression elimination (CSE) pass output
129
130     .. ghc-flag:: -ddump-worker-wrapper
131
132         Dump worker/wrapper split output
133
134     .. ghc-flag:: -ddump-occur-anal
135
136         Dump "occurrence analysis" output
137
138     .. ghc-flag:: -ddump-prep
139
140         Dump output of Core preparation pass
141
142     .. ghc-flag:: -ddump-stg
143
144         Dump output of STG-to-STG passes
145
146     .. ghc-flag:: -ddump-cmm
147
148         Dump the result of the C-- pipeline processing
149
150     .. ghc-flag:: -ddump-cmm-from-stg
151
152         Dump the result of STG-to-C-- conversion
153
154     .. ghc-flag:: -ddump-cmm-verbose
155
156         Dump output from all C-- pipeline stages. In case of
157         ``.cmm`` compilation this also dumps the result of
158         file parsing.
159
160     .. ghc-flag:: -ddump-opt-cmm
161
162         Dump the results of C-- to C-- optimising passes.
163
164     .. ghc-flag:: -ddump-asm
165
166         Dump assembly language produced by the :ref:`native code
167         generator <native-code-gen>`
168
169     .. ghc-flag:: -ddump-llvm
170
171         :implies: :ghc-flag:`-fllvm`
172
173         LLVM code from the :ref:`LLVM code generator <llvm-code-gen>`
174
175     .. ghc-flag:: -ddump-bcos
176
177         Dump byte-code compiler output
178
179     .. ghc-flag:: -ddump-foreign
180
181         dump foreign export stubs
182
183     .. ghc-flag:: -ddump-json
184
185          Dump error messages as JSON documents. This is intended to be consumed
186          by external tooling. A good way to use it is in conjunction with
187          :ghc-flag:`-ddump-to-file`.
188
189 .. ghc-flag:: -ddump-simpl-iterations
190
191     Show the output of each *iteration* of the simplifier (each run of
192     the simplifier has a maximum number of iterations, normally 4). This
193     outputs even more information than ``-ddump-simpl-phases``.
194
195 .. ghc-flag:: -ddump-simpl-stats
196
197     Dump statistics about how many of each kind of transformation too
198     place. If you add ``-dppr-debug`` you get more detailed information.
199
200 .. ghc-flag:: -ddump-if-trace
201
202     Make the interface loader be *real* chatty about what it is up to.
203
204 .. ghc-flag:: -ddump-tc-trace
205
206     Make the type checker be *real* chatty about what it is up to.
207
208 .. ghc-flag:: -ddump-vt-trace
209
210     Make the vectoriser be *real* chatty about what it is up to.
211
212 .. ghc-flag:: -ddump-rn-trace
213
214     Make the renamer be *real* chatty about what it is up to.
215
216 .. ghc-flag:: -ddump-ec-trace
217
218     Make the pattern match exhaustiveness checker be *real* chatty about
219     what it is up to.
220
221 .. ghc-flag:: -ddump-rn-stats
222
223     Print out summary of what kind of information the renamer had to
224     bring in.
225
226 .. ghc-flag:: -dverbose-core2core
227               -dverbose-stg2stg
228
229     Show the output of the intermediate Core-to-Core and STG-to-STG
230     passes, respectively. (*lots* of output!) So: when we're really
231     desperate:
232
233     .. code-block:: sh
234
235         % ghc -noC -O -ddump-simpl -dverbose-core2core -dcore-lint Foo.hs
236
237 .. ghc-flag:: -dshow-passes
238
239     Print out each pass name, its runtime and heap allocations as it happens.
240     Note that this may come at a slight performance cost as the compiler will
241     be a bit more eager in forcing pass results to more accurately account for
242     their costs.
243
244     Two types of messages are produced: Those beginning with ``***`` are
245     denote the beginning of a compilation phase whereas those starting with
246     ``!!!`` mark the end of a pass and are accompanied by allocation and
247     runtime statistics.
248
249 .. ghc-flag:: -ddump-core-stats
250
251     Print a one-line summary of the size of the Core program at the end
252     of the optimisation pipeline.
253
254 .. ghc-flag:: -dfaststring-stats
255
256     Show statistics on the usage of fast strings by the compiler.
257
258 .. ghc-flag:: -dppr-debug
259
260     Debugging output is in one of several "styles." Take the printing of
261     types, for example. In the "user" style (the default), the
262     compiler's internal ideas about types are presented in Haskell
263     source-level syntax, insofar as possible. In the "debug" style
264     (which is the default for debugging output), the types are printed
265     in with explicit foralls, and variables have their unique-id
266     attached (so you can check for things that look the same but
267     aren't). This flag makes debugging output appear in the more verbose
268     debug style.
269
270
271 .. _formatting dumps:
272
273 Formatting dumps
274 ----------------
275
276 .. index::
277    single: formatting dumps
278
279 .. ghc-flag:: -dppr-user-length
280
281     In error messages, expressions are printed to a certain "depth",
282     with subexpressions beyond the depth replaced by ellipses. This flag
283     sets the depth. Its default value is 5.
284
285 .. ghc-flag:: -dppr-cols=⟨n⟩
286
287     Set the width of debugging output. Use this if your code is wrapping
288     too much. For example: ``-dppr-cols=200``.
289
290 .. ghc-flag:: -dppr-case-as-let
291
292     Print single alternative case expressions as though they were strict
293     let expressions. This is helpful when your code does a lot of
294     unboxing.
295
296 .. ghc-flag:: -dno-debug-output
297
298     Suppress any unsolicited debugging output. When GHC has been built
299     with the ``DEBUG`` option it occasionally emits debug output of
300     interest to developers. The extra output can confuse the testing
301     framework and cause bogus test failures, so this flag is provided to
302     turn it off.
303
304 .. _suppression:
305
306 Suppressing unwanted information
307 --------------------------------
308
309 .. index::
310    single: suppression; of unwanted dump output
311
312 Core dumps contain a large amount of information. Depending on what you
313 are doing, not all of it will be useful. Use these flags to suppress the
314 parts that you are not interested in.
315
316 .. ghc-flag:: -dsuppress-all
317
318     Suppress everything that can be suppressed, except for unique ids as
319     this often makes the printout ambiguous. If you just want to see the
320     overall structure of the code, then start here.
321
322 .. ghc-flag:: -dsuppress-ticks
323
324     Suppress "ticks" in the pretty-printer output.
325
326 .. ghc-flag:: -dsuppress-uniques
327
328     Suppress the printing of uniques. This may make the printout
329     ambiguous (e.g. unclear where an occurrence of 'x' is bound), but it
330     makes the output of two compiler runs have many fewer gratuitous
331     differences, so you can realistically apply ``diff``. Once ``diff``
332     has shown you where to look, you can try again without
333     :ghc-flag:`-dsuppress-uniques`
334
335 .. ghc-flag:: -dsuppress-idinfo
336
337     Suppress extended information about identifiers where they are
338     bound. This includes strictness information and inliner templates.
339     Using this flag can cut the size of the core dump in half, due to
340     the lack of inliner templates
341
342 .. ghc-flag:: -dsuppress-unfoldings
343
344     Suppress the printing of the stable unfolding of a variable at its
345     binding site.
346
347 .. ghc-flag:: -dsuppress-module-prefixes
348
349     Suppress the printing of module qualification prefixes. This is the
350     ``Data.List`` in ``Data.List.length``.
351
352 .. ghc-flag:: -dsuppress-type-signatures
353
354     Suppress the printing of type signatures.
355
356 .. ghc-flag:: -dsuppress-type-applications
357
358     Suppress the printing of type applications.
359
360 .. ghc-flag:: -dsuppress-coercions
361
362     Suppress the printing of type coercions.
363
364 .. _checking-consistency:
365
366 Checking for consistency
367 ------------------------
368
369 .. index::
370    single: consistency checks
371    single: lint
372
373 .. ghc-flag:: -dcore-lint
374
375     Turn on heavyweight intra-pass sanity-checking within GHC, at Core
376     level. (It checks GHC's sanity, not yours.)
377
378 .. ghc-flag:: -dstg-lint
379
380     Ditto for STG level. (note: currently doesn't work).
381
382 .. ghc-flag:: -dcmm-lint
383
384     Ditto for C-- level.
385
386 .. ghc-flag:: -fllvm-fill-undef-with-garbage
387
388     Instructs the LLVM code generator to fill dead STG registers with garbage
389     instead of ``undef`` in calls. This makes it easier to catch subtle
390     code generator and runtime system bugs (e.g. see :ghc-ticket:`11487`).
391
392 .. ghc-flag:: -fcatch-bottoms
393
394     Instructs the simplifier to emit ``error`` expressions in the continuation
395     of empty case analyses (which should bottom and consequently not return).
396     This is helpful when debugging demand analysis bugs which can sometimes
397     manifest as segmentation faults.
398
399 .. _checking-determinism:
400
401 Checking for determinism
402 ------------------------
403
404 .. index::
405    single: deterministic builds
406
407 .. ghc-flag:: -dinitial-unique=⟨s⟩
408
409     Start ``UniqSupply`` allocation from ⟨s⟩.
410
411 .. ghc-flag:: -dunique-increment=⟨i⟩
412
413     Set the increment for the generated ``Unique``'s to ⟨i⟩.
414
415     This is useful in combination with :ghc-flag:`-dinitial-unique=⟨s⟩` to test
416     if the generated files depend on the order of ``Unique``'s.
417
418     Some interesting values:
419
420     * ``-dinitial-unique=0 -dunique-increment=1`` - current sequential
421       ``UniqSupply``
422     * ``-dinitial-unique=16777215 -dunique-increment=-1`` - ``UniqSupply`` that
423       generates in decreasing order
424     * ``-dinitial-unique=1 -dunique-increment=PRIME`` - where PRIME big enough
425       to overflow often - nonsequential order