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