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