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