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