users-guide: Document -dppr-ticks
[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 .. ghc-flag:: -dppr-ticks
255
256     Includes "ticks" in the pretty-printer output.
257
258
259 .. _formatting dumps:
260
261 Formatting dumps
262 ----------------
263
264 .. index::
265    single: formatting dumps
266
267 .. ghc-flag:: -dppr-user-length
268
269     In error messages, expressions are printed to a certain "depth",
270     with subexpressions beyond the depth replaced by ellipses. This flag
271     sets the depth. Its default value is 5.
272
273 .. ghc-flag:: -dppr-cols=N
274
275     Set the width of debugging output. Use this if your code is wrapping
276     too much. For example: ``-dppr-cols=200``.
277
278 .. ghc-flag:: -dppr-case-as-let
279
280     Print single alternative case expressions as though they were strict
281     let expressions. This is helpful when your code does a lot of
282     unboxing.
283
284 .. ghc-flag:: -dno-debug-output
285
286     Suppress any unsolicited debugging output. When GHC has been built
287     with the ``DEBUG`` option it occasionally emits debug output of
288     interest to developers. The extra output can confuse the testing
289     framework and cause bogus test failures, so this flag is provided to
290     turn it off.
291
292 .. _suppression:
293
294 Suppressing unwanted information
295 --------------------------------
296
297 .. index::
298    single: suppression; of unwanted dump output
299
300 Core dumps contain a large amount of information. Depending on what you
301 are doing, not all of it will be useful. Use these flags to suppress the
302 parts that you are not interested in.
303
304 .. ghc-flag:: -dsuppress-all
305
306     Suppress everything that can be suppressed, except for unique ids as
307     this often makes the printout ambiguous. If you just want to see the
308     overall structure of the code, then start here.
309
310 .. ghc-flag:: -dsuppress-uniques
311
312     Suppress the printing of uniques. This may make the printout
313     ambiguous (e.g. unclear where an occurrence of 'x' is bound), but it
314     makes the output of two compiler runs have many fewer gratuitous
315     differences, so you can realistically apply ``diff``. Once ``diff``
316     has shown you where to look, you can try again without
317     :ghc-flag:`-dsuppress-uniques`
318
319 .. ghc-flag:: -dsuppress-idinfo
320
321     Suppress extended information about identifiers where they are
322     bound. This includes strictness information and inliner templates.
323     Using this flag can cut the size of the core dump in half, due to
324     the lack of inliner templates
325
326 .. ghc-flag:: -dsuppress-unfoldings
327
328     Suppress the printing of the stable unfolding of a variable at its
329     binding site.
330
331 .. ghc-flag:: -dsuppress-module-prefixes
332
333     Suppress the printing of module qualification prefixes. This is the
334     ``Data.List`` in ``Data.List.length``.
335
336 .. ghc-flag:: -dsuppress-type-signatures
337
338     Suppress the printing of type signatures.
339
340 .. ghc-flag:: -dsuppress-type-applications
341
342     Suppress the printing of type applications.
343
344 .. ghc-flag:: -dsuppress-coercions
345
346     Suppress the printing of type coercions.
347
348 .. _checking-consistency:
349
350 Checking for consistency
351 ------------------------
352
353 .. index::
354    single: consistency checks
355    single: lint
356
357 .. ghc-flag:: -dcore-lint
358
359     Turn on heavyweight intra-pass sanity-checking within GHC, at Core
360     level. (It checks GHC's sanity, not yours.)
361
362 .. ghc-flag:: -dstg-lint
363
364     Ditto for STG level. (note: currently doesn't work).
365
366 .. ghc-flag:: -dcmm-lint
367
368     Ditto for C-- level.
369
370 .. ghc-flag:: -fllvm-fill-undef-with-garbage
371
372     Instructs the LLVM code generator to fill dead STG registers with garbage
373     instead of ``undef`` in calls. This makes it easier to catch subtle
374     code generator and runtime system bugs (e.g. see :ghc-ticket:`11487`).
375
376 .. _checking-determinism:
377
378 Checking for determinism
379 ------------------------
380
381 .. index::
382    single: deterministic builds
383
384 .. ghc-flag:: -dinitial-unique=⟨s⟩
385
386     Start ``UniqSupply`` allocation from ⟨s⟩.
387
388 .. ghc-flag:: -dunique-increment=⟨i⟩
389
390     Set the increment for the generated ``Unique``'s to ⟨i⟩.
391
392     This is useful in combination with :ghc-flag:`-dinitial-unique` to test if the
393     generated files depend on the order of ``Unique``'s.
394
395     Some interesting values:
396
397     * ``-dinitial-unique=0 -dunique-increment=1`` - current sequential
398       ``UniqSupply``
399     * ``-dinitial-unique=16777215 -dunique-increment=-1`` - ``UniqSupply`` that
400       generates in decreasing order
401     * ``-dinitial-unique=1 -dunique-increment=PRIME`` - where PRIME big enough
402       to overflow often - nonsequential order