ghc/docs/users_guide/debugging.sgml

   1 <Sect1 id="options-debugging">
   2 <Title>Debugging the compiler
   3 </Title>
   4
   5 <Para>
   6 <IndexTerm><Primary>debugging options (for GHC)</Primary></IndexTerm>
   7 </Para>
   8
   9 <Para>
  10 HACKER TERRITORY. HACKER TERRITORY.
  11 (You were warned.)
  12 </Para>
  13
  14 <Sect2 id="replacing-phases">
  15 <Title>Replacing the program for one or more phases.
  16 </Title>
  17
  18 <Para>
  19 <IndexTerm><Primary>GHC phases, changing</Primary></IndexTerm>
  20 <IndexTerm><Primary>phases, changing GHC</Primary></IndexTerm>
  21 You may specify that a different program be used for one of the phases
  22 of the compilation system, in place of whatever the driver <Command>ghc</Command> has
  23 wired into it.  For example, you might want to try a different
  24 assembler.  The
  25 <Option>-pgm&lt;phase-code&gt;&lt;program-name&gt;</Option><IndexTerm><Primary>-pgm&lt;phase&gt;&lt;stuff&gt;
  26 option</Primary></IndexTerm> option to <Command>ghc</Command> will cause it to use <Literal>&lt;program-name&gt;</Literal>
  27 for phase <Literal>&lt;phase-code&gt;</Literal>, where the codes to indicate the phases are:
  28 </Para>
  29
  30 <Para>
  31 <InformalTable>
  32 <TGroup Cols="2">
  33 <ColSpec Align="Left" Colsep="0">
  34 <ColSpec Align="Left" Colsep="0">
  35 <TBody>
  36 <Row>
  37 <Entry><Emphasis>code</Emphasis> </Entry>
  38 <Entry><Emphasis>phase</Emphasis> </Entry>
  39 </Row>
  40
  41 <Row>
  42 <Entry>
  43 L </Entry>
  44 <Entry> literate pre-processor </Entry>
  45 </Row>
  46 <Row>
  47 <Entry>
  48 P </Entry>
  49 <Entry> C pre-processor (if -cpp only) </Entry>
  50 </Row>
  51 <Row>
  52 <Entry>
  53 C </Entry>
  54 <Entry> Haskell compiler </Entry>
  55 </Row>
  56 <Row>
  57 <Entry>
  58 c </Entry>
  59 <Entry> C compiler</Entry>
  60 </Row>
  61 <Row>
  62 <Entry>
  63 a </Entry>
  64 <Entry> assembler </Entry>
  65 </Row>
  66 <Row>
  67 <Entry>
  68 l </Entry>
  69 <Entry> linker </Entry>
  70 </Row>
  71 <Row>
  72 <Entry>
  73 dep </Entry>
  74 <Entry> Makefile dependency generator </Entry>
  75 </Row>
  76
  77 </TBody>
  78
  79 </TGroup>
  80 </InformalTable>
  81 </Para>
  82
  83 </Sect2>
  84
  85 <Sect2 id="forcing-options-through">
  86 <Title>Forcing options to a particular phase.
  87 </Title>
  88
  89 <Para>
  90 <IndexTerm><Primary>forcing GHC-phase options</Primary></IndexTerm>
  91 </Para>
  92
  93 <Para>
  94 The preceding sections describe driver options that are mostly
  95 applicable to one particular phase.  You may also <Emphasis>force</Emphasis> a
  96 specific option <Option>&lt;option&gt;</Option> to be passed to a particular phase
  97 <Literal>&lt;phase-code&gt;</Literal> by feeding the driver the option
  98 <Option>-opt&lt;phase-code&gt;&lt;option&gt;</Option>.<IndexTerm><Primary>-opt&lt;phase&gt;&lt;stuff&gt;
  99 option</Primary></IndexTerm> The codes to indicate the phases are the same as in the
 100 previous section.
 101 </Para>
 102
 103 <Para>
 104 So, for example, to force an <Option>-Ewurble</Option> option to the assembler, you
 105 would tell the driver <Option>-opta-Ewurble</Option> (the dash before the E is
 106 required).
 107 </Para>
 108
 109 <Para>
 110 Besides getting options to the Haskell compiler with <Option>-optC&lt;blah&gt;</Option>,
 111 you can get options through to its runtime system with
 112 <Option>-optCrts&lt;blah&gt;</Option><IndexTerm><Primary>-optCrts&lt;blah&gt; option</Primary></IndexTerm>.
 113 </Para>
 114
 115 <Para>
 116 So, for example: when I want to use my normal driver but with my
 117 profiled compiler binary, I use this script:
 118
 119 <ProgramListing>
 120 #! /bin/sh
 121 exec /local/grasp_tmp3/simonpj/ghc-BUILDS/working-alpha/ghc/driver/ghc \
 122      -pgmC/local/grasp_tmp3/simonpj/ghc-BUILDS/working-hsc-prof/hsc \
 123      -optCrts-i0.5 \
 124      -optCrts-PT \
 125      "$@"
 126 </ProgramListing>
 127
 128 </Para>
 129
 130 </Sect2>
 131
 132 <Sect2 id="dumping-output">
 133 <Title>Dumping out compiler intermediate structures
 134 </Title>
 135
 136 <Para>
 137 <IndexTerm><Primary>dumping GHC intermediates</Primary></IndexTerm>
 138 <IndexTerm><Primary>intermediate passes, output</Primary></IndexTerm>
 139 </Para>
 140
 141 <Para>
 142 <VariableList>
 143
 144 <VarListEntry>
 145 <Term><Option>-hi</Option>:</Term>
 146 <ListItem>
 147 <Para>
 148 <IndexTerm><Primary>-hi option</Primary></IndexTerm>
 149 <Emphasis>Do</Emphasis> generate an interface file.  This would normally be used in
 150 conjunction with <Option>-noC</Option>, which turns off interface generation;
 151 thus: <Option>-noC -hi</Option>.
 152 </Para>
 153 </ListItem>
 154 </VarListEntry>
 155 <VarListEntry>
 156 <Term><Option>-dshow-passes</Option>:</Term>
 157 <ListItem>
 158 <Para>
 159 <IndexTerm><Primary>-dshow-passes option</Primary></IndexTerm>
 160 Prints a message to stderr as each pass starts.  Gives a warm but
 161 undoubtedly misleading feeling that GHC is telling you what's
 162 happening.
 163 </Para>
 164 </ListItem>
 165 </VarListEntry>
 166 <VarListEntry>
 167 <Term><Option>-ddump-&lt;pass&gt;</Option>:</Term>
 168 <ListItem>
 169 <Para>
 170 <IndexTerm><Primary>-ddump-&lt;pass&gt; options</Primary></IndexTerm>
 171 Make a debugging dump after pass <Literal>&lt;pass&gt;</Literal> (may be common enough to
 172 need a short form&hellip;).  You can get all of these at once (<Emphasis>lots</Emphasis> of
 173 output) by using <Option>-ddump-all</Option>, or most of them with <Option>-ddump-most</Option>.
 174 Some of the most useful ones are:
 175 </Para>
 176
 177 <Para>
 178 <VariableList>
 179
 180 <VarListEntry>
 181 <Term><Option>-ddump-parsed</Option>:</Term>
 182 <ListItem>
 183 <Para>
 184 parser output
 185 </Para>
 186 </ListItem>
 187 </VarListEntry>
 188
 189 <VarListEntry>
 190 <Term><Option>-ddump-rn</Option>:</Term>
 191 <ListItem>
 192 <Para>
 193 renamer output
 194 </Para>
 195 </ListItem>
 196 </VarListEntry>
 197
 198 <VarListEntry>
 199 <Term><Option>-ddump-minimal-imports</Option>:</Term>
 200 <ListItem>
 201 <Para>
 202 Dump to the file "M.imports" (where M is the module being compiled)
 203 a "minimal" set of import declarations.  You can safely replace
 204 all the import declarations in "M.hs" with those found in "M.imports".
 205 Why would you want to do that?  Because the "minimal" imports (a) import
 206 everything explicitly, by name, and (b) import nothing that is not required.
 207 It can be quite painful to maintain this property by hand, so this flag is
 208 intended to reduce the labour.
 209 </Para>
 210 </ListItem>
 211 </VarListEntry>
 212
 213 <VarListEntry>
 214 <Term><Option>-ddump-hi-diffs</Option>:</Term>
 215 <ListItem>
 216 <Para>
 217 Dump to stdout a summary of the differences between the existing interface file (if any)
 218 for this module, and the new one.
 219 </Para>
 220 </ListItem>
 221 </VarListEntry>
 222
 223 <VarListEntry>
 224 <Term><Option>-ddump-tc</Option>:</Term>
 225 <ListItem>
 226 <Para>
 227 typechecker output
 228 </Para>
 229 </ListItem>
 230 </VarListEntry>
 231
 232 <VarListEntry>
 233 <Term><Option>-ddump-types</Option>:</Term>
 234 <ListItem>
 235 <Para>
 236 Dump a type signature for each value defined at the top level
 237 of the module.  The list is sorted alphabetically.
 238 Using <Option>-dppr-debug</Option> dumps a type signature for
 239 all the imported and system-defined things as well; useful
 240 for debugging the compiler.
 241 </Para>
 242 </ListItem>
 243 </VarListEntry>
 244
 245 <VarListEntry>
 246 <Term><Option>-ddump-deriv</Option>:</Term>
 247 <ListItem>
 248 <Para>
 249 derived instances
 250 </Para>
 251 </ListItem>
 252 </VarListEntry>
 253 <VarListEntry>
 254 <Term><Option>-ddump-ds</Option>:</Term>
 255 <ListItem>
 256 <Para>
 257 desugarer output
 258 </Para>
 259 </ListItem>
 260 </VarListEntry>
 261 <VarListEntry>
 262 <Term><Option>-ddump-spec</Option>:</Term>
 263 <ListItem>
 264 <Para>
 265 output of specialisation pass
 266 </Para>
 267 </ListItem>
 268 </VarListEntry>
 269 <VarListEntry>
 270 <Term><Option>-ddump-rules</Option>:</Term>
 271 <ListItem>
 272 <Para>
 273 dumps all rewrite rules (including those generated by the specialisation pass)
 274 </Para>
 275 </ListItem>
 276 </VarListEntry>
 277 <VarListEntry>
 278 <Term><Option>-ddump-simpl</Option>:</Term>
 279 <ListItem>
 280 <Para>
 281 simplifer output (Core-to-Core passes)
 282 </Para>
 283 </ListItem>
 284 </VarListEntry>
 285 <VarListEntry>
 286 <Term><Option>-ddump-usagesp</Option>:</Term>
 287 <ListItem>
 288 <Para>
 289 UsageSP inference pre-inf and output
 290 </Para>
 291 </ListItem>
 292 </VarListEntry>
 293 <VarListEntry>
 294 <Term><Option>-ddump-cpranal</Option>:</Term>
 295 <ListItem>
 296 <Para>
 297 CPR analyser output
 298 </Para>
 299 </ListItem>
 300 </VarListEntry>
 301 <VarListEntry>
 302 <Term><Option>-ddump-stranal</Option>:</Term>
 303 <ListItem>
 304 <Para>
 305 strictness analyser output
 306 </Para>
 307 </ListItem>
 308 </VarListEntry>
 309 <VarListEntry>
 310 <Term><Option>-ddump-workwrap</Option>:</Term>
 311 <ListItem>
 312 <Para>
 313 worker/wrapper split output
 314 </Para>
 315 </ListItem>
 316 </VarListEntry>
 317 <VarListEntry>
 318 <Term><Option>-ddump-occur-anal</Option>:</Term>
 319 <ListItem>
 320 <Para>
 321 `occurrence analysis' output
 322 </Para>
 323 </ListItem>
 324 </VarListEntry>
 325 <VarListEntry>
 326 <Term><Option>-ddump-stg</Option>:</Term>
 327 <ListItem>
 328 <Para>
 329 output of STG-to-STG passes
 330 </Para>
 331 </ListItem>
 332 </VarListEntry>
 333 <VarListEntry>
 334 <Term><Option>-ddump-absC</Option>:</Term>
 335 <ListItem>
 336 <Para>
 337 <Emphasis>un</Emphasis>flattened Abstract&nbsp;C
 338 </Para>
 339 </ListItem>
 340 </VarListEntry>
 341 <VarListEntry>
 342 <Term><Option>-ddump-flatC</Option>:</Term>
 343 <ListItem>
 344 <Para>
 345 <Emphasis>flattened</Emphasis> Abstract&nbsp;C
 346 </Para>
 347 </ListItem>
 348 </VarListEntry>
 349 <VarListEntry>
 350 <Term><Option>-ddump-realC</Option>:</Term>
 351 <ListItem>
 352 <Para>
 353 same as what goes to the C compiler
 354 </Para>
 355 </ListItem>
 356 </VarListEntry>
 357 <VarListEntry>
 358 <Term><Option>-ddump-asm</Option>:</Term>
 359 <ListItem>
 360 <Para>
 361 assembly language from the native-code generator
 362 </Para>
 363 </ListItem>
 364 </VarListEntry>
 365 </VariableList>
 366 <IndexTerm><Primary>-ddump-all option</Primary></IndexTerm>
 367 <IndexTerm><Primary>-ddump-most option</Primary></IndexTerm>
 368 <IndexTerm><Primary>-ddump-parsed option</Primary></IndexTerm>
 369 <IndexTerm><Primary>-ddump-rn option</Primary></IndexTerm>
 370 <IndexTerm><Primary>-ddump-tc option</Primary></IndexTerm>
 371 <IndexTerm><Primary>-ddump-deriv option</Primary></IndexTerm>
 372 <IndexTerm><Primary>-ddump-ds option</Primary></IndexTerm>
 373 <IndexTerm><Primary>-ddump-simpl option</Primary></IndexTerm>
 374 <IndexTerm><Primary>-ddump-cpranal option</Primary></IndexTerm>
 375 <IndexTerm><Primary>-ddump-workwrap option</Primary></IndexTerm>
 376 <IndexTerm><Primary>-ddump-rules option</Primary></IndexTerm>
 377 <IndexTerm><Primary>-ddump-usagesp option</Primary></IndexTerm>
 378 <IndexTerm><Primary>-ddump-stranal option</Primary></IndexTerm>
 379 <IndexTerm><Primary>-ddump-occur-anal option</Primary></IndexTerm>
 380 <IndexTerm><Primary>-ddump-spec option</Primary></IndexTerm>
 381 <IndexTerm><Primary>-ddump-stg option</Primary></IndexTerm>
 382 <IndexTerm><Primary>-ddump-absC option</Primary></IndexTerm>
 383 <IndexTerm><Primary>-ddump-flatC option</Primary></IndexTerm>
 384 <IndexTerm><Primary>-ddump-realC option</Primary></IndexTerm>
 385 <IndexTerm><Primary>-ddump-asm option</Primary></IndexTerm>
 386 </Para>
 387 </ListItem>
 388 </VarListEntry>
 389 <VarListEntry>
 390 <Term><Option>-dverbose-simpl</Option> and <Option>-dverbose-stg</Option>:</Term>
 391 <ListItem>
 392 <Para>
 393 <IndexTerm><Primary>-dverbose-simpl option</Primary></IndexTerm>
 394 <IndexTerm><Primary>-dverbose-stg option</Primary></IndexTerm>
 395 Show the output of the intermediate Core-to-Core and STG-to-STG
 396 passes, respectively.  (<Emphasis>Lots</Emphasis> of output!) So: when we're
 397 really desperate:
 398
 399 <Screen>
 400 % ghc -noC -O -ddump-simpl -dverbose-simpl -dcore-lint Foo.hs
 401 </Screen>
 402
 403 </Para>
 404 </ListItem>
 405 </VarListEntry>
 406 <VarListEntry>
 407 <Term><Option>-ddump-simpl-iterations</Option>:</Term>
 408 <ListItem>
 409 <Para>
 410 <IndexTerm><Primary>-ddump-simpl-iterations option</Primary></IndexTerm>
 411 Show the output of each <Emphasis>iteration</Emphasis> of the simplifier (each run of
 412 the simplifier has a maximum number of iterations, normally 4).  Used
 413 when even <Option>-dverbose-simpl</Option> doesn't cut it.
 414 </Para>
 415 </ListItem>
 416 </VarListEntry>
 417 <VarListEntry>
 418 <Term><Option>-dppr-&lcub;user,debug</Option>&rcub;:</Term>
 419 <ListItem>
 420 <Para>
 421 <IndexTerm><Primary>-dppr-user option</Primary></IndexTerm>
 422 <IndexTerm><Primary>-dppr-debug option</Primary></IndexTerm>
 423 Debugging output is in one of several &ldquo;styles.&rdquo;  Take the printing
 424 of types, for example.  In the &ldquo;user&rdquo; style, the compiler's internal
 425 ideas about types are presented in Haskell source-level syntax,
 426 insofar as possible.  In the &ldquo;debug&rdquo; style (which is the default for
 427 debugging output), the types are printed in with
 428 explicit foralls, and variables have their unique-id attached (so you
 429 can check for things that look the same but aren't).
 430 </Para>
 431 </ListItem>
 432 </VarListEntry>
 433 <VarListEntry>
 434 <Term><Option>-ddump-simpl-stats</Option>:</Term>
 435 <ListItem>
 436 <Para>
 437 <IndexTerm><Primary>-ddump-simpl-stats option</Primary></IndexTerm>
 438 Dump statistics about how many of each kind
 439 of transformation too place.  If you add <Option>-dppr-debug</Option> you get more detailed information.
 440 </Para>
 441 </ListItem>
 442 </VarListEntry>
 443 <VarListEntry>
 444 <Term><Option>-ddump-raw-asm</Option>:</Term>
 445 <ListItem>
 446 <Para>
 447 <IndexTerm><Primary>-ddump-raw-asm option</Primary></IndexTerm>
 448 Dump out the assembly-language stuff, before the &ldquo;mangler&rdquo; gets it.
 449 </Para>
 450 </ListItem>
 451 </VarListEntry>
 452 <VarListEntry>
 453 <Term><Option>-ddump-rn-trace</Option>:</Term>
 454 <ListItem>
 455 <Para>
 456 <IndexTerm><Primary>-ddump-rn-trace</Primary></IndexTerm>
 457 Make the renamer be *real* chatty about what it is upto.
 458 </Para>
 459 </ListItem>
 460 </VarListEntry>
 461 <VarListEntry>
 462 <Term><Option>-dshow-rn-stats</Option>:</Term>
 463 <ListItem>
 464 <Para>
 465 <IndexTerm><Primary>-dshow-rn-stats</Primary></IndexTerm>
 466 Print out summary of what kind of information the renamer had to bring
 467 in.
 468 </Para>
 469 </ListItem>
 470 </VarListEntry>
 471 <VarListEntry>
 472 <Term><Option>-dshow-unused-imports</Option>:</Term>
 473 <ListItem>
 474 <Para>
 475 <IndexTerm><Primary>-dshow-unused-imports</Primary></IndexTerm>
 476 Have the renamer report what imports does not contribute.
 477 </Para>
 478 </ListItem>
 479 </VarListEntry>
 480 </VariableList>
 481 </Para>
 482
 483 </Sect2>
 484
 485 <Sect2 id="checking-consistency">
 486 <Title>Checking for consistency
 487 </Title>
 488
 489 <Para>
 490 <IndexTerm><Primary>consistency checks</Primary></IndexTerm>
 491 <IndexTerm><Primary>lint</Primary></IndexTerm>
 492 </Para>
 493
 494 <Para>
 495 <VariableList>
 496
 497 <VarListEntry>
 498 <Term><Option>-dcore-lint</Option>:</Term>
 499 <ListItem>
 500 <Para>
 501 <IndexTerm><Primary>-dcore-lint option</Primary></IndexTerm>
 502 Turn on heavyweight intra-pass sanity-checking within GHC, at Core
 503 level.  (It checks GHC's sanity, not yours.)
 504 </Para>
 505 </ListItem>
 506 </VarListEntry>
 507 <VarListEntry>
 508 <Term><Option>-dstg-lint</Option>:</Term>
 509 <ListItem>
 510 <Para>
 511 <IndexTerm><Primary>-dstg-lint option</Primary></IndexTerm>
 512 Ditto for STG level.
 513 </Para>
 514 </ListItem>
 515 </VarListEntry>
 516 <VarListEntry>
 517 <Term><Option>-dusagesp-lint</Option>:</Term>
 518 <ListItem>
 519 <Para>
 520 <IndexTerm><Primary>-dstg-lint option</Primary></IndexTerm>
 521 Turn on checks around UsageSP inference (<Option>-fusagesp</Option>).  This verifies
 522 various simple properties of the results of the inference, and also
 523 warns if any identifier with a used-once annotation before the
 524 inference has a used-many annotation afterwards; this could indicate a
 525 non-worksafe transformation is being applied.
 526 </Para>
 527 </ListItem>
 528 </VarListEntry>
 529 </VariableList>
 530 </Para>
 531
 532 </Sect2>
 533
 534 <Sect2>
 535 <Title>How to read Core syntax (from some <Option>-ddump-*</Option> flags)</Title>
 536
 537 <Para>
 538 <IndexTerm><Primary>reading Core syntax</Primary></IndexTerm>
 539 <IndexTerm><Primary>Core syntax, how to read</Primary></IndexTerm>
 540 </Para>
 541
 542 <Para>
 543 Let's do this by commenting an example.  It's from doing
 544 <Option>-ddump-ds</Option> on this code:
 545
 546 <ProgramListing>
 547 skip2 m = m : skip2 (m+2)
 548 </ProgramListing>
 549
 550 </Para>
 551
 552 <Para>
 553 Before we jump in, a word about names of things.  Within GHC,
 554 variables, type constructors, etc., are identified by their
 555 &ldquo;Uniques.&rdquo;  These are of the form `letter' plus `number' (both
 556 loosely interpreted).  The `letter' gives some idea of where the
 557 Unique came from; e.g., <Literal>&lowbar;</Literal> means &ldquo;built-in type variable&rdquo;;
 558 <Literal>t</Literal> means &ldquo;from the typechecker&rdquo;; <Literal>s</Literal> means &ldquo;from the
 559 simplifier&rdquo;; and so on.  The `number' is printed fairly compactly in
 560 a `base-62' format, which everyone hates except me (WDP).
 561 </Para>
 562
 563 <Para>
 564 Remember, everything has a &ldquo;Unique&rdquo; and it is usually printed out
 565 when debugging, in some form or another.  So here we go&hellip;
 566 </Para>
 567
 568 <Para>
 569 <ProgramListing>
 570 Desugared:
 571 Main.skip2{-r1L6-} :: _forall_ a$_4 =&#62;{{Num a$_4}} -&#62; a$_4 -&#62; [a$_4]
 572
 573 --# `r1L6' is the Unique for Main.skip2;
 574 --# `_4' is the Unique for the type-variable (template) `a'
 575 --# `{{Num a$_4}}' is a dictionary argument
 576
 577 _NI_
 578
 579 --# `_NI_' means "no (pragmatic) information" yet; it will later
 580 --# evolve into the GHC_PRAGMA info that goes into interface files.
 581
 582 Main.skip2{-r1L6-} =
 583     /\ _4 -&#62; \ d.Num.t4Gt -&#62;
 584         let {
 585           {- CoRec -}
 586           +.t4Hg :: _4 -&#62; _4 -&#62; _4
 587           _NI_
 588           +.t4Hg = (+{-r3JH-} _4) d.Num.t4Gt
 589
 590           fromInt.t4GS :: Int{-2i-} -&#62; _4
 591           _NI_
 592           fromInt.t4GS = (fromInt{-r3JX-} _4) d.Num.t4Gt
 593
 594 --# The `+' class method (Unique: r3JH) selects the addition code
 595 --# from a `Num' dictionary (now an explicit lamba'd argument).
 596 --# Because Core is 2nd-order lambda-calculus, type applications
 597 --# and lambdas (/\) are explicit.  So `+' is first applied to a
 598 --# type (`_4'), then to a dictionary, yielding the actual addition
 599 --# function that we will use subsequently...
 600
 601 --# We play the exact same game with the (non-standard) class method
 602 --# `fromInt'.  Unsurprisingly, the type `Int' is wired into the
 603 --# compiler.
 604
 605           lit.t4Hb :: _4
 606           _NI_
 607           lit.t4Hb =
 608               let {
 609                 ds.d4Qz :: Int{-2i-}
 610                 _NI_
 611                 ds.d4Qz = I#! 2#
 612               } in  fromInt.t4GS ds.d4Qz
 613
 614 --# `I# 2#' is just the literal Int `2'; it reflects the fact that
 615 --# GHC defines `data Int = I# Int#', where Int# is the primitive
 616 --# unboxed type.  (see relevant info about unboxed types elsewhere...)
 617
 618 --# The `!' after `I#' indicates that this is a *saturated*
 619 --# application of the `I#' data constructor (i.e., not partially
 620 --# applied).
 621
 622           skip2.t3Ja :: _4 -&#62; [_4]
 623           _NI_
 624           skip2.t3Ja =
 625               \ m.r1H4 -&#62;
 626                   let { ds.d4QQ :: [_4]
 627                         _NI_
 628                         ds.d4QQ =
 629                     let {
 630                       ds.d4QY :: _4
 631                       _NI_
 632                       ds.d4QY = +.t4Hg m.r1H4 lit.t4Hb
 633                     } in  skip2.t3Ja ds.d4QY
 634                   } in
 635                   :! _4 m.r1H4 ds.d4QQ
 636
 637           {- end CoRec -}
 638         } in  skip2.t3Ja
 639 </ProgramListing>
 640 </Para>
 641
 642 <Para>
 643 (&ldquo;It's just a simple functional language&rdquo; is an unregisterised
 644 trademark of Peyton Jones Enterprises, plc.)
 645 </Para>
 646
 647 </Sect2>
 648
 649 <Sect2 id="source-file-options">
 650 <Title>Command line options in source files
 651 </Title>
 652
 653 <Para>
 654 <IndexTerm><Primary>source-file options</Primary></IndexTerm>
 655 </Para>
 656
 657 <Para>
 658 Sometimes it is useful to make the connection between a source file
 659 and the command-line options it requires quite tight. For instance,
 660 if a (Glasgow) Haskell source file uses <Literal>casm</Literal>s, the C back-end
 661 often needs to be told about which header files to include. Rather than
 662 maintaining the list of files the source depends on in a
 663 <Filename>Makefile</Filename> (using the <Option>-&num;include</Option> command-line option), it is
 664 possible to do this directly in the source file using the <Literal>OPTIONS</Literal>
 665 pragma <IndexTerm><Primary>OPTIONS pragma</Primary></IndexTerm>:
 666 </Para>
 667
 668 <Para>
 669 <ProgramListing>
 670 {-# OPTIONS -#include "foo.h" #-}
 671 module X where
 672
 673 ...
 674 </ProgramListing>
 675 </Para>
 676
 677 <Para>
 678 <Literal>OPTIONS</Literal> pragmas are only looked for at the top of your source
 679 files, upto the first (non-literate,non-empty) line not containing
 680 <Literal>OPTIONS</Literal>. Multiple <Literal>OPTIONS</Literal> pragmas are recognised. Note
 681 that your command shell does not get to the source file options, they
 682 are just included literally in the array of command-line arguments
 683 the compiler driver maintains internally, so you'll be desperately
 684 disappointed if you try to glob etc. inside <Literal>OPTIONS</Literal>.
 685 </Para>
 686
 687 <Para>
 688 NOTE: the contents of OPTIONS are prepended to the command-line
 689 options, so you <Emphasis>do</Emphasis> have the ability to override OPTIONS settings
 690 via the command line.
 691 </Para>
 692
 693 <Para>
 694 It is not recommended to move all the contents of your Makefiles into
 695 your source files, but in some circumstances, the <Literal>OPTIONS</Literal> pragma
 696 is the Right Thing. (If you use <Option>-keep-hc-file-too</Option> and have OPTION
 697 flags in your module, the OPTIONS will get put into the generated .hc
 698 file).
 699 </Para>
 700
 701 </Sect2>
 702
 703   <sect2 id="unreg">
 704     <title>Unregisterised compilation</title>
 705     <indexterm><primary>unregisterised compilation</primary></indexterm>
 706
 707     <para>The term "unregisterised" really means "compile via vanilla
 708     C", disabling some of the platform-specific tricks that GHC
 709     normally uses to make programs go faster.  When compiling
 710     unregisterised, GHC simply generates a C file which is compiled
 711     via gcc.</para>
 712
 713     <para>Unregisterised compilation can be useful when porting GHC to
 714     a new machine, since it reduces the prerequisite tools to
 715     <command>gcc</command>, <command>as</command>, and
 716     <command>ld</command> and nothing more, and furthermore the amount
 717     of platform-specific code that needs to be written in order to get
 718     unregisterised compilation going is usually fairly small.</para>
 719
 720     <variablelist>
 721       <varlistentry>
 722         <term><option>-unreg</option>:</term>
 723         <indexterm><primary><option>-unreg</option></primary></indexterm>
 724         <listitem>
 725           <para>Compile via vanilla ANSI C only, turning off
 726           platform-specific optimisations.  NOTE: in order to use
 727           <option>-unreg</option>, you need to have a set of libraries
 728           (including the RTS) built for unregisterised compilation.
 729           This amounts to building GHC with way "u" enabled.</para>
 730         </listitem>
 731       </varlistentry>
 732     </variablelist>
 733   </sect2>
 734
 735 </Sect1>
 736
 737 <!-- Emacs stuff:
 738      ;;; Local Variables: ***
 739      ;;; mode: sgml ***
 740      ;;; sgml-parent-document: ("users_guide.sgml" "book" "chapter" "sect1") ***
 741      ;;; End: ***
 742  -->