Improve documentation of INLINE pragmas
[ghc.git] / docs / users_guide / debugging.xml
1 <?xml version="1.0" encoding="iso-8859-1"?>
2 <sect1 id="options-debugging">
3 <title>Debugging the compiler</title>
4
5 <indexterm><primary>debugging options (for GHC)</primary></indexterm>
6
7 <para>HACKER TERRITORY. HACKER TERRITORY. (You were warned.)</para>
8
9 <sect2 id="dumping-output">
10 <title>Dumping out compiler intermediate structures</title>
11
12 <indexterm><primary>dumping GHC intermediates</primary></indexterm>
13 <indexterm><primary>intermediate passes, output</primary></indexterm>
14
15 <variablelist>
16 <varlistentry>
17 <term>
18 <option>-ddump-</option><replaceable>pass</replaceable>
19 <indexterm><primary><option>-ddump</option> options</primary></indexterm>
20 </term>
21 <listitem>
22 <para>Make a debugging dump after pass
23 <literal>&lt;pass&gt;</literal> (may be common enough to need
24 a short form&hellip;). You can get all of these at once
25 (<emphasis>lots</emphasis> of output) by using
26 <option>-v5</option>, or most of them with
27 <option>-v4</option>. Some of the most useful ones
28 are:</para>
29
30 <variablelist>
31 <varlistentry>
32 <term>
33 <option>-ddump-parsed</option>:
34 <indexterm><primary><option>-ddump-parsed</option></primary></indexterm>
35 </term>
36 <listitem>
37 <para>parser output</para>
38 </listitem>
39 </varlistentry>
40
41 <varlistentry>
42 <term>
43 <option>-ddump-rn</option>:
44 <indexterm><primary><option>-ddump-rn</option></primary></indexterm>
45 </term>
46 <listitem>
47 <para>renamer output</para>
48 </listitem>
49 </varlistentry>
50
51 <varlistentry>
52 <term>
53 <option>-ddump-tc</option>:
54 <indexterm><primary><option>-ddump-tc</option></primary></indexterm>
55 </term>
56 <listitem>
57 <para>typechecker output</para>
58 </listitem>
59 </varlistentry>
60
61 <varlistentry>
62 <term>
63 <option>-ddump-types</option>:
64 <indexterm><primary><option>-ddump-types</option></primary></indexterm>
65 </term>
66 <listitem>
67 <para>Dump a type signature for each value defined at
68 the top level of the module. The list is sorted
69 alphabetically. Using <option>-dppr-debug</option>
70 dumps a type signature for all the imported and
71 system-defined things as well; useful for debugging the
72 compiler.</para>
73 </listitem>
74 </varlistentry>
75
76 <varlistentry>
77 <term>
78 <option>-ddump-deriv</option>:
79 <indexterm><primary><option>-ddump-deriv</option></primary></indexterm>
80 </term>
81 <listitem>
82 <para>derived instances</para>
83 </listitem>
84 </varlistentry>
85
86 <varlistentry>
87 <term>
88 <option>-ddump-ds</option>:
89 <indexterm><primary><option>-ddump-ds</option></primary></indexterm>
90 </term>
91 <listitem>
92 <para>desugarer output</para>
93 </listitem>
94 </varlistentry>
95
96 <varlistentry>
97 <term>
98 <option>-ddump-spec</option>:
99 <indexterm><primary><option>-ddump-spec</option></primary></indexterm>
100 </term>
101 <listitem>
102 <para>output of specialisation pass</para>
103 </listitem>
104 </varlistentry>
105
106 <varlistentry>
107 <term>
108 <option>-ddump-rules</option>:
109 <indexterm><primary><option>-ddump-rules</option></primary></indexterm>
110 </term>
111 <listitem>
112 <para>dumps all rewrite rules (including those generated
113 by the specialisation pass)</para>
114 </listitem>
115 </varlistentry>
116
117 <varlistentry>
118 <term>
119 <option>-ddump-simpl</option>:
120 <indexterm><primary><option>-ddump-simpl</option></primary></indexterm>
121 </term>
122 <listitem>
123 <para>simplifier output (Core-to-Core passes)</para>
124 </listitem>
125 </varlistentry>
126
127 <varlistentry>
128 <term>
129 <option>-ddump-inlinings</option>:
130 <indexterm><primary><option>-ddump-inlinings</option></primary></indexterm>
131 </term>
132 <listitem>
133 <para>inlining info from the simplifier</para>
134 </listitem>
135 </varlistentry>
136
137 <varlistentry>
138 <term>
139 <option>-ddump-usagesp</option>:
140 <indexterm><primary><option>-ddump-usagesp</option></primary></indexterm>
141 </term>
142 <listitem>
143 <para>UsageSP inference pre-inf and output</para>
144 </listitem>
145 </varlistentry>
146
147 <varlistentry>
148 <term>
149 <option>-ddump-cpranal</option>:
150 <indexterm><primary><option>-ddump-cpranal</option></primary></indexterm>
151 </term>
152 <listitem>
153 <para>CPR analyser output</para>
154 </listitem>
155 </varlistentry>
156
157 <varlistentry>
158 <term>
159 <option>-ddump-stranal</option>:
160 <indexterm><primary><option>-ddump-stranal</option></primary></indexterm>
161 </term>
162 <listitem>
163 <para>strictness analyser output</para>
164 </listitem>
165 </varlistentry>
166
167 <varlistentry>
168 <term>
169 <option>-ddump-cse</option>:
170 <indexterm><primary><option>-ddump-cse</option></primary></indexterm>
171 </term>
172 <listitem>
173 <para>CSE pass output</para>
174 </listitem>
175 </varlistentry>
176
177 <varlistentry>
178 <term>
179 <option>-ddump-workwrap</option>:
180 <indexterm><primary><option>-ddump-workwrap</option></primary></indexterm>
181 </term>
182 <listitem>
183 <para>worker/wrapper split output</para>
184 </listitem>
185 </varlistentry>
186
187 <varlistentry>
188 <term>
189 <option>-ddump-occur-anal</option>:
190 <indexterm><primary><option>-ddump-occur-anal</option></primary></indexterm>
191 </term>
192 <listitem>
193 <para>`occurrence analysis' output</para>
194 </listitem>
195 </varlistentry>
196
197 <varlistentry>
198 <term>
199 <option>-ddump-sat</option>:
200 <indexterm><primary><option>-ddump-sat</option></primary></indexterm>
201 </term>
202 <listitem>
203 <para>output of &ldquo;saturate&rdquo; pass</para>
204 </listitem>
205 </varlistentry>
206
207 <varlistentry>
208 <term>
209 <option>-ddump-stg</option>:
210 <indexterm><primary><option>-ddump-stg</option></primary></indexterm>
211 </term>
212 <listitem>
213 <para>output of STG-to-STG passes</para>
214 </listitem>
215 </varlistentry>
216
217 <varlistentry>
218 <term>
219 <option>-ddump-absC</option>:
220 <indexterm><primary><option>-ddump-absC</option></primary></indexterm>
221 </term>
222 <listitem>
223 <para><emphasis>un</emphasis>flattened Abstract&nbsp;C</para>
224 </listitem>
225 </varlistentry>
226
227 <varlistentry>
228 <term>
229 <option>-ddump-flatC</option>:
230 <indexterm><primary><option>-ddump-flatC</option></primary></indexterm>
231 </term>
232 <listitem>
233 <para><emphasis>flattened</emphasis> Abstract&nbsp;C</para>
234 </listitem>
235 </varlistentry>
236
237 <varlistentry>
238 <term>
239 <option>-ddump-realC</option>:
240 <indexterm><primary><option>-ddump-realC</option></primary></indexterm>
241 </term>
242 <listitem>
243 <para>same as what goes to the C compiler</para>
244 </listitem>
245 </varlistentry>
246
247 <varlistentry>
248 <term>
249 <option>-ddump-stix</option>:
250 <indexterm><primary><option>-ddump-stix</option></primary></indexterm>
251 </term>
252 <listitem>
253 <para>native-code generator intermediate form</para>
254 </listitem>
255 </varlistentry>
256
257 <varlistentry>
258 <term>
259 <option>-ddump-asm</option>:
260 <indexterm><primary><option>-ddump-asm</option></primary></indexterm>
261 </term>
262 <listitem>
263 <para>assembly language from the native-code generator</para>
264 </listitem>
265 </varlistentry>
266
267 <varlistentry>
268 <term>
269 <option>-ddump-bcos</option>:
270 <indexterm><primary><option>-ddump-bcos</option></primary></indexterm>
271 </term>
272 <listitem>
273 <para>byte code compiler output</para>
274 </listitem>
275 </varlistentry>
276
277 <varlistentry>
278 <term>
279 <option>-ddump-foreign</option>:
280 <indexterm><primary><option>-ddump-foreign</option></primary></indexterm>
281 </term>
282 <listitem>
283 <para>dump foreign export stubs</para>
284 </listitem>
285 </varlistentry>
286 </variablelist>
287 </listitem>
288 </varlistentry>
289
290 <varlistentry>
291 <term>
292 <option>-dverbose-core2core</option>
293 <indexterm><primary><option>-dverbose-core2core</option></primary></indexterm>
294 </term>
295 <term>
296 <option>-dverbose-stg2stg</option>
297 <indexterm><primary><option>-dverbose-stg2stg</option></primary></indexterm>
298 </term>
299 <listitem>
300 <para>Show the output of the intermediate Core-to-Core and
301 STG-to-STG passes, respectively. (<emphasis>Lots</emphasis>
302 of output!) So: when we're really desperate:</para>
303
304 <screen>
305 % ghc -noC -O -ddump-simpl -dverbose-simpl -dcore-lint Foo.hs
306 </screen>
307
308 </listitem>
309 </varlistentry>
310
311 <varlistentry>
312 <term>
313 <option>-ddump-simpl-iterations</option>:
314 <indexterm><primary><option>-ddump-simpl-iterations</option></primary></indexterm>
315 </term>
316 <listitem>
317 <para>Show the output of each <emphasis>iteration</emphasis>
318 of the simplifier (each run of the simplifier has a maximum
319 number of iterations, normally 4). Used when even
320 <option>-dverbose-simpl</option> doesn't cut it.</para>
321 </listitem>
322 </varlistentry>
323
324 <varlistentry>
325 <term>
326 <option>-dppr-debug</option>
327 <indexterm><primary><option>-dppr-debug</option></primary></indexterm>
328 </term>
329 <listitem>
330 <para>Debugging output is in one of several
331 &ldquo;styles.&rdquo; Take the printing of types, for
332 example. In the &ldquo;user&rdquo; style (the default), the
333 compiler's internal ideas about types are presented in
334 Haskell source-level syntax, insofar as possible. In the
335 &ldquo;debug&rdquo; style (which is the default for
336 debugging output), the types are printed in with explicit
337 foralls, and variables have their unique-id attached (so you
338 can check for things that look the same but aren't). This
339 flag makes debugging output appear in the more verbose debug
340 style.</para>
341 </listitem>
342 </varlistentry>
343
344 <varlistentry>
345 <term>
346 <option>-dppr-user-length</option>
347 <indexterm><primary><option>-dppr-user-length</option></primary></indexterm>
348 </term>
349 <listitem>
350 <para>In error messages, expressions are printed to a
351 certain &ldquo;depth&rdquo;, with subexpressions beyond the
352 depth replaced by ellipses. This flag sets the
353 depth.</para>
354 </listitem>
355 </varlistentry>
356
357 <varlistentry>
358 <term>
359 <option>-ddump-simpl-stats</option>
360 <indexterm><primary><option>-ddump-simpl-stats option</option></primary></indexterm>
361 </term>
362 <listitem>
363 <para>Dump statistics about how many of each kind of
364 transformation too place. If you add
365 <option>-dppr-debug</option> you get more detailed
366 information.</para>
367 </listitem>
368 </varlistentry>
369
370 <varlistentry>
371 <term>
372 <option>-ddump-rn-trace</option>
373 <indexterm><primary><option>-ddump-rn-trace</option></primary></indexterm>
374 </term>
375 <listitem>
376 <para>Make the renamer be *real* chatty about what it is
377 upto.</para>
378 </listitem>
379 </varlistentry>
380
381 <varlistentry>
382 <term>
383 <option>-ddump-rn-stats</option>
384 <indexterm><primary><option>-dshow-rn-stats</option></primary></indexterm>
385 </term>
386 <listitem>
387 <para>Print out summary of what kind of information the renamer
388 had to bring in.</para>
389 </listitem>
390 </varlistentry>
391
392 <varlistentry>
393 <term>
394 <option>-dshow-unused-imports</option>
395 <indexterm><primary><option>-dshow-unused-imports</option></primary></indexterm>
396 </term>
397 <listitem>
398 <para>Have the renamer report what imports does not
399 contribute.</para>
400 </listitem>
401 </varlistentry>
402 </variablelist>
403 </sect2>
404
405 <sect2 id="checking-consistency">
406 <title>Checking for consistency</title>
407
408 <indexterm><primary>consistency checks</primary></indexterm>
409 <indexterm><primary>lint</primary></indexterm>
410
411 <variablelist>
412
413 <varlistentry>
414 <term>
415 <option>-dcore-lint</option>
416 <indexterm><primary><option>-dcore-lint</option></primary></indexterm>
417 </term>
418 <listitem>
419 <para>Turn on heavyweight intra-pass sanity-checking within
420 GHC, at Core level. (It checks GHC's sanity, not yours.)</para>
421 </listitem>
422 </varlistentry>
423
424 <varlistentry>
425 <term>
426 <option>-dstg-lint</option>:
427 <indexterm><primary><option>-dstg-lint</option></primary></indexterm>
428 </term>
429 <listitem>
430 <para>Ditto for STG level. (NOTE: currently doesn't work).</para>
431 </listitem>
432 </varlistentry>
433
434 <varlistentry>
435 <term>
436 <option>-dusagesp-lint</option>:
437 <indexterm><primary><option>-dstg-lint</option></primary></indexterm>
438 </term>
439 <listitem>
440 <para>Turn on checks around UsageSP inference
441 (<option>-fusagesp</option>). This verifies various simple
442 properties of the results of the inference, and also warns
443 if any identifier with a used-once annotation before the
444 inference has a used-many annotation afterwards; this could
445 indicate a non-worksafe transformation is being
446 applied.</para>
447 </listitem>
448 </varlistentry>
449 </variablelist>
450 </sect2>
451
452 <sect2>
453 <title>How to read Core syntax (from some <option>-ddump</option>
454 flags)</title>
455
456 <indexterm><primary>reading Core syntax</primary></indexterm>
457 <indexterm><primary>Core syntax, how to read</primary></indexterm>
458
459 <para>Let's do this by commenting an example. It's from doing
460 <option>-ddump-ds</option> on this code:
461
462 <programlisting>
463 skip2 m = m : skip2 (m+2)
464 </programlisting>
465
466 Before we jump in, a word about names of things. Within GHC,
467 variables, type constructors, etc., are identified by their
468 &ldquo;Uniques.&rdquo; These are of the form `letter' plus
469 `number' (both loosely interpreted). The `letter' gives some idea
470 of where the Unique came from; e.g., <literal>&lowbar;</literal>
471 means &ldquo;built-in type variable&rdquo;; <literal>t</literal>
472 means &ldquo;from the typechecker&rdquo;; <literal>s</literal>
473 means &ldquo;from the simplifier&rdquo;; and so on. The `number'
474 is printed fairly compactly in a `base-62' format, which everyone
475 hates except me (WDP).</para>
476
477 <para>Remember, everything has a &ldquo;Unique&rdquo; and it is
478 usually printed out when debugging, in some form or another. So
479 here we go&hellip;</para>
480
481 <programlisting>
482 Desugared:
483 Main.skip2{-r1L6-} :: _forall_ a$_4 =&#62;{{Num a$_4}} -&#62; a$_4 -&#62; [a$_4]
484
485 --# `r1L6' is the Unique for Main.skip2;
486 --# `_4' is the Unique for the type-variable (template) `a'
487 --# `{{Num a$_4}}' is a dictionary argument
488
489 _NI_
490
491 --# `_NI_' means "no (pragmatic) information" yet; it will later
492 --# evolve into the GHC_PRAGMA info that goes into interface files.
493
494 Main.skip2{-r1L6-} =
495 /\ _4 -&#62; \ d.Num.t4Gt -&#62;
496 let {
497 {- CoRec -}
498 +.t4Hg :: _4 -&#62; _4 -&#62; _4
499 _NI_
500 +.t4Hg = (+{-r3JH-} _4) d.Num.t4Gt
501
502 fromInt.t4GS :: Int{-2i-} -&#62; _4
503 _NI_
504 fromInt.t4GS = (fromInt{-r3JX-} _4) d.Num.t4Gt
505
506 --# The `+' class method (Unique: r3JH) selects the addition code
507 --# from a `Num' dictionary (now an explicit lambda'd argument).
508 --# Because Core is 2nd-order lambda-calculus, type applications
509 --# and lambdas (/\) are explicit. So `+' is first applied to a
510 --# type (`_4'), then to a dictionary, yielding the actual addition
511 --# function that we will use subsequently...
512
513 --# We play the exact same game with the (non-standard) class method
514 --# `fromInt'. Unsurprisingly, the type `Int' is wired into the
515 --# compiler.
516
517 lit.t4Hb :: _4
518 _NI_
519 lit.t4Hb =
520 let {
521 ds.d4Qz :: Int{-2i-}
522 _NI_
523 ds.d4Qz = I#! 2#
524 } in fromInt.t4GS ds.d4Qz
525
526 --# `I# 2#' is just the literal Int `2'; it reflects the fact that
527 --# GHC defines `data Int = I# Int#', where Int# is the primitive
528 --# unboxed type. (see relevant info about unboxed types elsewhere...)
529
530 --# The `!' after `I#' indicates that this is a *saturated*
531 --# application of the `I#' data constructor (i.e., not partially
532 --# applied).
533
534 skip2.t3Ja :: _4 -&#62; [_4]
535 _NI_
536 skip2.t3Ja =
537 \ m.r1H4 -&#62;
538 let { ds.d4QQ :: [_4]
539 _NI_
540 ds.d4QQ =
541 let {
542 ds.d4QY :: _4
543 _NI_
544 ds.d4QY = +.t4Hg m.r1H4 lit.t4Hb
545 } in skip2.t3Ja ds.d4QY
546 } in
547 :! _4 m.r1H4 ds.d4QQ
548
549 {- end CoRec -}
550 } in skip2.t3Ja
551 </programlisting>
552
553 <para>(&ldquo;It's just a simple functional language&rdquo; is an
554 unregisterised trademark of Peyton Jones Enterprises, plc.)</para>
555
556 </sect2>
557
558 <sect2 id="unreg">
559 <title>Unregisterised compilation</title>
560 <indexterm><primary>unregisterised compilation</primary></indexterm>
561
562 <para>The term "unregisterised" really means "compile via vanilla
563 C", disabling some of the platform-specific tricks that GHC
564 normally uses to make programs go faster. When compiling
565 unregisterised, GHC simply generates a C file which is compiled
566 via gcc.</para>
567
568 <para>Unregisterised compilation can be useful when porting GHC to
569 a new machine, since it reduces the prerequisite tools to
570 <command>gcc</command>, <command>as</command>, and
571 <command>ld</command> and nothing more, and furthermore the amount
572 of platform-specific code that needs to be written in order to get
573 unregisterised compilation going is usually fairly small.</para>
574
575 <variablelist>
576 <varlistentry>
577 <term>
578 <option>-unreg</option>:
579 <indexterm><primary><option>-unreg</option></primary></indexterm>
580 </term>
581 <listitem>
582 <para>Compile via vanilla ANSI C only, turning off
583 platform-specific optimisations. NOTE: in order to use
584 <option>-unreg</option>, you need to have a set of libraries
585 (including the RTS) built for unregisterised compilation.
586 This amounts to building GHC with way "u" enabled.</para>
587 </listitem>
588 </varlistentry>
589 </variablelist>
590 </sect2>
591
592 </sect1>
593
594 <!-- Emacs stuff:
595 ;;; Local Variables: ***
596 ;;; mode: xml ***
597 ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter" "sect1") ***
598 ;;; End: ***
599 -->