ghc/docs/users_guide/debugging.sgml

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