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-splices</option>:
  64                 <indexterm><primary><option>-ddump-splices</option></primary></indexterm>
  65               </term>
  66               <listitem>
  67                 <para>Dump Template Haskell expressions that we splice in,
  68                 and what Haskell code the expression evaluates to.</para>
  69               </listitem>
  70             </varlistentry>
  71
  72             <varlistentry>
  73               <term>
  74                 <option>-ddump-types</option>:
  75                 <indexterm><primary><option>-ddump-types</option></primary></indexterm>
  76               </term>
  77               <listitem>
  78                 <para>Dump a type signature for each value defined at
  79               the top level of the module.  The list is sorted
  80               alphabetically.  Using <option>-dppr-debug</option>
  81               dumps a type signature for all the imported and
  82               system-defined things as well; useful for debugging the
  83               compiler.</para>
  84               </listitem>
  85             </varlistentry>
  86
  87             <varlistentry>
  88               <term>
  89                 <option>-ddump-deriv</option>:
  90                 <indexterm><primary><option>-ddump-deriv</option></primary></indexterm>
  91               </term>
  92               <listitem>
  93                 <para>derived instances</para>
  94               </listitem>
  95             </varlistentry>
  96
  97             <varlistentry>
  98               <term>
  99                 <option>-ddump-ds</option>:
 100                 <indexterm><primary><option>-ddump-ds</option></primary></indexterm>
 101               </term>
 102               <listitem>
 103                 <para>desugarer output</para>
 104               </listitem>
 105             </varlistentry>
 106
 107             <varlistentry>
 108               <term>
 109                 <option>-ddump-spec</option>:
 110                 <indexterm><primary><option>-ddump-spec</option></primary></indexterm>
 111               </term>
 112               <listitem>
 113                 <para>output of specialisation pass</para>
 114               </listitem>
 115             </varlistentry>
 116
 117             <varlistentry>
 118               <term>
 119                 <option>-ddump-rules</option>:
 120                 <indexterm><primary><option>-ddump-rules</option></primary></indexterm>
 121               </term>
 122               <listitem>
 123                 <para>dumps all rewrite rules (including those generated
 124               by the specialisation pass)</para>
 125               </listitem>
 126             </varlistentry>
 127
 128             <varlistentry>
 129               <term>
 130                 <option>-ddump-simpl</option>:
 131                 <indexterm><primary><option>-ddump-simpl</option></primary></indexterm>
 132               </term>
 133               <listitem>
 134                 <para>simplifier output (Core-to-Core passes)</para>
 135               </listitem>
 136             </varlistentry>
 137
 138             <varlistentry>
 139               <term>
 140                 <option>-ddump-inlinings</option>:
 141                 <indexterm><primary><option>-ddump-inlinings</option></primary></indexterm>
 142               </term>
 143               <listitem>
 144                 <para>inlining info from the simplifier</para>
 145               </listitem>
 146             </varlistentry>
 147
 148             <varlistentry>
 149               <term>
 150                 <option>-ddump-cpranal</option>:
 151                 <indexterm><primary><option>-ddump-cpranal</option></primary></indexterm>
 152               </term>
 153               <listitem>
 154                 <para>CPR analyser output</para>
 155               </listitem>
 156             </varlistentry>
 157
 158             <varlistentry>
 159               <term>
 160                 <option>-ddump-stranal</option>:
 161                 <indexterm><primary><option>-ddump-stranal</option></primary></indexterm>
 162               </term>
 163               <listitem>
 164                 <para>strictness analyser output</para>
 165               </listitem>
 166             </varlistentry>
 167
 168             <varlistentry>
 169               <term>
 170                 <option>-ddump-cse</option>:
 171                 <indexterm><primary><option>-ddump-cse</option></primary></indexterm>
 172               </term>
 173               <listitem>
 174                 <para>CSE pass output</para>
 175               </listitem>
 176             </varlistentry>
 177
 178             <varlistentry>
 179               <term>
 180                 <option>-ddump-workwrap</option>:
 181                 <indexterm><primary><option>-ddump-workwrap</option></primary></indexterm>
 182               </term>
 183               <listitem>
 184                 <para>worker/wrapper split output</para>
 185               </listitem>
 186             </varlistentry>
 187
 188             <varlistentry>
 189               <term>
 190                 <option>-ddump-occur-anal</option>:
 191                 <indexterm><primary><option>-ddump-occur-anal</option></primary></indexterm>
 192               </term>
 193               <listitem>
 194                 <para>`occurrence analysis' output</para>
 195               </listitem>
 196             </varlistentry>
 197
 198             <varlistentry>
 199               <term>
 200                 <option>-ddump-prep</option>:
 201                 <indexterm><primary><option>-ddump-prep</option></primary></indexterm>
 202               </term>
 203               <listitem>
 204                 <para>output of core preparation pass</para>
 205               </listitem>
 206             </varlistentry>
 207
 208             <varlistentry>
 209               <term>
 210                 <option>-ddump-stg</option>:
 211                 <indexterm><primary><option>-ddump-stg</option></primary></indexterm>
 212               </term>
 213               <listitem>
 214                 <para>output of STG-to-STG passes</para>
 215               </listitem>
 216             </varlistentry>
 217
 218             <varlistentry>
 219               <term>
 220                 <option>-ddump-flatC</option>:
 221                 <indexterm><primary><option>-ddump-flatC</option></primary></indexterm>
 222               </term>
 223               <listitem>
 224                 <para><emphasis>flattened</emphasis> Abstract&nbsp;C</para>
 225               </listitem>
 226             </varlistentry>
 227
 228             <varlistentry>
 229               <term>
 230                 <option>-ddump-cmm</option>:
 231                 <indexterm><primary><option>-ddump-cmm</option></primary></indexterm>
 232               </term>
 233               <listitem>
 234                 <para>Print the C-- code out.</para>
 235               </listitem>
 236             </varlistentry>
 237
 238             <varlistentry>
 239               <term>
 240                 <option>-ddump-opt-cmm</option>:
 241                 <indexterm><primary><option>-ddump-opt-cmm</option></primary></indexterm>
 242               </term>
 243               <listitem>
 244                 <para>Dump the results of C-- to C-- optimising passes.</para>
 245               </listitem>
 246             </varlistentry>
 247
 248             <varlistentry>
 249               <term>
 250                 <option>-ddump-asm</option>:
 251                 <indexterm><primary><option>-ddump-asm</option></primary></indexterm>
 252               </term>
 253               <listitem>
 254                 <para>assembly language from the native-code generator</para>
 255               </listitem>
 256             </varlistentry>
 257
 258             <varlistentry>
 259               <term>
 260                 <option>-ddump-bcos</option>:
 261                 <indexterm><primary><option>-ddump-bcos</option></primary></indexterm>
 262               </term>
 263               <listitem>
 264                 <para>byte code compiler output</para>
 265               </listitem>
 266             </varlistentry>
 267
 268             <varlistentry>
 269               <term>
 270                 <option>-ddump-foreign</option>:
 271                 <indexterm><primary><option>-ddump-foreign</option></primary></indexterm>
 272               </term>
 273               <listitem>
 274                 <para>dump foreign export stubs</para>
 275               </listitem>
 276             </varlistentry>
 277           </variablelist>
 278         </listitem>
 279       </varlistentry>
 280
 281       <varlistentry>
 282         <term>
 283           <option>-ddump-simpl-phases</option>:
 284           <indexterm><primary><option>-ddump-simpl-phases</option></primary></indexterm>
 285         </term>
 286         <listitem>
 287           <para>Show the output of each run of the simplifier.  Used when even
 288         <option>-dverbose-simpl</option> doesn't cut it.</para>
 289         </listitem>
 290       </varlistentry>
 291
 292       <varlistentry>
 293         <term>
 294           <option>-ddump-simpl-iterations</option>:
 295           <indexterm><primary><option>-ddump-simpl-iterations</option></primary></indexterm>
 296         </term>
 297         <listitem>
 298           <para>Show the output of each <emphasis>iteration</emphasis>
 299         of the simplifier (each run of the simplifier has a maximum
 300         number of iterations, normally 4).  This outputs even more information
 301         than <option>-ddump-simpl-phases</option>.</para>
 302         </listitem>
 303       </varlistentry>
 304
 305       <varlistentry>
 306         <term>
 307           <option>-ddump-simpl-stats</option>
 308           <indexterm><primary><option>-ddump-simpl-stats option</option></primary></indexterm>
 309         </term>
 310         <listitem>
 311           <para>Dump statistics about how many of each kind of
 312         transformation too place.  If you add
 313         <option>-dppr-debug</option> you get more detailed
 314         information.</para>
 315         </listitem>
 316       </varlistentry>
 317
 318       <varlistentry>
 319         <term>
 320           <option>-ddump-if-trace</option>
 321           <indexterm><primary><option>-ddump-if-trace</option></primary></indexterm>
 322         </term>
 323         <listitem>
 324           <para>Make the interface loader be *real* chatty about what it is
 325         upto.</para>
 326         </listitem>
 327       </varlistentry>
 328
 329       <varlistentry>
 330         <term>
 331           <option>-ddump-tc-trace</option>
 332           <indexterm><primary><option>-ddump-tc-trace</option></primary></indexterm>
 333         </term>
 334         <listitem>
 335           <para>Make the type checker be *real* chatty about what it is
 336         upto.</para>
 337         </listitem>
 338       </varlistentry>
 339
 340       <varlistentry>
 341         <term>
 342           <option>-ddump-rn-trace</option>
 343           <indexterm><primary><option>-ddump-rn-trace</option></primary></indexterm>
 344         </term>
 345         <listitem>
 346           <para>Make the renamer be *real* chatty about what it is
 347         upto.</para>
 348         </listitem>
 349       </varlistentry>
 350
 351       <varlistentry>
 352         <term>
 353           <option>-ddump-rn-stats</option>
 354           <indexterm><primary><option>-dshow-rn-stats</option></primary></indexterm>
 355         </term>
 356         <listitem>
 357           <para>Print out summary of what kind of information the renamer
 358         had to bring in.</para>
 359         </listitem>
 360       </varlistentry>
 361
 362       <varlistentry>
 363         <term>
 364           <option>-dverbose-core2core</option>
 365           <indexterm><primary><option>-dverbose-core2core</option></primary></indexterm>
 366         </term>
 367         <term>
 368           <option>-dverbose-stg2stg</option>
 369           <indexterm><primary><option>-dverbose-stg2stg</option></primary></indexterm>
 370         </term>
 371         <listitem>
 372           <para>Show the output of the intermediate Core-to-Core and
 373         STG-to-STG passes, respectively.  (<emphasis>Lots</emphasis>
 374         of output!) So: when we're really desperate:</para>
 375
 376           <screen>
 377 % ghc -noC -O -ddump-simpl -dverbose-simpl -dcore-lint Foo.hs
 378 </screen>
 379
 380         </listitem>
 381       </varlistentry>
 382
 383       <varlistentry>
 384         <term>
 385           <option>-dshow-passes</option>
 386           <indexterm><primary><option>-dshow-passes</option></primary></indexterm>
 387         </term>
 388         <listitem>
 389           <para>Print out each pass name as it happens.</para>
 390         </listitem>
 391       </varlistentry>
 392
 393       <varlistentry>
 394         <term>
 395           <option>-dfaststring-stats</option>
 396           <indexterm><primary><option>-dfaststring-stats</option></primary></indexterm>
 397         </term>
 398         <listitem>
 399           <para>Show statistics for the usage of fast strings by the
 400           compiler.</para>
 401         </listitem>
 402       </varlistentry>
 403
 404       <varlistentry>
 405         <term>
 406           <option>-dppr-debug</option>
 407           <indexterm><primary><option>-dppr-debug</option></primary></indexterm>
 408         </term>
 409         <listitem>
 410           <para>Debugging output is in one of several
 411           &ldquo;styles.&rdquo; Take the printing of types, for
 412           example.  In the &ldquo;user&rdquo; style (the default), the
 413           compiler's internal ideas about types are presented in
 414           Haskell source-level syntax, insofar as possible.  In the
 415           &ldquo;debug&rdquo; style (which is the default for
 416           debugging output), the types are printed in with explicit
 417           foralls, and variables have their unique-id attached (so you
 418           can check for things that look the same but aren't).  This
 419           flag makes debugging output appear in the more verbose debug
 420           style.</para>
 421         </listitem>
 422       </varlistentry>
 423
 424       <varlistentry>
 425         <term>
 426           <option>-dsuppress-uniques</option>
 427           <indexterm><primary><option>-dsuppress-uniques</option></primary></indexterm>
 428         </term>
 429         <listitem>
 430           <para>Suppress the printing of uniques in debugging output. This may make
 431           the printout ambiguous (e.g. unclear where an occurrence of 'x' is bound), but
 432           it makes the output of two compiler runs have many fewer gratuitous differences,
 433             so you can realistically apply <command>diff</command>.  Once <command>diff</command>
 434           has shown you where to look, you can try again without <option>-dsuppress-uniques</option></para>
 435         </listitem>
 436       </varlistentry>
 437
 438       <varlistentry>
 439         <term>
 440           <option>-dsuppress-coercions</option>
 441           <indexterm><primary><option>-dsuppress-coercions</option></primary></indexterm>
 442         </term>
 443         <listitem>
 444           <para>Suppress the printing of coercions in Core dumps to make them
 445 shorter.</para>
 446         </listitem>
 447       </varlistentry>
 448
 449       <varlistentry>
 450         <term>
 451           <option>-dppr-user-length</option>
 452           <indexterm><primary><option>-dppr-user-length</option></primary></indexterm>
 453         </term>
 454         <listitem>
 455           <para>In error messages, expressions are printed to a
 456           certain &ldquo;depth&rdquo;, with subexpressions beyond the
 457           depth replaced by ellipses.  This flag sets the
 458           depth.  Its default value is 5.</para>
 459         </listitem>
 460       </varlistentry>
 461
 462       <varlistentry>
 463         <term>
 464           <option>-dno-debug-output</option>
 465           <indexterm><primary><option>-dno-debug-output</option></primary></indexterm>
 466         </term>
 467         <listitem>
 468           <para>Suppress any unsolicited debugging output.  When GHC
 469             has been built with the <literal>DEBUG</literal> option it
 470             occasionally emits debug output of interest to developers.
 471             The extra output can confuse the testing framework and
 472             cause bogus test failures, so this flag is provided to
 473             turn it off.</para>
 474         </listitem>
 475       </varlistentry>
 476     </variablelist>
 477   </sect2>
 478
 479   <sect2 id="checking-consistency">
 480     <title>Checking for consistency</title>
 481
 482     <indexterm><primary>consistency checks</primary></indexterm>
 483     <indexterm><primary>lint</primary></indexterm>
 484
 485     <variablelist>
 486
 487       <varlistentry>
 488         <term>
 489           <option>-dcore-lint</option>
 490           <indexterm><primary><option>-dcore-lint</option></primary></indexterm>
 491         </term>
 492         <listitem>
 493           <para>Turn on heavyweight intra-pass sanity-checking within
 494           GHC, at Core level.  (It checks GHC's sanity, not yours.)</para>
 495         </listitem>
 496       </varlistentry>
 497
 498       <varlistentry>
 499         <term>
 500           <option>-dstg-lint</option>:
 501           <indexterm><primary><option>-dstg-lint</option></primary></indexterm>
 502         </term>
 503         <listitem>
 504           <para>Ditto for STG level. (NOTE: currently doesn't work).</para>
 505         </listitem>
 506       </varlistentry>
 507
 508       <varlistentry>
 509         <term>
 510           <option>-dcmm-lint</option>:
 511           <indexterm><primary><option>-dcmm-lint</option></primary></indexterm>
 512         </term>
 513         <listitem>
 514           <para>Ditto for C-- level.</para>
 515         </listitem>
 516       </varlistentry>
 517
 518     </variablelist>
 519   </sect2>
 520
 521   <sect2>
 522     <title>How to read Core syntax (from some <option>-ddump</option>
 523     flags)</title>
 524
 525     <indexterm><primary>reading Core syntax</primary></indexterm>
 526     <indexterm><primary>Core syntax, how to read</primary></indexterm>
 527
 528     <para>Let's do this by commenting an example.  It's from doing
 529     <option>-ddump-ds</option> on this code:
 530
 531 <programlisting>
 532 skip2 m = m : skip2 (m+2)
 533 </programlisting>
 534
 535     Before we jump in, a word about names of things.  Within GHC,
 536     variables, type constructors, etc., are identified by their
 537     &ldquo;Uniques.&rdquo; These are of the form `letter' plus
 538     `number' (both loosely interpreted).  The `letter' gives some idea
 539     of where the Unique came from; e.g., <literal>&lowbar;</literal>
 540     means &ldquo;built-in type variable&rdquo;; <literal>t</literal>
 541     means &ldquo;from the typechecker&rdquo;; <literal>s</literal>
 542     means &ldquo;from the simplifier&rdquo;; and so on.  The `number'
 543     is printed fairly compactly in a `base-62' format, which everyone
 544     hates except me (WDP).</para>
 545
 546     <para>Remember, everything has a &ldquo;Unique&rdquo; and it is
 547     usually printed out when debugging, in some form or another.  So
 548     here we go&hellip;</para>
 549
 550 <programlisting>
 551 Desugared:
 552 Main.skip2{-r1L6-} :: _forall_ a$_4 =&#62;{{Num a$_4}} -&#62; a$_4 -&#62; [a$_4]
 553
 554 --# `r1L6' is the Unique for Main.skip2;
 555 --# `_4' is the Unique for the type-variable (template) `a'
 556 --# `{{Num a$_4}}' is a dictionary argument
 557
 558 _NI_
 559
 560 --# `_NI_' means "no (pragmatic) information" yet; it will later
 561 --# evolve into the GHC_PRAGMA info that goes into interface files.
 562
 563 Main.skip2{-r1L6-} =
 564     /\ _4 -&#62; \ d.Num.t4Gt -&#62;
 565         let {
 566           {- CoRec -}
 567           +.t4Hg :: _4 -&#62; _4 -&#62; _4
 568           _NI_
 569           +.t4Hg = (+{-r3JH-} _4) d.Num.t4Gt
 570
 571           fromInt.t4GS :: Int{-2i-} -&#62; _4
 572           _NI_
 573           fromInt.t4GS = (fromInt{-r3JX-} _4) d.Num.t4Gt
 574
 575 --# The `+' class method (Unique: r3JH) selects the addition code
 576 --# from a `Num' dictionary (now an explicit lambda'd argument).
 577 --# Because Core is 2nd-order lambda-calculus, type applications
 578 --# and lambdas (/\) are explicit.  So `+' is first applied to a
 579 --# type (`_4'), then to a dictionary, yielding the actual addition
 580 --# function that we will use subsequently...
 581
 582 --# We play the exact same game with the (non-standard) class method
 583 --# `fromInt'.  Unsurprisingly, the type `Int' is wired into the
 584 --# compiler.
 585
 586           lit.t4Hb :: _4
 587           _NI_
 588           lit.t4Hb =
 589               let {
 590                 ds.d4Qz :: Int{-2i-}
 591                 _NI_
 592                 ds.d4Qz = I#! 2#
 593               } in  fromInt.t4GS ds.d4Qz
 594
 595 --# `I# 2#' is just the literal Int `2'; it reflects the fact that
 596 --# GHC defines `data Int = I# Int#', where Int# is the primitive
 597 --# unboxed type.  (see relevant info about unboxed types elsewhere...)
 598
 599 --# The `!' after `I#' indicates that this is a *saturated*
 600 --# application of the `I#' data constructor (i.e., not partially
 601 --# applied).
 602
 603           skip2.t3Ja :: _4 -&#62; [_4]
 604           _NI_
 605           skip2.t3Ja =
 606               \ m.r1H4 -&#62;
 607                   let { ds.d4QQ :: [_4]
 608                         _NI_
 609                         ds.d4QQ =
 610                     let {
 611                       ds.d4QY :: _4
 612                       _NI_
 613                       ds.d4QY = +.t4Hg m.r1H4 lit.t4Hb
 614                     } in  skip2.t3Ja ds.d4QY
 615                   } in
 616                   :! _4 m.r1H4 ds.d4QQ
 617
 618           {- end CoRec -}
 619         } in  skip2.t3Ja
 620 </programlisting>
 621
 622     <para>(&ldquo;It's just a simple functional language&rdquo; is an
 623     unregisterised trademark of Peyton Jones Enterprises, plc.)</para>
 624
 625   </sect2>
 626
 627   <sect2 id="unreg">
 628     <title>Unregisterised compilation</title>
 629     <indexterm><primary>unregisterised compilation</primary></indexterm>
 630
 631     <para>The term "unregisterised" really means "compile via vanilla
 632     C", disabling some of the platform-specific tricks that GHC
 633     normally uses to make programs go faster.  When compiling
 634     unregisterised, GHC simply generates a C file which is compiled
 635     via gcc.</para>
 636
 637     <para>Unregisterised compilation can be useful when porting GHC to
 638     a new machine, since it reduces the prerequisite tools to
 639     <command>gcc</command>, <command>as</command>, and
 640     <command>ld</command> and nothing more, and furthermore the amount
 641     of platform-specific code that needs to be written in order to get
 642     unregisterised compilation going is usually fairly small.</para>
 643
 644    <para>Unregisterised compilation cannot be selected at
 645    compile-time; you have to build GHC with the appropriate options
 646    set.  Consult the GHC Building Guide for details.</para>
 647   </sect2>
 648
 649 </sect1>
 650
 651 <!-- Emacs stuff:
 652      ;;; Local Variables: ***
 653      ;;; mode: xml ***
 654      ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter" "sect1") ***
 655      ;;; End: ***
 656  -->