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