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