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