docs/users_guide/debugging.xml

   1 <?xml version="1.0" encoding="iso-8859-1"?>
   2 <sect1 id="options-debugging">
   3   <title>Debugging the compiler</title>
   4
   5   <indexterm><primary>debugging options (for GHC)</primary></indexterm>
   6
   7   <para>HACKER TERRITORY. HACKER TERRITORY.  (You were warned.)</para>
   8
   9   <sect2 id="dumping-output">
  10     <title>Dumping out compiler intermediate structures</title>
  11
  12     <indexterm><primary>dumping GHC intermediates</primary></indexterm>
  13     <indexterm><primary>intermediate passes, output</primary></indexterm>
  14
  15     <variablelist>
  16       <varlistentry>
  17         <term>
  18           <option>-ddump-</option><replaceable>pass</replaceable>
  19           <indexterm><primary><option>-ddump</option> options</primary></indexterm>
  20         </term>
  21         <listitem>
  22           <para>Make a debugging dump after pass
  23         <literal>&lt;pass&gt;</literal> (may be common enough to need
  24         a short form&hellip;).  You can get all of these at once
  25         (<emphasis>lots</emphasis> of output) by using
  26         <option>-v5</option>, or most of them with
  27         <option>-v4</option>.  Some of the most useful ones
  28         are:</para>
  29
  30           <variablelist>
  31             <varlistentry>
  32               <term>
  33                 <option>-ddump-parsed</option>:
  34                 <indexterm><primary><option>-ddump-parsed</option></primary></indexterm>
  35               </term>
  36               <listitem>
  37                 <para>parser output</para>
  38               </listitem>
  39             </varlistentry>
  40
  41             <varlistentry>
  42               <term>
  43                 <option>-ddump-rn</option>:
  44                 <indexterm><primary><option>-ddump-rn</option></primary></indexterm>
  45               </term>
  46               <listitem>
  47                 <para>renamer output</para>
  48               </listitem>
  49             </varlistentry>
  50
  51             <varlistentry>
  52               <term>
  53                 <option>-ddump-tc</option>:
  54                 <indexterm><primary><option>-ddump-tc</option></primary></indexterm>
  55               </term>
  56               <listitem>
  57                 <para>typechecker output</para>
  58               </listitem>
  59             </varlistentry>
  60
  61             <varlistentry>
  62               <term>
  63                 <option>-ddump-splices</option>:
  64                 <indexterm><primary><option>-ddump-splices</option></primary></indexterm>
  65               </term>
  66               <listitem>
  67                 <para>Dump Template Haskell expressions that we splice in,
  68                 and what Haskell code the expression evaluates to.</para>
  69               </listitem>
  70             </varlistentry>
  71
  72             <varlistentry>
  73               <term>
  74                 <option>-ddump-types</option>:
  75                 <indexterm><primary><option>-ddump-types</option></primary></indexterm>
  76               </term>
  77               <listitem>
  78                 <para>Dump a type signature for each value defined at
  79               the top level of the module.  The list is sorted
  80               alphabetically.  Using <option>-dppr-debug</option>
  81               dumps a type signature for all the imported and
  82               system-defined things as well; useful for debugging the
  83               compiler.</para>
  84               </listitem>
  85             </varlistentry>
  86
  87             <varlistentry>
  88               <term>
  89                 <option>-ddump-deriv</option>:
  90                 <indexterm><primary><option>-ddump-deriv</option></primary></indexterm>
  91               </term>
  92               <listitem>
  93                 <para>derived instances</para>
  94               </listitem>
  95             </varlistentry>
  96
  97             <varlistentry>
  98               <term>
  99                 <option>-ddump-ds</option>:
 100                 <indexterm><primary><option>-ddump-ds</option></primary></indexterm>
 101               </term>
 102               <listitem>
 103                 <para>desugarer output</para>
 104               </listitem>
 105             </varlistentry>
 106
 107             <varlistentry>
 108               <term>
 109                 <option>-ddump-spec</option>:
 110                 <indexterm><primary><option>-ddump-spec</option></primary></indexterm>
 111               </term>
 112               <listitem>
 113                 <para>output of specialisation pass</para>
 114               </listitem>
 115             </varlistentry>
 116
 117             <varlistentry>
 118               <term>
 119                 <option>-ddump-rules</option>:
 120                 <indexterm><primary><option>-ddump-rules</option></primary></indexterm>
 121               </term>
 122               <listitem>
 123                 <para>dumps all rewrite rules specified in this module;
 124                       see <xref linkend="controlling-rules"/>.
 125                 </para>
 126               </listitem>
 127             </varlistentry>
 128
 129             <varlistentry>
 130               <term>
 131                 <option>-ddump-rule-firings</option>:
 132                 <indexterm><primary><option>-ddump-rule-firings</option></primary></indexterm>
 133               </term>
 134               <listitem>
 135                 <para>dumps the names of all rules that fired in this module</para>
 136               </listitem>
 137             </varlistentry>
 138
 139             <varlistentry>
 140               <term>
 141                 <option>-ddump-rule-rewrites</option>:
 142                 <indexterm><primary><option>-ddump-rule-rewrites</option></primary></indexterm>
 143               </term>
 144               <listitem>
 145                 <para>dumps detailed information about all rules that fired in
 146                       this module
 147                 </para>
 148               </listitem>
 149             </varlistentry>
 150
 151             <varlistentry>
 152               <term>
 153                 <option>-ddump-vect</option>:
 154                 <indexterm><primary><option>-ddump-vect</option></primary></indexterm>
 155               </term>
 156               <listitem>
 157                 <para>dumps the output of the vectoriser.
 158                 </para>
 159               </listitem>
 160             </varlistentry>
 161
 162             <varlistentry>
 163               <term>
 164                 <option>-ddump-simpl</option>:
 165                 <indexterm><primary><option>-ddump-simpl</option></primary></indexterm>
 166               </term>
 167               <listitem>
 168                 <para>simplifier output (Core-to-Core passes)</para>
 169               </listitem>
 170             </varlistentry>
 171
 172             <varlistentry>
 173               <term>
 174                 <option>-ddump-inlinings</option>:
 175                 <indexterm><primary><option>-ddump-inlinings</option></primary></indexterm>
 176               </term>
 177               <listitem>
 178                 <para>inlining info from the simplifier</para>
 179               </listitem>
 180             </varlistentry>
 181
 182             <varlistentry>
 183               <term>
 184                 <option>-ddump-cpranal</option>:
 185                 <indexterm><primary><option>-ddump-cpranal</option></primary></indexterm>
 186               </term>
 187               <listitem>
 188                 <para>CPR analyser output</para>
 189               </listitem>
 190             </varlistentry>
 191
 192             <varlistentry>
 193               <term>
 194                 <option>-ddump-stranal</option>:
 195                 <indexterm><primary><option>-ddump-stranal</option></primary></indexterm>
 196               </term>
 197               <listitem>
 198                 <para>strictness analyser output</para>
 199               </listitem>
 200             </varlistentry>
 201
 202             <varlistentry>
 203               <term>
 204                 <option>-ddump-cse</option>:
 205                 <indexterm><primary><option>-ddump-cse</option></primary></indexterm>
 206               </term>
 207               <listitem>
 208                 <para>CSE pass output</para>
 209               </listitem>
 210             </varlistentry>
 211
 212             <varlistentry>
 213               <term>
 214                 <option>-ddump-worker-wrapper</option>:
 215                 <indexterm><primary><option>-ddump-worker-wrapper</option></primary></indexterm>
 216               </term>
 217               <listitem>
 218                 <para>worker/wrapper split output</para>
 219               </listitem>
 220             </varlistentry>
 221
 222             <varlistentry>
 223               <term>
 224                 <option>-ddump-occur-anal</option>:
 225                 <indexterm><primary><option>-ddump-occur-anal</option></primary></indexterm>
 226               </term>
 227               <listitem>
 228                 <para>`occurrence analysis' output</para>
 229               </listitem>
 230             </varlistentry>
 231
 232             <varlistentry>
 233               <term>
 234                 <option>-ddump-prep</option>:
 235                 <indexterm><primary><option>-ddump-prep</option></primary></indexterm>
 236               </term>
 237               <listitem>
 238                 <para>output of core preparation pass</para>
 239               </listitem>
 240             </varlistentry>
 241
 242             <varlistentry>
 243               <term>
 244                 <option>-ddump-stg</option>:
 245                 <indexterm><primary><option>-ddump-stg</option></primary></indexterm>
 246               </term>
 247               <listitem>
 248                 <para>output of STG-to-STG passes</para>
 249               </listitem>
 250             </varlistentry>
 251
 252             <varlistentry>
 253               <term>
 254                 <option>-ddump-flatC</option>:
 255                 <indexterm><primary><option>-ddump-flatC</option></primary></indexterm>
 256               </term>
 257               <listitem>
 258                 <para><emphasis>flattened</emphasis> Abstract&nbsp;C</para>
 259               </listitem>
 260             </varlistentry>
 261
 262             <varlistentry>
 263               <term>
 264                 <option>-ddump-cmm</option>:
 265                 <indexterm><primary><option>-ddump-cmm</option></primary></indexterm>
 266               </term>
 267               <listitem>
 268                 <para>Print the C-- code out.</para>
 269               </listitem>
 270             </varlistentry>
 271
 272             <varlistentry>
 273               <term>
 274                 <option>-ddump-opt-cmm</option>:
 275                 <indexterm><primary><option>-ddump-opt-cmm</option></primary></indexterm>
 276               </term>
 277               <listitem>
 278                 <para>Dump the results of C-- to C-- optimising passes.</para>
 279               </listitem>
 280             </varlistentry>
 281
 282             <varlistentry>
 283               <term>
 284                 <option>-ddump-asm</option>:
 285                 <indexterm><primary><option>-ddump-asm</option></primary></indexterm>
 286               </term>
 287               <listitem>
 288                 <para>assembly language from the native-code generator</para>
 289               </listitem>
 290             </varlistentry>
 291
 292             <varlistentry>
 293               <term>
 294                 <option>-ddump-bcos</option>:
 295                 <indexterm><primary><option>-ddump-bcos</option></primary></indexterm>
 296               </term>
 297               <listitem>
 298                 <para>byte code compiler output</para>
 299               </listitem>
 300             </varlistentry>
 301
 302             <varlistentry>
 303               <term>
 304                 <option>-ddump-foreign</option>:
 305                 <indexterm><primary><option>-ddump-foreign</option></primary></indexterm>
 306               </term>
 307               <listitem>
 308                 <para>dump foreign export stubs</para>
 309               </listitem>
 310             </varlistentry>
 311           </variablelist>
 312         </listitem>
 313       </varlistentry>
 314
 315       <varlistentry>
 316         <term>
 317           <option>-ddump-simpl-phases</option>:
 318           <indexterm><primary><option>-ddump-simpl-phases</option></primary></indexterm>
 319         </term>
 320         <listitem>
 321           <para>Show the output of each run of the simplifier.  Used when even
 322         <option>-dverbose-core2core</option> doesn't cut it.</para>
 323         </listitem>
 324       </varlistentry>
 325
 326       <varlistentry>
 327         <term>
 328           <option>-ddump-simpl-iterations</option>:
 329           <indexterm><primary><option>-ddump-simpl-iterations</option></primary></indexterm>
 330         </term>
 331         <listitem>
 332           <para>Show the output of each <emphasis>iteration</emphasis>
 333         of the simplifier (each run of the simplifier has a maximum
 334         number of iterations, normally 4).  This outputs even more information
 335         than <option>-ddump-simpl-phases</option>.</para>
 336         </listitem>
 337       </varlistentry>
 338
 339       <varlistentry>
 340         <term>
 341           <option>-ddump-simpl-stats</option>
 342           <indexterm><primary><option>-ddump-simpl-stats option</option></primary></indexterm>
 343         </term>
 344         <listitem>
 345           <para>Dump statistics about how many of each kind of
 346         transformation too place.  If you add
 347         <option>-dppr-debug</option> you get more detailed
 348         information.</para>
 349         </listitem>
 350       </varlistentry>
 351
 352       <varlistentry>
 353         <term>
 354           <option>-ddump-if-trace</option>
 355           <indexterm><primary><option>-ddump-if-trace</option></primary></indexterm>
 356         </term>
 357         <listitem>
 358           <para>Make the interface loader be *real* chatty about what it is
 359         upto.</para>
 360         </listitem>
 361       </varlistentry>
 362
 363       <varlistentry>
 364   <term>
 365           <option>-ddump-tc-trace</option>
 366           <indexterm><primary><option>-ddump-tc-trace</option></primary></indexterm>
 367         </term>
 368   <listitem>
 369     <para>Make the type checker be *real* chatty about what it is
 370   upto.</para>
 371   </listitem>
 372       </varlistentry>
 373
 374       <varlistentry>
 375   <term>
 376           <option>-ddump-vt-trace</option>
 377           <indexterm><primary><option>-ddump-tv-trace</option></primary></indexterm>
 378         </term>
 379   <listitem>
 380     <para>Make the vectoriser be *real* chatty about what it is
 381   upto.</para>
 382   </listitem>
 383       </varlistentry>
 384
 385       <varlistentry>
 386         <term>
 387           <option>-ddump-rn-trace</option>
 388           <indexterm><primary><option>-ddump-rn-trace</option></primary></indexterm>
 389         </term>
 390         <listitem>
 391           <para>Make the renamer be *real* chatty about what it is
 392         upto.</para>
 393         </listitem>
 394       </varlistentry>
 395
 396       <varlistentry>
 397         <term>
 398           <option>-ddump-rn-stats</option>
 399           <indexterm><primary><option>-dshow-rn-stats</option></primary></indexterm>
 400         </term>
 401         <listitem>
 402           <para>Print out summary of what kind of information the renamer
 403         had to bring in.</para>
 404         </listitem>
 405       </varlistentry>
 406
 407       <varlistentry>
 408         <term>
 409           <option>-dverbose-core2core</option>
 410           <indexterm><primary><option>-dverbose-core2core</option></primary></indexterm>
 411         </term>
 412         <term>
 413           <option>-dverbose-stg2stg</option>
 414           <indexterm><primary><option>-dverbose-stg2stg</option></primary></indexterm>
 415         </term>
 416         <listitem>
 417           <para>Show the output of the intermediate Core-to-Core and
 418         STG-to-STG passes, respectively.  (<emphasis>Lots</emphasis>
 419         of output!) So: when we're really desperate:</para>
 420
 421           <screen>
 422 % ghc -noC -O -ddump-simpl -dverbose-core2core -dcore-lint Foo.hs
 423 </screen>
 424
 425         </listitem>
 426       </varlistentry>
 427
 428       <varlistentry>
 429         <term>
 430           <option>-dshow-passes</option>
 431           <indexterm><primary><option>-dshow-passes</option></primary></indexterm>
 432         </term>
 433         <listitem>
 434           <para>Print out each pass name as it happens.</para>
 435         </listitem>
 436       </varlistentry>
 437
 438       <varlistentry>
 439         <term>
 440           <option>-ddump-core-stats</option>
 441           <indexterm><primary><option>-ddump-core-stats</option></primary></indexterm>
 442         </term>
 443         <listitem>
 444           <para>Print a one-line summary of the size of the Core program
 445                      at the end of the optimisation pipeline.</para>
 446         </listitem>
 447       </varlistentry>
 448
 449       <varlistentry>
 450         <term>
 451           <option>-dfaststring-stats</option>
 452           <indexterm><primary><option>-dfaststring-stats</option></primary></indexterm>
 453         </term>
 454         <listitem>
 455           <para>Show statistics for the usage of fast strings by the
 456           compiler.</para>
 457         </listitem>
 458       </varlistentry>
 459
 460       <varlistentry>
 461         <term>
 462           <option>-dppr-debug</option>
 463           <indexterm><primary><option>-dppr-debug</option></primary></indexterm>
 464         </term>
 465         <listitem>
 466           <para>Debugging output is in one of several
 467           &ldquo;styles.&rdquo; Take the printing of types, for
 468           example.  In the &ldquo;user&rdquo; style (the default), the
 469           compiler's internal ideas about types are presented in
 470           Haskell source-level syntax, insofar as possible.  In the
 471           &ldquo;debug&rdquo; style (which is the default for
 472           debugging output), the types are printed in with explicit
 473           foralls, and variables have their unique-id attached (so you
 474           can check for things that look the same but aren't).  This
 475           flag makes debugging output appear in the more verbose debug
 476           style.</para>
 477         </listitem>
 478       </varlistentry>
 479
 480       <varlistentry>
 481         <term>
 482           <option>-dsuppress-uniques</option>
 483           <indexterm><primary><option>-dsuppress-uniques</option></primary></indexterm>
 484         </term>
 485         <listitem>
 486           <para>Suppress the printing of uniques in debugging output. This may make
 487           the printout ambiguous (e.g. unclear where an occurrence of 'x' is bound), but
 488           it makes the output of two compiler runs have many fewer gratuitous differences,
 489             so you can realistically apply <command>diff</command>.  Once <command>diff</command>
 490           has shown you where to look, you can try again without <option>-dsuppress-uniques</option></para>
 491         </listitem>
 492       </varlistentry>
 493
 494       <varlistentry>
 495         <term>
 496           <option>-dsuppress-coercions</option>
 497           <indexterm><primary><option>-dsuppress-coercions</option></primary></indexterm>
 498         </term>
 499         <listitem>
 500           <para>Suppress the printing of coercions in Core dumps to make them
 501 shorter.</para>
 502         </listitem>
 503       </varlistentry>
 504
 505       <varlistentry>
 506         <term>
 507           <option>-dsuppress-module-prefixes</option>
 508           <indexterm><primary><option>-dsuppress-module-prefixes</option></primary></indexterm>
 509         </term>
 510         <listitem>
 511           <para>Suppress the printing of module qualification prefixes in Core dumps to make them easier to read.</para>
 512         </listitem>
 513       </varlistentry>
 514
 515       <varlistentry>
 516         <term>
 517           <option>-dppr-user-length</option>
 518           <indexterm><primary><option>-dppr-user-length</option></primary></indexterm>
 519         </term>
 520         <listitem>
 521           <para>In error messages, expressions are printed to a
 522           certain &ldquo;depth&rdquo;, with subexpressions beyond the
 523           depth replaced by ellipses.  This flag sets the
 524           depth.  Its default value is 5.</para>
 525         </listitem>
 526       </varlistentry>
 527
 528       <varlistentry>
 529         <term>
 530           <option>-dno-debug-output</option>
 531           <indexterm><primary><option>-dno-debug-output</option></primary></indexterm>
 532         </term>
 533         <listitem>
 534           <para>Suppress any unsolicited debugging output.  When GHC
 535             has been built with the <literal>DEBUG</literal> option it
 536             occasionally emits debug output of interest to developers.
 537             The extra output can confuse the testing framework and
 538             cause bogus test failures, so this flag is provided to
 539             turn it off.</para>
 540         </listitem>
 541       </varlistentry>
 542     </variablelist>
 543   </sect2>
 544
 545   <sect2 id="checking-consistency">
 546     <title>Checking for consistency</title>
 547
 548     <indexterm><primary>consistency checks</primary></indexterm>
 549     <indexterm><primary>lint</primary></indexterm>
 550
 551     <variablelist>
 552
 553       <varlistentry>
 554         <term>
 555           <option>-dcore-lint</option>
 556           <indexterm><primary><option>-dcore-lint</option></primary></indexterm>
 557         </term>
 558         <listitem>
 559           <para>Turn on heavyweight intra-pass sanity-checking within
 560           GHC, at Core level.  (It checks GHC's sanity, not yours.)</para>
 561         </listitem>
 562       </varlistentry>
 563
 564       <varlistentry>
 565         <term>
 566           <option>-dstg-lint</option>:
 567           <indexterm><primary><option>-dstg-lint</option></primary></indexterm>
 568         </term>
 569         <listitem>
 570           <para>Ditto for STG level. (NOTE: currently doesn't work).</para>
 571         </listitem>
 572       </varlistentry>
 573
 574       <varlistentry>
 575         <term>
 576           <option>-dcmm-lint</option>:
 577           <indexterm><primary><option>-dcmm-lint</option></primary></indexterm>
 578         </term>
 579         <listitem>
 580           <para>Ditto for C-- level.</para>
 581         </listitem>
 582       </varlistentry>
 583
 584     </variablelist>
 585   </sect2>
 586
 587   <sect2>
 588     <title>How to read Core syntax (from some <option>-ddump</option>
 589     flags)</title>
 590
 591     <indexterm><primary>reading Core syntax</primary></indexterm>
 592     <indexterm><primary>Core syntax, how to read</primary></indexterm>
 593
 594     <para>Let's do this by commenting an example.  It's from doing
 595     <option>-ddump-ds</option> on this code:
 596
 597 <programlisting>
 598 skip2 m = m : skip2 (m+2)
 599 </programlisting>
 600
 601     Before we jump in, a word about names of things.  Within GHC,
 602     variables, type constructors, etc., are identified by their
 603     &ldquo;Uniques.&rdquo; These are of the form `letter' plus
 604     `number' (both loosely interpreted).  The `letter' gives some idea
 605     of where the Unique came from; e.g., <literal>&lowbar;</literal>
 606     means &ldquo;built-in type variable&rdquo;; <literal>t</literal>
 607     means &ldquo;from the typechecker&rdquo;; <literal>s</literal>
 608     means &ldquo;from the simplifier&rdquo;; and so on.  The `number'
 609     is printed fairly compactly in a `base-62' format, which everyone
 610     hates except me (WDP).</para>
 611
 612     <para>Remember, everything has a &ldquo;Unique&rdquo; and it is
 613     usually printed out when debugging, in some form or another.  So
 614     here we go&hellip;</para>
 615
 616 <programlisting>
 617 Desugared:
 618 Main.skip2{-r1L6-} :: _forall_ a$_4 =&#62;{{Num a$_4}} -&#62; a$_4 -&#62; [a$_4]
 619
 620 --# `r1L6' is the Unique for Main.skip2;
 621 --# `_4' is the Unique for the type-variable (template) `a'
 622 --# `{{Num a$_4}}' is a dictionary argument
 623
 624 _NI_
 625
 626 --# `_NI_' means "no (pragmatic) information" yet; it will later
 627 --# evolve into the GHC_PRAGMA info that goes into interface files.
 628
 629 Main.skip2{-r1L6-} =
 630     /\ _4 -&#62; \ d.Num.t4Gt -&#62;
 631         let {
 632           {- CoRec -}
 633           +.t4Hg :: _4 -&#62; _4 -&#62; _4
 634           _NI_
 635           +.t4Hg = (+{-r3JH-} _4) d.Num.t4Gt
 636
 637           fromInt.t4GS :: Int{-2i-} -&#62; _4
 638           _NI_
 639           fromInt.t4GS = (fromInt{-r3JX-} _4) d.Num.t4Gt
 640
 641 --# The `+' class method (Unique: r3JH) selects the addition code
 642 --# from a `Num' dictionary (now an explicit lambda'd argument).
 643 --# Because Core is 2nd-order lambda-calculus, type applications
 644 --# and lambdas (/\) are explicit.  So `+' is first applied to a
 645 --# type (`_4'), then to a dictionary, yielding the actual addition
 646 --# function that we will use subsequently...
 647
 648 --# We play the exact same game with the (non-standard) class method
 649 --# `fromInt'.  Unsurprisingly, the type `Int' is wired into the
 650 --# compiler.
 651
 652           lit.t4Hb :: _4
 653           _NI_
 654           lit.t4Hb =
 655               let {
 656                 ds.d4Qz :: Int{-2i-}
 657                 _NI_
 658                 ds.d4Qz = I#! 2#
 659               } in  fromInt.t4GS ds.d4Qz
 660
 661 --# `I# 2#' is just the literal Int `2'; it reflects the fact that
 662 --# GHC defines `data Int = I# Int#', where Int# is the primitive
 663 --# unboxed type.  (see relevant info about unboxed types elsewhere...)
 664
 665 --# The `!' after `I#' indicates that this is a *saturated*
 666 --# application of the `I#' data constructor (i.e., not partially
 667 --# applied).
 668
 669           skip2.t3Ja :: _4 -&#62; [_4]
 670           _NI_
 671           skip2.t3Ja =
 672               \ m.r1H4 -&#62;
 673                   let { ds.d4QQ :: [_4]
 674                         _NI_
 675                         ds.d4QQ =
 676                     let {
 677                       ds.d4QY :: _4
 678                       _NI_
 679                       ds.d4QY = +.t4Hg m.r1H4 lit.t4Hb
 680                     } in  skip2.t3Ja ds.d4QY
 681                   } in
 682                   :! _4 m.r1H4 ds.d4QQ
 683
 684           {- end CoRec -}
 685         } in  skip2.t3Ja
 686 </programlisting>
 687
 688     <para>(&ldquo;It's just a simple functional language&rdquo; is an
 689     unregisterised trademark of Peyton Jones Enterprises, plc.)</para>
 690
 691   </sect2>
 692
 693   <sect2 id="unreg">
 694     <title>Unregisterised compilation</title>
 695     <indexterm><primary>unregisterised compilation</primary></indexterm>
 696
 697     <para>The term "unregisterised" really means "compile via vanilla
 698     C", disabling some of the platform-specific tricks that GHC
 699     normally uses to make programs go faster.  When compiling
 700     unregisterised, GHC simply generates a C file which is compiled
 701     via gcc.</para>
 702
 703     <para>Unregisterised compilation can be useful when porting GHC to
 704     a new machine, since it reduces the prerequisite tools to
 705     <command>gcc</command>, <command>as</command>, and
 706     <command>ld</command> and nothing more, and furthermore the amount
 707     of platform-specific code that needs to be written in order to get
 708     unregisterised compilation going is usually fairly small.</para>
 709
 710    <para>Unregisterised compilation cannot be selected at
 711    compile-time; you have to build GHC with the appropriate options
 712    set.  Consult the GHC Building Guide for details.</para>
 713   </sect2>
 714
 715 </sect1>
 716
 717 <!-- Emacs stuff:
 718      ;;; Local Variables: ***
 719      ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter" "sect1") ***
 720      ;;; End: ***
 721  -->