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>-dppr-user-length</option>
 441           <indexterm><primary><option>-dppr-user-length</option></primary></indexterm>
 442         </term>
 443         <listitem>
 444           <para>In error messages, expressions are printed to a
 445           certain &ldquo;depth&rdquo;, with subexpressions beyond the
 446           depth replaced by ellipses.  This flag sets the
 447           depth.  Its default value is 5.</para>
 448         </listitem>
 449       </varlistentry>
 450
 451       <varlistentry>
 452         <term>
 453           <option>-dno-debug-output</option>
 454           <indexterm><primary><option>-dno-debug-output</option></primary></indexterm>
 455         </term>
 456         <listitem>
 457           <para>Suppress any unsolicited debugging output.  When GHC
 458             has been built with the <literal>DEBUG</literal> option it
 459             occasionally emits debug output of interest to developers.
 460             The extra output can confuse the testing framework and
 461             cause bogus test failures, so this flag is provided to
 462             turn it off.</para>
 463         </listitem>
 464       </varlistentry>
 465     </variablelist>
 466   </sect2>
 467
 468   <sect2 id="checking-consistency">
 469     <title>Checking for consistency</title>
 470
 471     <indexterm><primary>consistency checks</primary></indexterm>
 472     <indexterm><primary>lint</primary></indexterm>
 473
 474     <variablelist>
 475
 476       <varlistentry>
 477         <term>
 478           <option>-dcore-lint</option>
 479           <indexterm><primary><option>-dcore-lint</option></primary></indexterm>
 480         </term>
 481         <listitem>
 482           <para>Turn on heavyweight intra-pass sanity-checking within
 483           GHC, at Core level.  (It checks GHC's sanity, not yours.)</para>
 484         </listitem>
 485       </varlistentry>
 486
 487       <varlistentry>
 488         <term>
 489           <option>-dstg-lint</option>:
 490           <indexterm><primary><option>-dstg-lint</option></primary></indexterm>
 491         </term>
 492         <listitem>
 493           <para>Ditto for STG level. (NOTE: currently doesn't work).</para>
 494         </listitem>
 495       </varlistentry>
 496
 497       <varlistentry>
 498         <term>
 499           <option>-dcmm-lint</option>:
 500           <indexterm><primary><option>-dcmm-lint</option></primary></indexterm>
 501         </term>
 502         <listitem>
 503           <para>Ditto for C-- level.</para>
 504         </listitem>
 505       </varlistentry>
 506
 507     </variablelist>
 508   </sect2>
 509
 510   <sect2>
 511     <title>How to read Core syntax (from some <option>-ddump</option>
 512     flags)</title>
 513
 514     <indexterm><primary>reading Core syntax</primary></indexterm>
 515     <indexterm><primary>Core syntax, how to read</primary></indexterm>
 516
 517     <para>Let's do this by commenting an example.  It's from doing
 518     <option>-ddump-ds</option> on this code:
 519
 520 <programlisting>
 521 skip2 m = m : skip2 (m+2)
 522 </programlisting>
 523
 524     Before we jump in, a word about names of things.  Within GHC,
 525     variables, type constructors, etc., are identified by their
 526     &ldquo;Uniques.&rdquo; These are of the form `letter' plus
 527     `number' (both loosely interpreted).  The `letter' gives some idea
 528     of where the Unique came from; e.g., <literal>&lowbar;</literal>
 529     means &ldquo;built-in type variable&rdquo;; <literal>t</literal>
 530     means &ldquo;from the typechecker&rdquo;; <literal>s</literal>
 531     means &ldquo;from the simplifier&rdquo;; and so on.  The `number'
 532     is printed fairly compactly in a `base-62' format, which everyone
 533     hates except me (WDP).</para>
 534
 535     <para>Remember, everything has a &ldquo;Unique&rdquo; and it is
 536     usually printed out when debugging, in some form or another.  So
 537     here we go&hellip;</para>
 538
 539 <programlisting>
 540 Desugared:
 541 Main.skip2{-r1L6-} :: _forall_ a$_4 =&#62;{{Num a$_4}} -&#62; a$_4 -&#62; [a$_4]
 542
 543 --# `r1L6' is the Unique for Main.skip2;
 544 --# `_4' is the Unique for the type-variable (template) `a'
 545 --# `{{Num a$_4}}' is a dictionary argument
 546
 547 _NI_
 548
 549 --# `_NI_' means "no (pragmatic) information" yet; it will later
 550 --# evolve into the GHC_PRAGMA info that goes into interface files.
 551
 552 Main.skip2{-r1L6-} =
 553     /\ _4 -&#62; \ d.Num.t4Gt -&#62;
 554         let {
 555           {- CoRec -}
 556           +.t4Hg :: _4 -&#62; _4 -&#62; _4
 557           _NI_
 558           +.t4Hg = (+{-r3JH-} _4) d.Num.t4Gt
 559
 560           fromInt.t4GS :: Int{-2i-} -&#62; _4
 561           _NI_
 562           fromInt.t4GS = (fromInt{-r3JX-} _4) d.Num.t4Gt
 563
 564 --# The `+' class method (Unique: r3JH) selects the addition code
 565 --# from a `Num' dictionary (now an explicit lambda'd argument).
 566 --# Because Core is 2nd-order lambda-calculus, type applications
 567 --# and lambdas (/\) are explicit.  So `+' is first applied to a
 568 --# type (`_4'), then to a dictionary, yielding the actual addition
 569 --# function that we will use subsequently...
 570
 571 --# We play the exact same game with the (non-standard) class method
 572 --# `fromInt'.  Unsurprisingly, the type `Int' is wired into the
 573 --# compiler.
 574
 575           lit.t4Hb :: _4
 576           _NI_
 577           lit.t4Hb =
 578               let {
 579                 ds.d4Qz :: Int{-2i-}
 580                 _NI_
 581                 ds.d4Qz = I#! 2#
 582               } in  fromInt.t4GS ds.d4Qz
 583
 584 --# `I# 2#' is just the literal Int `2'; it reflects the fact that
 585 --# GHC defines `data Int = I# Int#', where Int# is the primitive
 586 --# unboxed type.  (see relevant info about unboxed types elsewhere...)
 587
 588 --# The `!' after `I#' indicates that this is a *saturated*
 589 --# application of the `I#' data constructor (i.e., not partially
 590 --# applied).
 591
 592           skip2.t3Ja :: _4 -&#62; [_4]
 593           _NI_
 594           skip2.t3Ja =
 595               \ m.r1H4 -&#62;
 596                   let { ds.d4QQ :: [_4]
 597                         _NI_
 598                         ds.d4QQ =
 599                     let {
 600                       ds.d4QY :: _4
 601                       _NI_
 602                       ds.d4QY = +.t4Hg m.r1H4 lit.t4Hb
 603                     } in  skip2.t3Ja ds.d4QY
 604                   } in
 605                   :! _4 m.r1H4 ds.d4QQ
 606
 607           {- end CoRec -}
 608         } in  skip2.t3Ja
 609 </programlisting>
 610
 611     <para>(&ldquo;It's just a simple functional language&rdquo; is an
 612     unregisterised trademark of Peyton Jones Enterprises, plc.)</para>
 613
 614   </sect2>
 615
 616   <sect2 id="unreg">
 617     <title>Unregisterised compilation</title>
 618     <indexterm><primary>unregisterised compilation</primary></indexterm>
 619
 620     <para>The term "unregisterised" really means "compile via vanilla
 621     C", disabling some of the platform-specific tricks that GHC
 622     normally uses to make programs go faster.  When compiling
 623     unregisterised, GHC simply generates a C file which is compiled
 624     via gcc.</para>
 625
 626     <para>Unregisterised compilation can be useful when porting GHC to
 627     a new machine, since it reduces the prerequisite tools to
 628     <command>gcc</command>, <command>as</command>, and
 629     <command>ld</command> and nothing more, and furthermore the amount
 630     of platform-specific code that needs to be written in order to get
 631     unregisterised compilation going is usually fairly small.</para>
 632
 633    <para>Unregisterised compilation cannot be selected at
 634    compile-time; you have to build GHC with the appropriate options
 635    set.  Consult the GHC Building Guide for details.</para>
 636   </sect2>
 637
 638 </sect1>
 639
 640 <!-- Emacs stuff:
 641      ;;; Local Variables: ***
 642      ;;; mode: xml ***
 643      ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter" "sect1") ***
 644      ;;; End: ***
 645  -->