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