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