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