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