ghc/docs/users_guide/using.sgml

   1 <Chapter id="using-GHC">
   2 <Title>Using GHC
   3 </Title>
   4
   5 <Para>
   6 <IndexTerm><Primary>GHC, using</Primary></IndexTerm>
   7 <IndexTerm><Primary>using GHC</Primary></IndexTerm>
   8 </Para>
   9
  10 <Para>
  11 GHC is a command-line compiler: in order to compile a Haskell program,
  12 GHC must be invoked on the source file(s) by typing a command to the
  13 shell.  The steps involved in compiling a program can be automated
  14 using the <Literal>make</Literal> tool (this is especially useful if the program
  15 consists of multiple source files which depend on each other).  This
  16 section describes how to use GHC from the command-line.
  17 </Para>
  18
  19 <Sect1 id="command-line-structure">
  20 <Title>Overall command-line structure
  21 </Title>
  22
  23 <Para>
  24 <IndexTerm><Primary>structure, command-line</Primary></IndexTerm>
  25 <IndexTerm><Primary>command-line structure</Primary></IndexTerm>
  26 </Para>
  27
  28 <Para>
  29 An invocation of GHC takes the following form:
  30 </Para>
  31
  32 <Para>
  33
  34 <Screen>
  35 ghc [argument...]
  36 </Screen>
  37
  38 </Para>
  39
  40 <Para>
  41 Command-line arguments are either options or file names.
  42 </Para>
  43
  44 <Para>
  45 Command-line options begin with <Literal>-</Literal>.  They may <Emphasis>not</Emphasis> be
  46 grouped: <Literal>-vO</Literal> is different from <Literal>-v -O</Literal>.  Options need not
  47 precede filenames: e.g., <Literal>ghc *.o -o foo</Literal>.  All options are
  48 processed and then applied to all files; you cannot, for example, invoke
  49 <Literal>ghc -c -O1 Foo.hs -O2 Bar.hs</Literal> to apply different optimisation
  50 levels to the files <Literal>Foo.hs</Literal> and <Literal>Bar.hs</Literal>.  For conflicting
  51 options, e.g., <Literal>-c -S</Literal>, we reserve the right to do anything we
  52 want.  (Usually, the last one applies.)
  53 </Para>
  54
  55 </Sect1>
  56
  57 <Sect1 id="file-suffixes">
  58 <Title>Meaningful file suffixes
  59 </Title>
  60
  61 <Para>
  62 <IndexTerm><Primary>suffixes, file</Primary></IndexTerm>
  63 <IndexTerm><Primary>file suffixes for GHC</Primary></IndexTerm>
  64 </Para>
  65
  66 <Para>
  67 File names with ``meaningful'' suffixes (e.g., <Literal>.lhs</Literal> or <Literal>.o</Literal>)
  68 cause the ``right thing'' to happen to those files.
  69 </Para>
  70
  71 <Para>
  72 <VariableList>
  73
  74 <VarListEntry>
  75 <Term><Literal>.lhs</Literal>:</Term>
  76 <ListItem>
  77 <Para>
  78 <IndexTerm><Primary>lhs suffix</Primary></IndexTerm>
  79 A ``literate Haskell'' module.
  80 </Para>
  81 </ListItem>
  82 </VarListEntry>
  83 <VarListEntry>
  84 <Term><Literal>.hs</Literal>:</Term>
  85 <ListItem>
  86 <Para>
  87 A not-so-literate Haskell module.
  88 </Para>
  89 </ListItem>
  90 </VarListEntry>
  91 <VarListEntry>
  92 <Term><Literal>.hi</Literal>:</Term>
  93 <ListItem>
  94 <Para>
  95 A Haskell interface file, probably compiler-generated.
  96 </Para>
  97 </ListItem>
  98 </VarListEntry>
  99 <VarListEntry>
 100 <Term><Literal>.hc</Literal>:</Term>
 101 <ListItem>
 102 <Para>
 103 Intermediate C file produced by the Haskell compiler.
 104 </Para>
 105 </ListItem>
 106 </VarListEntry>
 107 <VarListEntry>
 108 <Term><Literal>.c</Literal>:</Term>
 109 <ListItem>
 110 <Para>
 111 A C&nbsp;file not produced by the Haskell compiler.
 112 </Para>
 113 </ListItem>
 114 </VarListEntry>
 115 <VarListEntry>
 116 <Term><Literal>.s</Literal>:</Term>
 117 <ListItem>
 118 <Para>
 119 An assembly-language source file, usually
 120 produced by the compiler.
 121 </Para>
 122 </ListItem>
 123 </VarListEntry>
 124 <VarListEntry>
 125 <Term><Literal>.o</Literal>:</Term>
 126 <ListItem>
 127 <Para>
 128 An object file, produced by an assembler.
 129 </Para>
 130 </ListItem>
 131 </VarListEntry>
 132 </VariableList>
 133 </Para>
 134
 135 <Para>
 136 Files with other suffixes (or without suffixes) are passed straight
 137 to the linker.
 138 </Para>
 139
 140 </Sect1>
 141
 142 <Sect1 id="options-help">
 143 <Title>Help and verbosity options
 144 </Title>
 145
 146 <Para>
 147 <IndexTerm><Primary>help options (GHC)</Primary></IndexTerm>
 148 <IndexTerm><Primary>verbose option (GHC)</Primary></IndexTerm>
 149 </Para>
 150
 151 <Para>
 152 A good option to start with is the <Literal>-help</Literal> (or <Literal>-?</Literal>) option.
 153 <IndexTerm><Primary>-help option</Primary></IndexTerm>
 154 <IndexTerm><Primary>-? option</Primary></IndexTerm>
 155 GHC spews a long message to standard output and then exits.
 156 </Para>
 157
 158 <Para>
 159 The <Literal>-v</Literal><IndexTerm><Primary>-v option</Primary></IndexTerm> option makes GHC <Emphasis>verbose</Emphasis>: it
 160 reports its version number and shows (on stderr) exactly how it invokes each
 161 phase of the compilation system.  Moreover, it passes
 162 the <Literal>-v</Literal> flag to most phases; each reports
 163 its version number (and possibly some other information).
 164 </Para>
 165
 166 <Para>
 167 Please, oh please, use the <Literal>-v</Literal> option when reporting bugs!
 168 Knowing that you ran the right bits in the right order is always the
 169 first thing we want to verify.
 170 </Para>
 171
 172 <Para>
 173 If you're just interested in the compiler version number, the
 174 <Literal>--version</Literal><IndexTerm><Primary>--version option</Primary></IndexTerm> option prints out a
 175 one-line string containing the requested info.
 176 </Para>
 177
 178 </Sect1>
 179
 180 <Sect1 id="options-order">
 181 <Title>Running the right phases in the right order
 182 </Title>
 183
 184 <Para>
 185 <IndexTerm><Primary>order of passes in GHC</Primary></IndexTerm>
 186 <IndexTerm><Primary>pass ordering in GHC</Primary></IndexTerm>
 187 The basic task of the <Literal>ghc</Literal> driver is to run each input file
 188 through the right phases (compiling, linking, etc.).
 189 </Para>
 190
 191 <Para>
 192 The first phase to run is determined by the input-file suffix, and the
 193 last phase is determined by a flag.  If no relevant flag is present,
 194 then go all the way through linking.  This table summarises:
 195 </Para>
 196
 197 <Para>
 198 <InformalTable>
 199 <TGroup Cols="4">
 200 <ColSpec Align="Left">
 201 <ColSpec Align="Left">
 202 <ColSpec Align="Left">
 203 <ColSpec Align="Left">
 204 <TBody>
 205
 206 <Row>
 207 <Entry>Phase of the compilation system</Entry>
 208 <Entry>Suffix saying ``start here''</Entry>
 209 <Entry>Flag saying ``stop after''</Entry>
 210 <Entry>(suffix of) output file</Entry>
 211 </Row>
 212
 213 <Row>
 214 <Entry>
 215 literate pre-processor </Entry>
 216 <Entry> .lhs </Entry>
 217 <Entry> - </Entry>
 218 <Entry> - </Entry>
 219 </Row>
 220 <Row>
 221 <Entry>
 222 C pre-processor (opt.) </Entry>
 223 <Entry> - </Entry>
 224 <Entry> - </Entry>
 225 <Entry> - </Entry>
 226 </Row>
 227 <Row>
 228 <Entry>
 229 Haskell compiler </Entry>
 230 <Entry> .hs </Entry>
 231 <Entry> -C, -S </Entry>
 232 <Entry> .hc, .s </Entry>
 233 </Row>
 234 <Row>
 235 <Entry>
 236 C compiler (opt.) </Entry>
 237 <Entry> .hc or .c </Entry>
 238 <Entry> -S </Entry>
 239 <Entry> .s </Entry>
 240 </Row>
 241 <Row>
 242 <Entry>
 243 assembler </Entry>
 244 <Entry> .s </Entry>
 245 <Entry> -c </Entry>
 246 <Entry> .o </Entry>
 247 </Row>
 248 <Row>
 249 <Entry>
 250 linker </Entry>
 251 <Entry> other </Entry>
 252 <Entry> - </Entry>
 253 <Entry> a.out </Entry>
 254 </Row>
 255 </TBody>
 256 </TGroup>
 257 </InformalTable>
 258
 259 <IndexTerm><Primary>-C option</Primary></IndexTerm>
 260 <IndexTerm><Primary>-S option</Primary></IndexTerm>
 261 <IndexTerm><Primary>-c option</Primary></IndexTerm>
 262 </Para>
 263
 264 <Para>
 265 Thus, a common invocation would be: <Literal>ghc -c Foo.hs</Literal>
 266 </Para>
 267
 268 <Para>
 269 Note: What the Haskell compiler proper produces depends on whether a
 270 native-code generator is used (producing assembly language) or not
 271 (producing C).
 272 </Para>
 273
 274 <Para>
 275 The option <Literal>-cpp</Literal><IndexTerm><Primary>-cpp option</Primary></IndexTerm> must be given for the C
 276 pre-processor phase to be run, that is, the pre-processor will be run
 277 over your Haskell source file before continuing.
 278 </Para>
 279
 280 <Para>
 281 The option <Literal>-E</Literal><IndexTerm><Primary>-E option</Primary></IndexTerm> runs just the pre-processing
 282 passes of the compiler, outputting the result on stdout before
 283 stopping. If used in conjunction with -cpp, the output is the
 284 code blocks of the original (literal) source after having put it
 285 through the grinder that is the C pre-processor. Sans <Literal>-cpp</Literal>, the
 286 output is the de-litted version of the original source.
 287 </Para>
 288
 289 <Para>
 290 The option <Literal>-optcpp-E</Literal><IndexTerm><Primary>-optcpp-E option</Primary></IndexTerm> runs just the
 291 pre-processing stage of the C-compiling phase, sending the result to
 292 stdout.  (For debugging or obfuscation contests, usually.)
 293 </Para>
 294
 295 </Sect1>
 296
 297 <Sect1 id="options-output">
 298 <Title>Re-directing the compilation output(s)
 299 </Title>
 300
 301 <Para>
 302 <IndexTerm><Primary>output-directing options</Primary></IndexTerm>
 303 </Para>
 304
 305 <Para>
 306 GHC's compiled output normally goes into a <Literal>.hc</Literal>, <Literal>.o</Literal>, etc., file,
 307 depending on the last-run compilation phase.  The option <Literal>-o
 308 foo</Literal><IndexTerm><Primary>-o option</Primary></IndexTerm> re-directs the output of that last-run
 309 phase to file <Literal>foo</Literal>.
 310 </Para>
 311
 312 <Para>
 313 Note: this ``feature'' can be counterintuitive:
 314 <Literal>ghc -C -o foo.o foo.hs</Literal> will put the intermediate C code in the
 315 file <Literal>foo.o</Literal>, name notwithstanding!
 316 </Para>
 317
 318 <Para>
 319 EXOTICA: But the <Literal>-o</Literal> option isn't of much use if you have
 320 <Emphasis>several</Emphasis> input files&hellip; Non-interface output files are
 321 normally put in the same directory as their corresponding input file
 322 came from.  You may specify that they be put in another directory
 323 using the <Literal>-odir &lt;dir&gt;</Literal><IndexTerm><Primary>-odir &lt;dir&gt; option</Primary></IndexTerm> (the
 324 ``Oh, dear'' option).  For example:
 325 </Para>
 326
 327 <Para>
 328
 329 <Screen>
 330 % ghc -c parse/Foo.hs parse/Bar.hs gurgle/Bumble.hs -odir `arch`
 331 </Screen>
 332
 333 </Para>
 334
 335 <Para>
 336 The output files, <Literal>Foo.o</Literal>, <Literal>Bar.o</Literal>, and <Literal>Bumble.o</Literal> would be
 337 put into a subdirectory named after the architecture of the executing
 338 machine (<Literal>sun4</Literal>, <Literal>mips</Literal>, etc).  The directory must already
 339 exist; it won't be created.
 340 </Para>
 341
 342 <Para>
 343 Note that the <Literal>-odir</Literal> option does <Emphasis>not</Emphasis> affect where the
 344 interface files are put.  In the above example, they would still be
 345 put in <Literal>parse/Foo.hi</Literal>, <Literal>parse/Bar.hi</Literal>, and <Literal>gurgle/Bumble.hi</Literal>.
 346 </Para>
 347
 348 <Para>
 349 MORE EXOTICA: The <Literal>-osuf &lt;suffix&gt;</Literal><IndexTerm><Primary>-osuf &lt;suffix&gt;
 350 option</Primary></IndexTerm> will change the <Literal>.o</Literal> file suffix for object files to
 351 whatever you specify.  (We use this in compiling the prelude.).
 352 Similarly, the <Literal>-hisuf &lt;suffix&gt;</Literal><IndexTerm><Primary>-hisuf &lt;suffix&gt;
 353 option</Primary></IndexTerm> will change the <Literal>.hi</Literal> file suffix for non-system
 354 interface files (see <XRef LinkEnd="hi-options">).
 355 </Para>
 356
 357 <Para>
 358 The <Literal>-hisuf</Literal>/<Literal>-osuf</Literal> game is useful if you want to compile a program
 359 with both GHC and HBC (say) in the same directory.  Let HBC use the
 360 standard <Literal>.hi</Literal>/<Literal>.o</Literal> suffixes; add <Literal>-hisuf g&lowbar;hi -osuf g&lowbar;o</Literal> to your
 361 <Literal>make</Literal> rule for GHC compiling&hellip;
 362 </Para>
 363
 364 <Para>
 365 FURTHER EXOTICA: If you are doing a normal <Literal>.hs</Literal>-to-<Literal>.o</Literal> compilation
 366 but would like to hang onto the intermediate <Literal>.hc</Literal> C file, just
 367 throw in a <Literal>-keep-hc-file-too</Literal> option<IndexTerm><Primary>-keep-hc-file-too option</Primary></IndexTerm>.
 368 If you would like to look at the assembler output, toss in a
 369 <Literal>-keep-s-file-too</Literal>,<IndexTerm><Primary>-keep-s-file-too option</Primary></IndexTerm> too.
 370 </Para>
 371
 372 <Sect2 id="saving-ghc-stderr">
 373 <Title>Saving GHC's standard error output
 374 </Title>
 375
 376 <Para>
 377 <IndexTerm><Primary>standard error, saving</Primary></IndexTerm>
 378 </Para>
 379
 380 <Para>
 381 Sometimes, you may cause GHC to be rather chatty on standard error;
 382 with <Literal>-v</Literal>, for example.  You can instruct GHC to <Emphasis>append</Emphasis> this
 383 output to a particular log file with a <Literal>-odump &lt;blah&gt;</Literal><IndexTerm><Primary>-odump
 384 &lt;blah&gt; option</Primary></IndexTerm> option.
 385 </Para>
 386
 387 </Sect2>
 388
 389 <Sect2 id="temp-files">
 390 <Title>Redirecting temporary files
 391 </Title>
 392
 393 <Para>
 394 <IndexTerm><Primary>temporary files, redirecting</Primary></IndexTerm>
 395 </Para>
 396
 397 <Para>
 398 If you have trouble because of running out of space in <Literal>/tmp</Literal> (or
 399 wherever your installation thinks temporary files should go), you may
 400 use the <Literal>-tmpdir &lt;dir&gt;</Literal><IndexTerm><Primary>-tmpdir &lt;dir&gt; option</Primary></IndexTerm> option
 401 to specify an alternate directory.  For example, <Literal>-tmpdir .</Literal> says to
 402 put temporary files in the current working directory.
 403 </Para>
 404
 405 <Para>
 406 Alternatively, use your <Literal>TMPDIR</Literal> environment variable.<IndexTerm><Primary>TMPDIR
 407 environment variable</Primary></IndexTerm> Set it to the name of the directory where
 408 temporary files should be put.  GCC and other programs will honour the
 409 <Literal>TMPDIR</Literal> variable as well.
 410 </Para>
 411
 412 <Para>
 413 Even better idea: Set the <Literal>TMPDIR</Literal> variable when building GHC, and
 414 never worry about <Literal>TMPDIR</Literal> again. (see the build documentation).
 415 </Para>
 416
 417 </Sect2>
 418
 419 </Sect1>
 420
 421 <Sect1 id="options-sanity">
 422 <Title>Warnings and sanity-checking
 423 </Title>
 424
 425 <Para>
 426 <IndexTerm><Primary>sanity-checking options</Primary></IndexTerm>
 427 <IndexTerm><Primary>warnings</Primary></IndexTerm>
 428 GHC has a number of options that select which types of non-fatal error
 429 messages, otherwise known as warnings, can be generated during
 430 compilation.  By default, you get a standard set of warnings which are
 431 generally likely to indicate bugs in your program.  These are:
 432 <Literal>-fwarn-overlpapping-patterns</Literal>, <Literal>-fwarn-duplicate-exports</Literal>, and
 433 <Literal>-fwarn-missing-methods</Literal>.  The following flags are simple ways to
 434 select standard ``packages'' of warnings:
 435 </Para>
 436
 437 <Para>
 438 <VariableList>
 439
 440 <VarListEntry>
 441 <Term><Literal>-Wnot</Literal>:</Term>
 442 <ListItem>
 443 <Para>
 444 <IndexTerm><Primary>-Wnot option</Primary></IndexTerm>
 445 Turns off all warnings, including the standard ones.
 446 </Para>
 447 </ListItem>
 448 </VarListEntry>
 449
 450 <VarListEntry>
 451 <Term><Literal>-w</Literal>:</Term>
 452 <ListItem>
 453 <Para>
 454 <IndexTerm><Primary>-w option</Primary></IndexTerm>
 455 Synonym for <Literal>-Wnot</Literal>.
 456 </Para>
 457 </ListItem>
 458 </VarListEntry>
 459
 460 <VarListEntry>
 461 <Term><Literal>-W</Literal>:</Term>
 462 <ListItem>
 463 <Para>
 464 <IndexTerm><Primary>-W option</Primary></IndexTerm>
 465 Provides the standard warnings plus <Literal>-fwarn-incomplete-patterns</Literal>,
 466 <Literal>-fwarn-unused-imports</Literal> and <Literal>-fwarn-unused-binds</Literal>.
 467 </Para>
 468 </ListItem>
 469 </VarListEntry>
 470
 471 <VarListEntry>
 472 <Term><Literal>-Wall</Literal>:</Term>
 473 <ListItem>
 474 <Para>
 475 <IndexTerm><Primary>-Wall option</Primary></IndexTerm>
 476 Turns on all warning options.
 477 </Para>
 478 </ListItem>
 479 </VarListEntry>
 480
 481 </VariableList>
 482 </Para>
 483
 484 <Para>
 485 The full set of warning options is described below.  To turn off any
 486 warning, simply give the corresponding <Literal>-fno-warn-...</Literal> option on
 487 the command line.
 488 </Para>
 489
 490 <Para>
 491 <VariableList>
 492
 493 <VarListEntry>
 494 <Term><Literal>-fwarn-name-shadowing</Literal>:</Term>
 495 <ListItem>
 496 <Para>
 497 <IndexTerm><Primary>-fwarn-name-shadowing option</Primary></IndexTerm>
 498 <IndexTerm><Primary>shadowing, warning</Primary></IndexTerm>This option causes a warning to be emitted whenever an inner-scope
 499 value has the same name as an outer-scope value, i.e. the inner value
 500 shadows the outer one.  This can catch typographical errors that turn
 501 into hard-to-find bugs, e.g., in the inadvertent cyclic definition
 502 <Literal>let x = ... x ... in</Literal>.
 503 </Para>
 504
 505 <Para>
 506 Consequently, this option does <Emphasis>not</Emphasis> allow cyclic recursive
 507 definitions.
 508 </Para>
 509 </ListItem>
 510 </VarListEntry>
 511
 512 <VarListEntry>
 513 <Term><Literal>-fwarn-overlapping-patterns</Literal>:</Term>
 514 <ListItem>
 515 <Para>
 516 <IndexTerm><Primary>-fwarn-overlapping-patterns option</Primary></IndexTerm>
 517 <IndexTerm><Primary>overlapping patterns, warning</Primary></IndexTerm>
 518 <IndexTerm><Primary>patterns, overlapping</Primary></IndexTerm>
 519 By default, the compiler will warn you if a set of patterns are
 520 overlapping, i.e.,
 521 </Para>
 522
 523 <Para>
 524 <ProgramListing>
 525 f :: String -&#62; Int
 526 f []     = 0
 527 f (_:xs) = 1
 528 f "2"    = 2
 529 </ProgramListing>
 530 </Para>
 531
 532 <Para>
 533 where the last pattern match in <Literal>f</Literal> won't ever be reached, as the
 534 second pattern overlaps it. More often than not, redundant patterns
 535 is a programmer mistake/error, so this option is enabled by default.
 536 </Para>
 537 </ListItem>
 538 </VarListEntry>
 539
 540 <VarListEntry>
 541 <Term><Literal>-fwarn-incomplete-patterns</Literal>:</Term>
 542 <ListItem>
 543 <Para>
 544 <IndexTerm><Primary>-fwarn-incomplete-patterns option</Primary></IndexTerm>
 545 <IndexTerm><Primary>incomplete patterns, warning</Primary></IndexTerm>
 546 <IndexTerm><Primary>patterns, incomplete</Primary></IndexTerm>
 547 Similarly for incomplete patterns, the function <Literal>g</Literal> below will fail
 548 when applied to non-empty lists, so the compiler will emit a warning
 549 about this when <Literal>-fwarn-incomplete-patterns</Literal> is enabled.
 550 </Para>
 551
 552 <Para>
 553 <ProgramListing>
 554 g [] = 2
 555 </ProgramListing>
 556 </Para>
 557
 558 <Para>
 559 This option isn't enabled be default because it can be a bit noisy,
 560 and it doesn't always indicate a bug in the program.  However, it's
 561 generally considered good practice to cover all the cases in your
 562 functions.
 563 </Para>
 564 </ListItem>
 565 </VarListEntry>
 566
 567 <VarListEntry>
 568 <Term><Literal>-fwarn-missing-methods</Literal>:</Term>
 569 <ListItem>
 570 <Para>
 571 <IndexTerm><Primary>-fwarn-missing-methods option</Primary></IndexTerm>
 572 <IndexTerm><Primary>missing methods, warning</Primary></IndexTerm>
 573 <IndexTerm><Primary>methods, missing</Primary></IndexTerm>
 574 This option is on by default, and warns you whenever an instance
 575 declaration is missing one or more methods, and the corresponding
 576 class declaration has no default declaration for them.
 577 </Para>
 578 </ListItem>
 579 </VarListEntry>
 580
 581 <VarListEntry>
 582 <Term><Literal>-fwarn-missing-fields</Literal>:</Term>
 583 <ListItem>
 584 <Para>
 585 <IndexTerm><Primary>-fwarn-missing-fields option</Primary></IndexTerm>
 586 <IndexTerm><Primary>missing fields, warning</Primary></IndexTerm>
 587 <IndexTerm><Primary>fields, missing</Primary></IndexTerm>
 588 This option is on by default, and warns you whenever the construction
 589 of a labelled field constructor isn't complete, missing initializers
 590 for one or more fields. While not an error (the missing fields are
 591 initialised with bottoms), it is often an indication of a programmer
 592 error.
 593 </Para>
 594 </ListItem>
 595 </VarListEntry>
 596
 597 <VarListEntry>
 598 <Term><Literal>-fwarn-unused-imports</Literal>:</Term>
 599 <ListItem>
 600 <Para>
 601 <IndexTerm><Primary>-fwarn-unused-imports option</Primary></IndexTerm>
 602 <IndexTerm><Primary>unused imports, warning</Primary></IndexTerm>
 603 <IndexTerm><Primary>imports, unused</Primary></IndexTerm>
 604 Report any objects that are explicitly imported but never used.
 605 </Para>
 606 </ListItem>
 607 </VarListEntry>
 608
 609 <VarListEntry>
 610 <Term><Literal>-fwarn-unused-binds</Literal>:</Term>
 611 <ListItem>
 612 <Para>
 613 <IndexTerm><Primary>-fwarn-unused-binds option</Primary></IndexTerm>
 614 <IndexTerm><Primary>unused binds, warning</Primary></IndexTerm>
 615 <IndexTerm><Primary>binds, unused</Primary></IndexTerm>
 616 Report any function definitions (and local bindings) which are unused.
 617 For top-level functions, the warning is only given if the binding is
 618 not exported.
 619 </Para>
 620 </ListItem>
 621 </VarListEntry>
 622 <VarListEntry>
 623 <Term><Literal>-fwarn-unused-matches</Literal>:</Term>
 624 <ListItem>
 625 <Para>
 626 <IndexTerm><Primary>-fwarn-unused-matches option</Primary></IndexTerm>
 627 <IndexTerm><Primary>unused matches, warning</Primary></IndexTerm>
 628 <IndexTerm><Primary>matches, unused</Primary></IndexTerm>
 629 Report all unused variables which arise from pattern matches,
 630 including patterns consisting of a single variable.  For instance <Literal>f x
 631 y = []</Literal> would report <Literal>x</Literal> and <Literal>y</Literal> as unused.  To eliminate the warning,
 632 all unused variables can be replaced with wildcards.
 633 </Para>
 634 </ListItem>
 635 </VarListEntry>
 636
 637 <VarListEntry>
 638 <Term><Literal>-fwarn-duplicate-exports</Literal>:</Term>
 639 <ListItem>
 640 <Para>
 641 <IndexTerm><Primary>-fwarn-duplicate-exports option</Primary></IndexTerm>
 642 <IndexTerm><Primary>duplicate exports, warning</Primary></IndexTerm>
 643 <IndexTerm><Primary>export lists, duplicates</Primary></IndexTerm>
 644 Have the compiler warn about duplicate entries in export lists. This
 645 is useful information if you maintain large export lists, and want to
 646 avoid the continued export of a definition after you've deleted (one)
 647 mention of it in the export list.
 648 </Para>
 649
 650 <Para>
 651 This option is on by default.
 652 </Para>
 653 </ListItem>
 654 </VarListEntry>
 655
 656 <VarListEntry>
 657 <Term><Literal>-fwarn-type-defaults</Literal>:</Term>
 658 <ListItem>
 659 <Para>
 660 <IndexTerm><Primary>-fwarn-type-defaults option</Primary></IndexTerm>
 661 <IndexTerm><Primary>defaulting mechanism, warning</Primary></IndexTerm>
 662 Have the compiler warn/inform you where in your source the Haskell
 663 defaulting mechanism for numeric types kicks in. This is useful
 664 information when converting code from a context that assumed one
 665 default into one with another, e.g., the `default default' for Haskell
 666 1.4 caused the otherwise unconstrained value <Literal>1</Literal> to be given
 667 the type <Literal>Int</Literal>, whereas Haskell 98 defaults it to
 668 <Literal>Integer</Literal>.  This may lead to differences in performance and
 669 behaviour, hence the usefulness of being non-silent about this.
 670 </Para>
 671
 672 <Para>
 673 This warning is off by default.
 674 </Para>
 675 </ListItem>
 676 </VarListEntry>
 677
 678 <VarListEntry>
 679 <Term><Literal>-fwarn-missing-signatures</Literal>:</Term>
 680 <ListItem>
 681 <Para>
 682 <IndexTerm><Primary>-fwarn-missing-signatures option</Primary></IndexTerm>
 683 <IndexTerm><Primary>type signatures, missing</Primary></IndexTerm>
 684 If you would like GHC to check that every top-level function/value has
 685 a type signature, use the <Literal>-fwarn-missing-signatures</Literal> option.  This
 686 option is off by default.
 687 </Para>
 688 </ListItem>
 689 </VarListEntry>
 690 </VariableList>
 691 </Para>
 692
 693 <Para>
 694 If you're feeling really paranoid, the <Literal>-dcore-lint</Literal>
 695 option<IndexTerm><Primary>-dcore-lint option</Primary></IndexTerm> is a good choice.  It turns on
 696 heavyweight intra-pass sanity-checking within GHC.  (It checks GHC's
 697 sanity, not yours.)
 698 </Para>
 699
 700 </Sect1>
 701
 702 <Sect1 id="separate-compilation">
 703 <Title>Separate compilation
 704 </Title>
 705
 706 <Para>
 707 <IndexTerm><Primary>separate compilation</Primary></IndexTerm>
 708 <IndexTerm><Primary>recompilation checker</Primary></IndexTerm>
 709 <IndexTerm><Primary>make and recompilation</Primary></IndexTerm>
 710 </Para>
 711
 712 <Para>
 713 This section describes how GHC supports separate compilation.
 714 </Para>
 715
 716 <Sect2 id="hi-files">
 717 <Title>Interface files
 718 </Title>
 719
 720 <Para>
 721 <IndexTerm><Primary>interface files</Primary></IndexTerm>
 722 <IndexTerm><Primary>.hi files</Primary></IndexTerm>
 723 </Para>
 724
 725 <Para>
 726 When GHC compiles a source file <Literal>F</Literal> which contains a module <Literal>A</Literal>, say,
 727 it generates an object <Literal>F.o</Literal>, <Emphasis>and</Emphasis> a companion <Emphasis>interface
 728 file</Emphasis> <Literal>A.hi</Literal>.  The interface file is not intended for human
 729 consumption, as you'll see if you take a look at one.  It's merely
 730 there to help the compiler compile other modules in the same program.
 731 </Para>
 732
 733 <Para>
 734 NOTE: Having the name of the interface file follow the module name and
 735 not the file name, means that working with tools such as <Literal>make(1)</Literal>
 736 become harder. <Literal>make</Literal> implicitly assumes that any output files
 737 produced by processing a translation unit will have file names that
 738 can be derived from the file name of the translation unit.  For
 739 instance, pattern rules becomes unusable.  For this reason, we
 740 recommend you stick to using the same file name as the module name.
 741 </Para>
 742
 743 <Para>
 744 The interface file for <Literal>A</Literal> contains information needed by the compiler
 745 when it compiles any module <Literal>B</Literal> that imports <Literal>A</Literal>, whether directly or
 746 indirectly.  When compiling <Literal>B</Literal>, GHC will read <Literal>A.hi</Literal> to find the
 747 details that it needs to know about things defined in <Literal>A</Literal>.
 748 </Para>
 749
 750 <Para>
 751 Furthermore, when compiling module <Literal>C</Literal> which imports <Literal>B</Literal>, GHC may
 752 decide that it needs to know something about <Literal>A</Literal>&mdash;for example, <Literal>B</Literal>
 753 might export a function that involves a type defined in <Literal>A</Literal>.  In this
 754 case, GHC will go and read <Literal>A.hi</Literal> even though <Literal>C</Literal> does not explicitly
 755 import <Literal>A</Literal> at all.
 756 </Para>
 757
 758 <Para>
 759 The interface file may contain all sorts of things that aren't
 760 explicitly exported from <Literal>A</Literal> by the programmer.  For example, even
 761 though a data type is exported abstractly, <Literal>A.hi</Literal> will contain the
 762 full data type definition.  For small function definitions, <Literal>A.hi</Literal>
 763 will contain the complete definition of the function.  For bigger
 764 functions, <Literal>A.hi</Literal> will contain strictness information about the
 765 function.  And so on.  GHC puts much more information into <Literal>.hi</Literal> files
 766 when optimisation is turned on with the <Literal>-O</Literal> flag.  Without <Literal>-O</Literal> it
 767 puts in just the minimum; with <Literal>-O</Literal> it lobs in a whole pile of stuff.
 768 <IndexTerm><Primary>optimsation, effect on .hi files</Primary></IndexTerm>
 769 </Para>
 770
 771 <Para>
 772 <Literal>A.hi</Literal> should really be thought of as a compiler-readable version of
 773 <Literal>A.o</Literal>.  If you use a <Literal>.hi</Literal> file that wasn't generated by the same
 774 compilation run that generates the <Literal>.o</Literal> file the compiler may assume
 775 all sorts of incorrect things about <Literal>A</Literal>, resulting in core dumps and
 776 other unpleasant happenings.
 777 </Para>
 778
 779 </Sect2>
 780
 781 <Sect2 id="options-finding-imports">
 782 <Title>Finding interface files
 783 </Title>
 784
 785 <Para>
 786 <IndexTerm><Primary>interface files, finding them</Primary></IndexTerm>
 787 <IndexTerm><Primary>finding interface files</Primary></IndexTerm>
 788 </Para>
 789
 790 <Para>
 791 In your program, you import a module <Literal>Foo</Literal> by saying
 792 <Literal>import Foo</Literal>.  GHC goes looking for an interface file, <Literal>Foo.hi</Literal>.
 793 It has a builtin list of directories (notably including <Literal>.</Literal>) where
 794 it looks.
 795 </Para>
 796
 797 <Para>
 798 <VariableList>
 799
 800 <VarListEntry>
 801 <Term><Literal>-i&lt;dirs&gt;</Literal></Term>
 802 <ListItem>
 803 <Para>
 804 <IndexTerm><Primary>-i&lt;dirs&gt; option</Primary></IndexTerm>This flag
 805 prepends a colon-separated list of <Literal>dirs</Literal> to the ``import
 806 directories'' list.
 807 See also <XRef LinkEnd="recomp"> for the significance of using
 808 relative and absolute pathnames in the <Literal>-i</Literal> list.
 809 </Para>
 810 </ListItem>
 811 </VarListEntry>
 812
 813 <VarListEntry>
 814 <Term><Literal>-i</Literal></Term>
 815 <ListItem>
 816 <Para>
 817 resets the ``import directories'' list back to nothing.
 818 </Para>
 819 </ListItem>
 820 </VarListEntry>
 821
 822 <VarListEntry>
 823 <Term><Literal>-fno-implicit-prelude</Literal></Term>
 824 <ListItem>
 825 <Para>
 826 <IndexTerm><Primary>-fno-implicit-prelude option</Primary></IndexTerm>
 827 GHC normally imports <Literal>Prelude.hi</Literal> files for you.  If you'd rather it
 828 didn't, then give it a <Literal>-fno-implicit-prelude</Literal> option.  You are
 829 unlikely to get very far without a Prelude, but, hey, it's a free
 830 country.
 831 </Para>
 832 </ListItem>
 833 </VarListEntry>
 834
 835 <VarListEntry>
 836 <Term><Literal>-syslib &lt;lib&gt;</Literal></Term>
 837 <ListItem>
 838 <Para>
 839 <IndexTerm><Primary>-syslib &lt;lib&gt; option</Primary></IndexTerm>
 840 If you are using a system-supplied non-Prelude library (e.g., the
 841 POSIX library), just use a <Literal>-syslib posix</Literal> option (for example).  The
 842 right interface files should then be available.  <XRef LinkEnd="ghc-prelude"> lists the
 843 libraries available by this mechanism.
 844 </Para>
 845 </ListItem>
 846 </VarListEntry>
 847
 848 <VarListEntry>
 849 <Term><Literal>-I&lt;dir&gt;</Literal></Term>
 850 <ListItem>
 851 <Para>
 852 <IndexTerm><Primary>-I&lt;dir&gt; option</Primary></IndexTerm>
 853 Once a Haskell module has been compiled to C (<Literal>.hc</Literal> file), you may
 854 wish to specify where GHC tells the C compiler to look for <Literal>.h</Literal> files.
 855 (Or, if you are using the <Literal>-cpp</Literal> option<IndexTerm><Primary>-cpp option</Primary></IndexTerm>, where
 856 it tells the C pre-processor to look&hellip;)  For this purpose, use a <Literal>-I</Literal>
 857 option in the usual C-ish way.
 858 </Para>
 859 </ListItem>
 860 </VarListEntry>
 861
 862 </VariableList>
 863 </Para>
 864
 865 </Sect2>
 866
 867 <Sect2 id="hi-options">
 868 <Title>Other options related to interface files
 869 </Title>
 870
 871 <Para>
 872 <IndexTerm><Primary>interface files, options</Primary></IndexTerm>
 873 The interface output may be directed to another file
 874 <Literal>bar2/Wurble.iface</Literal> with the option <Literal>-ohi bar2/Wurble.iface</Literal><IndexTerm><Primary>-ohi
 875 &lt;file&gt; option</Primary></IndexTerm> (not recommended).
 876 </Para>
 877
 878 <Para>
 879 To avoid generating an interface file at all, use a <Literal>-nohi</Literal>
 880 option.<IndexTerm><Primary>-nohi option</Primary></IndexTerm>
 881 </Para>
 882
 883 <Para>
 884 The compiler does not overwrite an existing <Literal>.hi</Literal> interface file if
 885 the new one is byte-for-byte the same as the old one; this is friendly
 886 to <Literal>make</Literal>.  When an interface does change, it is often enlightening to
 887 be informed.  The <Literal>-hi-diffs</Literal><IndexTerm><Primary>-hi-diffs option</Primary></IndexTerm> option will
 888 make <Literal>ghc</Literal> run <Literal>diff</Literal> on the old and new <Literal>.hi</Literal> files. You can also
 889 record the difference in the interface file itself, the
 890 <Literal>-keep-hi-diffs</Literal><IndexTerm><Primary>-keep-hi-diffs</Primary></IndexTerm> option takes care of that.
 891 </Para>
 892
 893 <Para>
 894 The <Literal>.hi</Literal> files from GHC contain ``usage'' information which changes
 895 often and uninterestingly.  If you really want to see these changes
 896 reported, you need to use the
 897 <Literal>-hi-diffs-with-usages</Literal><IndexTerm><Primary>-hi-diffs-with-usages option</Primary></IndexTerm>
 898 option.
 899 </Para>
 900
 901 <Para>
 902 Interface files are normally jammed full of compiler-produced
 903 <Emphasis>pragmas</Emphasis>, which record arities, strictness info, etc.  If you
 904 think these pragmas are messing you up (or you are doing some kind of
 905 weird experiment), you can tell GHC to ignore them with the
 906 <Literal>-fignore-interface-pragmas</Literal><IndexTerm><Primary>-fignore-interface-pragmas
 907 option</Primary></IndexTerm> option.
 908 </Para>
 909
 910 <Para>
 911 When compiling without optimisations on, the compiler is extra-careful
 912 about not slurping in data constructors and instance declarations that
 913 it will not need. If you believe it is getting it wrong and not
 914 importing stuff which you think it should, this optimisation can be
 915 turned off with <Literal>-fno-prune-tydecls</Literal> and <Literal>-fno-prune-instdecls</Literal>.
 916 <IndexTerm><Primary>-fno-prune-tydecls option</Primary></IndexTerm><IndexTerm><Primary>-fno-prune-instdecls
 917 option</Primary></IndexTerm>
 918 </Para>
 919
 920 <Para>
 921 See also <XRef LinkEnd="options-linker">, which describes how the linker finds standard
 922 Haskell libraries.
 923 </Para>
 924
 925 </Sect2>
 926
 927 <Sect2 id="recomp">
 928 <Title>The recompilation checker
 929 </Title>
 930
 931 <Para>
 932 <IndexTerm><Primary>recompilation checker</Primary></IndexTerm>
 933 </Para>
 934
 935 <Para>
 936 In the olden days, GHC compared the newly-generated <Literal>.hi</Literal> file with
 937 the previous version; if they were identical, it left the old one
 938 alone and didn't change its modification date.  In consequence,
 939 importers of a module with an unchanged output <Literal>.hi</Literal> file were not
 940 recompiled.
 941 </Para>
 942
 943 <Para>
 944 This doesn't work any more.  In our earlier example, module <Literal>C</Literal> does
 945 not import module <Literal>A</Literal> directly, yet changes to <Literal>A.hi</Literal> should force a
 946 recompilation of <Literal>C</Literal>.  And some changes to <Literal>A</Literal> (changing the
 947 definition of a function that appears in an inlining of a function
 948 exported by <Literal>B</Literal>, say) may conceivably not change <Literal>B.hi</Literal> one jot.  So
 949 now&hellip;
 950 </Para>
 951
 952 <Para>
 953 GHC keeps a version number on each interface file, and on each type
 954 signature within the interface file.  It also keeps in every interface
 955 file a list of the version numbers of everything it used when it last
 956 compiled the file.  If the source file's modification date is earlier
 957 than the <Literal>.o</Literal> file's date (i.e. the source hasn't changed since the
 958 file was last compiled), GHC will be clever.  It compares the version
 959 numbers on the things it needs this time with the version numbers on
 960 the things it needed last time (gleaned from the interface file of the
 961 module being compiled); if they are all the same it stops compiling
 962 rather early in the process saying ``Compilation IS NOT required''.
 963 What a beautiful sight!
 964 </Para>
 965
 966 <Para>
 967 GHC <Emphasis>only</Emphasis> keeps detailed dependency information for ``user'' modules,
 968 not for ``library'' modules.  It distinguishes the two by a hack: a module
 969 whose <Literal>.hi</Literal> file has an absolute path name is considered a library module,
 970 while a relative path name indicates a user module.  So if you have a
 971 multi-directory application, use <Emphasis>relative</Emphasis> path names in your
 972 <Literal>-i</Literal> path, to force GHC to record detailed dependency information.
 973 Use absolute path names only for directories containing slowly-changing
 974 library modules.
 975 </Para>
 976
 977 <Para>
 978 A path is considered ``absolute'' if it starts with ``<Literal>/</Literal>'', or
 979 ``<Literal>A:/</Literal>'', or ``<Literal>A:\</Literal>'' (or ``<Literal>B:/</Literal>'', ``<Literal>B:\</Literal>'' etc).
 980 </Para>
 981
 982 <Para>
 983 Patrick Sansom had a workshop paper about how all this is done (though
 984 the details have changed quite a bit).  Ask
 985 him (email: <ULink
 986 URL="mailto:sansom@dcs.gla.ac.uk"
 987 >sansom@dcs.gla.ac.uk</ULink
 988 >) if you want a copy.
 989 </Para>
 990
 991 </Sect2>
 992
 993 <Sect2 id="using-make">
 994 <Title>Using <Literal>make</Literal>
 995 </Title>
 996
 997 <Para>
 998 <IndexTerm><Primary><literal>make</literal></Primary></IndexTerm>
 999 </Para>
1000
1001 <Para>
1002 It is reasonably straightforward to set up a <Literal>Makefile</Literal> to use with
1003 GHC, assuming you name your source files the same as your modules.
1004 Thus:
1005 </Para>
1006
1007 <Para>
1008
1009 <ProgramListing>
1010 HC      = ghc
1011 HC_OPTS = -cpp $(EXTRA_HC_OPTS)
1012
1013 SRCS = Main.lhs Foo.lhs Bar.lhs
1014 OBJS = Main.o   Foo.o   Bar.o
1015
1016 .SUFFIXES : .o .hi .lhs .hc .s
1017
1018 cool_pgm : $(OBJS)
1019         rm $@
1020         $(HC) -o $@ $(HC_OPTS) $(OBJS)
1021
1022 # Standard suffix rules
1023 .o.hi:
1024         @:
1025
1026 .lhs.o:
1027         $(HC) -c $&#60; $(HC_OPTS)
1028
1029 .hs.o:
1030         $(HC) -c $&#60; $(HC_OPTS)
1031
1032 # Inter-module dependencies
1033 Foo.o Foo.hc Foo.s    : Baz.hi          # Foo imports Baz
1034 Main.o Main.hc Main.s : Foo.hi Baz.hi   # Main imports Foo and Baz
1035 </ProgramListing>
1036
1037 </Para>
1038
1039 <Para>
1040 (Sophisticated <Literal>make</Literal> variants may achieve some of the above more
1041 elegantly.  Notably, <Literal>gmake</Literal>'s pattern rules let you write the more
1042 comprehensible:
1043 </Para>
1044
1045 <Para>
1046
1047 <ProgramListing>
1048 %.o : %.lhs
1049         $(HC) -c $&#60; $(HC_OPTS)
1050 </ProgramListing>
1051
1052 </Para>
1053
1054 <Para>
1055 What we've shown should work with any <Literal>make</Literal>.)
1056 </Para>
1057
1058 <Para>
1059 Note the cheesy <Literal>.o.hi</Literal> rule: It records the dependency of the
1060 interface (<Literal>.hi</Literal>) file on the source.  The rule says a <Literal>.hi</Literal> file can
1061 be made from a <Literal>.o</Literal> file by doing&hellip;nothing.  Which is true.
1062 </Para>
1063
1064 <Para>
1065 Note the inter-module dependencies at the end of the Makefile, which
1066 take the form
1067 </Para>
1068
1069 <Para>
1070
1071 <ProgramListing>
1072 Foo.o Foo.hc Foo.s    : Baz.hi          # Foo imports Baz
1073 </ProgramListing>
1074
1075 </Para>
1076
1077 <Para>
1078 They tell <Literal>make</Literal> that if any of <Literal>Foo.o</Literal>, <Literal>Foo.hc</Literal> or <Literal>Foo.s</Literal> have an
1079 earlier modification date than <Literal>Baz.hi</Literal>, then the out-of-date file
1080 must be brought up to date.  To bring it up to date, <Literal>make</Literal> looks for
1081 a rule to do so; one of the preceding suffix rules does the job
1082 nicely.
1083 </Para>
1084
1085 <Para>
1086 Putting inter-dependencies of the form <Literal>Foo.o : Bar.hi</Literal> into your
1087 <Literal>Makefile</Literal> by hand is rather error-prone.  Don't worry&mdash;never fear,
1088 <Literal>mkdependHS</Literal> is here! (and is distributed as part of GHC) Add the
1089 following to your <Literal>Makefile</Literal>:
1090 </Para>
1091
1092 <Para>
1093
1094 <ProgramListing>
1095 depend :
1096         mkdependHS -- $(HC_OPTS) -- $(SRCS)
1097 </ProgramListing>
1098
1099 </Para>
1100
1101 <Para>
1102 Now, before you start compiling, and any time you change the <Literal>imports</Literal>
1103 in your program, do <Literal>make depend</Literal> before you do <Literal>make cool&lowbar;pgm</Literal>.
1104 <Literal>mkdependHS</Literal> will append the needed dependencies to your <Literal>Makefile</Literal>.
1105 <Literal>mkdependHS</Literal> is fully described in <XRef LinkEnd="mkdependHS">.
1106 </Para>
1107
1108 <Para>
1109 A few caveats about this simple scheme:
1110 </Para>
1111
1112 <Para>
1113
1114 <ItemizedList>
1115 <ListItem>
1116
1117 <Para>
1118  You may need to compile some modules explicitly to create their
1119 interfaces in the first place (e.g., <Literal>make Bar.o</Literal> to create <Literal>Bar.hi</Literal>).
1120
1121 </Para>
1122 </ListItem>
1123 <ListItem>
1124
1125 <Para>
1126  You may have to type <Literal>make</Literal> more than once for the dependencies
1127 to have full effect.  However, a <Literal>make</Literal> run that does nothing
1128 <Emphasis>does</Emphasis> mean ``everything's up-to-date.''
1129
1130 </Para>
1131 </ListItem>
1132 <ListItem>
1133
1134 <Para>
1135  This scheme will work with mutually-recursive modules but,
1136 again, it may take multiple iterations to ``settle.''
1137
1138 </Para>
1139 </ListItem>
1140
1141 </ItemizedList>
1142
1143 </Para>
1144
1145 </Sect2>
1146
1147 <Sect2 id="mutual-recursion">
1148 <Title>How to compile mutually recursive modules
1149 </Title>
1150
1151 <Para>
1152 <IndexTerm><Primary>module system, recursion</Primary></IndexTerm>
1153 <IndexTerm><Primary>recursion, between modules</Primary></IndexTerm>
1154 </Para>
1155
1156 <Para>
1157 Currently, the compiler does not have proper support for dealing with
1158 mutually recursive modules:
1159 </Para>
1160
1161 <Para>
1162
1163 <ProgramListing>
1164 module A where
1165
1166 import B
1167
1168 newtype TA = MkTA Int
1169
1170 f :: TB -&#62; TA
1171 f (MkTB x) = MkTA x
1172 --------
1173 module B where
1174
1175 import A
1176
1177 data TB = MkTB !Int
1178
1179 g :: TA -&#62; TB
1180 g (MkTA x) = MkTB x
1181 </ProgramListing>
1182
1183 </Para>
1184
1185 <Para>
1186 When compiling either module A and B, the compiler will try (in vain)
1187 to look for the interface file of the other. So, to get mutually
1188 recursive modules off the ground, you need to hand write an interface
1189 file for A or B, so as to break the loop.  These hand-written
1190 interface files are called <Literal>hi-boot</Literal> files, and are placed in a file
1191 called <Literal>&lt;module&gt;.hi-boot</Literal>.  To import from an <Literal>hi-boot</Literal> file instead
1192 of the standard <Literal>.hi</Literal> file, use the following syntax in the importing module:
1193 <IndexTerm><Primary>hi-boot files</Primary></IndexTerm>
1194 <IndexTerm><Primary>importing, hi-boot files</Primary></IndexTerm>
1195 </Para>
1196
1197 <Para>
1198
1199 <ProgramListing>
1200 import {-# SOURCE #-} A
1201 </ProgramListing>
1202
1203 </Para>
1204
1205 <Para>
1206 The hand-written interface need only contain the bare minimum of
1207 information needed to get the bootstrapping process started.  For
1208 example, it doesn't need to contain declarations for <Emphasis>everything</Emphasis>
1209 that module <Literal>A</Literal> exports, only the things required by the module that
1210 imports <Literal>A</Literal> recursively.
1211 </Para>
1212
1213 <Para>
1214 For the example at hand, the boot interface file for A would look like
1215 the following:
1216 </Para>
1217
1218 <Para>
1219
1220 <ProgramListing>
1221 __interface A 1 404 where
1222 __export A TA{MkTA} ;
1223 1 newtype TA = MkTA PrelBase.Int ;
1224 </ProgramListing>
1225
1226 </Para>
1227
1228 <Para>
1229 The syntax is essentially the same as a normal <Literal>.hi</Literal> file
1230 (unfortunately), but you can usually tailor an existing <Literal>.hi</Literal> file to
1231 make a <Literal>.hi-boot</Literal> file.
1232 </Para>
1233
1234 <Para>
1235 Notice that we only put the declaration for the newtype <Literal>TA</Literal> in the
1236 <Literal>hi-boot</Literal> file, not the signature for <Literal>f</Literal>, since <Literal>f</Literal> isn't used by
1237 <Literal>B</Literal>.
1238 </Para>
1239
1240 <Para>
1241 The number ``1'' after ``&lowbar;&lowbar;interface A'' gives the version number of module A;
1242 it is incremented whenever anything in A's interface file changes.  The ``404'' is
1243 the version number of the interface file <Emphasis>syntax</Emphasis>; we change it when
1244 we change the syntax of interface files so that you get a better error message when
1245 you try to read an old-format file with a new-format compiler.
1246 </Para>
1247
1248 <Para>
1249 The number ``1'' at the beginning of a declaration is the <Emphasis>version
1250 number</Emphasis> of that declaration: for the purposes of <Literal>.hi-boot</Literal> files
1251 these can all be set to 1.  All names must be fully qualified with the
1252 <Emphasis>original</Emphasis> module that an object comes from: for example, the
1253 reference to <Literal>Int</Literal> in the interface for <Literal>A</Literal> comes from <Literal>PrelBase</Literal>,
1254 which is a module internal to GHC's prelude.  It's a pain, but that's
1255 the way it is.
1256 </Para>
1257
1258 <Para>
1259 If you want an hi-boot file to export a data type, but you don't want to give its constructors
1260 (because the constructors aren't used by the SOURCE-importing module), you can write simply:
1261 </Para>
1262
1263 <Para>
1264
1265 <ProgramListing>
1266 __interface A 1 404 where
1267 __export A TA;
1268 1 data TA
1269 </ProgramListing>
1270
1271 </Para>
1272
1273 <Para>
1274 (You must write all the type parameters, but leave out the '=' and everything that follows it.)
1275 </Para>
1276
1277 <Para>
1278 <Emphasis>Note:</Emphasis> This is all a temporary solution, a version of the
1279 compiler that handles mutually recursive modules properly without the manual
1280 construction of interface files, is (allegedly) in the works.
1281 </Para>
1282
1283 </Sect2>
1284
1285 </Sect1>
1286
1287 <Sect1 id="options-optimise">
1288 <Title>Optimisation (code improvement)
1289 </Title>
1290
1291 <Para>
1292 <IndexTerm><Primary>optimisation (GHC)</Primary></IndexTerm>
1293 <IndexTerm><Primary>improvement, code (GHC)</Primary></IndexTerm>
1294 </Para>
1295
1296 <Para>
1297 The <Literal>-O*</Literal> options specify convenient ``packages'' of optimisation
1298 flags; the <Literal>-f*</Literal> options described later on specify
1299 <Emphasis>individual</Emphasis> optimisations to be turned on/off; the <Literal>-m*</Literal>
1300 options specify <Emphasis>machine-specific</Emphasis> optimisations to be turned
1301 on/off.
1302 </Para>
1303
1304 <Sect2 id="optimise-pkgs">
1305 <Title><Literal>-O*</Literal>: convenient ``packages'' of optimisation flags.
1306 </Title>
1307
1308 <Para>
1309 <IndexTerm><Primary>-O options</Primary></IndexTerm>
1310 </Para>
1311
1312 <Para>
1313 There are <Emphasis>many</Emphasis> options that affect the quality of code
1314 produced by GHC.  Most people only have a general goal, something like
1315 ``Compile quickly'' or ``Make my program run like greased lightning.''
1316 The following ``packages'' of optimisations (or lack thereof) should
1317 suffice.
1318 </Para>
1319
1320 <Para>
1321 Once you choose a <Literal>-O*</Literal> ``package,'' stick with it&mdash;don't chop and
1322 change.  Modules' interfaces <Emphasis>will</Emphasis> change with a shift to a new
1323 <Literal>-O*</Literal> option, and you may have to recompile a large chunk of all
1324 importing modules before your program can again be run
1325 safely (see <XRef LinkEnd="recomp">).
1326 </Para>
1327
1328 <Para>
1329 <VariableList>
1330
1331 <VarListEntry>
1332 <Term>No <Literal>-O*</Literal>-type option specified:</Term>
1333 <ListItem>
1334 <Para>
1335 <IndexTerm><Primary>-O* not specified</Primary></IndexTerm>
1336 This is taken to mean: ``Please compile quickly; I'm not over-bothered
1337 about compiled-code quality.''  So, for example: <Literal>ghc -c Foo.hs</Literal>
1338 </Para>
1339 </ListItem>
1340 </VarListEntry>
1341 <VarListEntry>
1342 <Term><Literal>-O</Literal> or <Literal>-O1</Literal>:</Term>
1343 <ListItem>
1344 <Para>
1345 <IndexTerm><Primary>-O option</Primary></IndexTerm>
1346 <IndexTerm><Primary>-O1 option</Primary></IndexTerm>
1347 <IndexTerm><Primary>optimise normally</Primary></IndexTerm>
1348 Means: ``Generate good-quality code without taking too long about it.''
1349 Thus, for example: <Literal>ghc -c -O Main.lhs</Literal>
1350 </Para>
1351 </ListItem>
1352 </VarListEntry>
1353 <VarListEntry>
1354 <Term><Literal>-O2</Literal>:</Term>
1355 <ListItem>
1356 <Para>
1357 <IndexTerm><Primary>-O2 option</Primary></IndexTerm>
1358 <IndexTerm><Primary>optimise aggressively</Primary></IndexTerm>
1359 Means: ``Apply every non-dangerous optimisation, even if it means
1360 significantly longer compile times.''
1361 </Para>
1362
1363 <Para>
1364 The avoided ``dangerous'' optimisations are those that can make
1365 runtime or space <Emphasis>worse</Emphasis> if you're unlucky.  They are
1366 normally turned on or off individually.
1367 </Para>
1368
1369 <Para>
1370 At the moment, <Literal>-O2</Literal> is <Emphasis>unlikely</Emphasis> to produce
1371 better code than <Literal>-O</Literal>.
1372 </Para>
1373 </ListItem>
1374 </VarListEntry>
1375 <VarListEntry>
1376 <Term><Literal>-O2-for-C</Literal>:</Term>
1377 <ListItem>
1378 <Para>
1379 <IndexTerm><Primary>-O2-for-C option</Primary></IndexTerm>
1380 <IndexTerm><Primary>gcc, invoking with -O2</Primary></IndexTerm>
1381 </Para>
1382
1383 <Para>
1384 Says to run GCC with <Literal>-O2</Literal>, which may be worth a few percent in
1385 execution speed.  Don't forget <Literal>-fvia-C</Literal>, lest you use the native-code
1386 generator and bypass GCC altogether!
1387 </Para>
1388 </ListItem>
1389 </VarListEntry>
1390 <VarListEntry>
1391 <Term><Literal>-Onot</Literal>:</Term>
1392 <ListItem>
1393 <Para>
1394 <IndexTerm><Primary>-Onot option</Primary></IndexTerm>
1395 <IndexTerm><Primary>optimising, reset</Primary></IndexTerm>
1396 </Para>
1397
1398 <Para>
1399 This option will make GHC ``forget'' any <Literal>-O</Literal>ish options it has seen so
1400 far.  Sometimes useful; for example: <Literal>make all EXTRA&lowbar;HC&lowbar;OPTS=-Onot</Literal>.
1401 </Para>
1402 </ListItem>
1403 </VarListEntry>
1404 <VarListEntry>
1405 <Term><Literal>-Ofile &lt;file&gt;</Literal>:</Term>
1406 <ListItem>
1407 <Para>
1408 <IndexTerm><Primary>-Ofile &lt;file&gt; option</Primary></IndexTerm>
1409 <IndexTerm><Primary>optimising, customised</Primary></IndexTerm>
1410 </Para>
1411
1412 <Para>
1413 For those who need <Emphasis>absolute</Emphasis> control over <Emphasis>exactly</Emphasis>
1414 what options are used (e.g., compiler writers, sometimes :-), a list
1415 of options can be put in a file and then slurped in with <Literal>-Ofile</Literal>.
1416 </Para>
1417
1418 <Para>
1419 In that file, comments are of the <Literal>&num;</Literal>-to-end-of-line variety; blank
1420 lines and most whitespace is ignored.
1421 </Para>
1422
1423 <Para>
1424 Please ask if you are baffled and would like an example of <Literal>-Ofile</Literal>!
1425 </Para>
1426 </ListItem>
1427 </VarListEntry>
1428 </VariableList>
1429 </Para>
1430
1431 <Para>
1432 At Glasgow, we don't use a <Literal>-O*</Literal> flag for day-to-day work.  We use
1433 <Literal>-O</Literal> to get respectable speed; e.g., when we want to measure
1434 something.  When we want to go for broke, we tend to use <Literal>-O -fvia-C
1435 -O2-for-C</Literal> (and we go for lots of coffee breaks).
1436 </Para>
1437
1438 <Para>
1439 The easiest way to see what <Literal>-O</Literal> (etc.) ``really mean'' is to run with
1440 <Literal>-v</Literal>, then stand back in amazement.  Alternatively, just look at the
1441 <Literal>HsC&lowbar;minus&lt;blah&gt;</Literal> lists in the <Literal>ghc</Literal> driver script.
1442 </Para>
1443
1444 </Sect2>
1445
1446 <Sect2>
1447 <Title><Literal>-f*</Literal>: platform-independent flags</Title>
1448
1449 <Para>
1450 <IndexTerm><Primary>-f* options (GHC)</Primary></IndexTerm>
1451 <IndexTerm><Primary>-fno-* options (GHC)</Primary></IndexTerm>
1452 </Para>
1453
1454 <Para>
1455 Flags can be turned <Emphasis>off</Emphasis> individually.  (NB: I hope you have a
1456 good reason for doing this&hellip;) To turn off the <Literal>-ffoo</Literal> flag, just use
1457 the <Literal>-fno-foo</Literal> flag.<IndexTerm><Primary>-fno-&lt;opt&gt; anti-option</Primary></IndexTerm> So, for
1458 example, you can say <Literal>-O2 -fno-strictness</Literal>, which will then drop out
1459 any running of the strictness analyser.
1460 </Para>
1461
1462 <Para>
1463 The options you are most likely to want to turn off are:
1464
1465 <ItemizedList>
1466 <ListItem>
1467
1468 <Para>
1469 <Literal>-fno-strictness</Literal><IndexTerm><Primary>-fno-strictness option</Primary></IndexTerm> (strictness
1470 analyser, because it is sometimes slow),
1471 </Para>
1472 </ListItem>
1473 <ListItem>
1474
1475 <Para>
1476 <Literal>-fno-specialise</Literal><IndexTerm><Primary>-fno-specialise option</Primary></IndexTerm> (automatic
1477 specialisation of overloaded functions, because it can make your code
1478 bigger) (US spelling also accepted), and
1479 </Para>
1480 </ListItem>
1481 <ListItem>
1482
1483 <Para>
1484 <Literal>-fno-cpr-analyse</Literal><IndexTerm><Primary>-fno-cpr-analyse option</Primary></IndexTerm> switches off the CPR (constructed product
1485 result) analyser.
1486 </Para>
1487 </ListItem>
1488
1489 </ItemizedList>
1490
1491 </Para>
1492
1493 <Para>
1494 Should you wish to turn individual flags <Emphasis>on</Emphasis>, you are advised
1495 to use the <Literal>-Ofile</Literal> option, described above.  Because the order in
1496 which optimisation passes are run is sometimes crucial, it's quite
1497 hard to do with command-line options.
1498 </Para>
1499
1500 <Para>
1501 Here are some ``dangerous'' optimisations you <Emphasis>might</Emphasis> want to try:
1502 <VariableList>
1503
1504 <VarListEntry>
1505 <Term><Literal>-fvia-C</Literal>:</Term>
1506 <ListItem>
1507 <Para>
1508 <IndexTerm><Primary>-fvia-C option</Primary></IndexTerm>
1509 <IndexTerm><Primary>native code generator, turning off</Primary></IndexTerm>
1510 </Para>
1511
1512 <Para>
1513 Compile via C, and don't use the native-code generator.  (There are
1514 many cases when GHC does this on its own.)  You might pick up a little
1515 bit of speed by compiling via C.  If you use <Literal>&lowbar;ccall&lowbar;gc&lowbar;</Literal>s or
1516 <Literal>&lowbar;casm&lowbar;</Literal>s, you probably <Emphasis>have</Emphasis> to use <Literal>-fvia-C</Literal>.
1517 </Para>
1518
1519 <Para>
1520 The lower-case incantation, <Literal>-fvia-c</Literal>, is synonymous.
1521 </Para>
1522
1523 <Para>
1524 Compiling via C will probably be slower (in compilation time) than
1525 using GHC's native code generator.
1526 </Para>
1527 </ListItem>
1528 </VarListEntry>
1529 <VarListEntry>
1530 <Term><Literal>-funfolding-interface-threshold&lt;n&gt;</Literal>:</Term>
1531 <ListItem>
1532 <Para>
1533 <IndexTerm><Primary>-funfolding-interface-threshold option</Primary></IndexTerm>
1534 <IndexTerm><Primary>inlining, controlling</Primary></IndexTerm>
1535 <IndexTerm><Primary>unfolding, controlling</Primary></IndexTerm>
1536 (Default: 30) By raising or lowering this number, you can raise or
1537 lower the amount of pragmatic junk that gets spewed into interface
1538 files.  (An unfolding has a ``size'' that reflects the cost in terms
1539 of ``code bloat'' of expanding that unfolding in another module.  A
1540 bigger function would be assigned a bigger cost.)
1541 </Para>
1542 </ListItem>
1543 </VarListEntry>
1544 <VarListEntry>
1545 <Term><Literal>-funfolding-creation-threshold&lt;n&gt;</Literal>:</Term>
1546 <ListItem>
1547 <Para>
1548 <IndexTerm><Primary>-funfolding-creation-threshold option</Primary></IndexTerm>
1549 <IndexTerm><Primary>inlining, controlling</Primary></IndexTerm>
1550 <IndexTerm><Primary>unfolding, controlling</Primary></IndexTerm>
1551 (Default: 30) This option is similar to
1552 <Literal>-funfolding-interface-threshold</Literal>, except that it governs unfoldings
1553 within a single module.  Increasing this figure is more likely to
1554 result in longer compile times than faster code.  The next option is
1555 more useful:
1556 </Para>
1557 </ListItem>
1558 </VarListEntry>
1559 <VarListEntry>
1560 <Term><Literal>-funfolding-use-threshold&lt;n&gt;</Literal>:</Term>
1561 <ListItem>
1562 <Para>
1563 <IndexTerm><Primary>-funfolding-use-threshold option</Primary></IndexTerm>
1564 <IndexTerm><Primary>inlining, controlling</Primary></IndexTerm>
1565 <IndexTerm><Primary>unfolding, controlling</Primary></IndexTerm>
1566 (Default: 8) This is the magic cut-off figure for unfolding: below
1567 this size, a function definition will be unfolded at the call-site,
1568 any bigger and it won't.  The size computed for a function depends on
1569 two things: the actual size of the expression minus any discounts that
1570 apply (see <Literal>-funfolding-con-discount</Literal>).
1571 </Para>
1572 </ListItem>
1573 </VarListEntry>
1574 <VarListEntry>
1575 <Term><Literal>-funfolding-con-discount&lt;n&gt;</Literal>:</Term>
1576 <ListItem>
1577 <Para>
1578 <IndexTerm><Primary>-funfolding-con-discount option</Primary></IndexTerm>
1579 <IndexTerm><Primary>inlining, controlling</Primary></IndexTerm>
1580 <IndexTerm><Primary>unfolding, controlling</Primary></IndexTerm>
1581 (Default: 2) If the compiler decides that it can eliminate some
1582 computation by performing an unfolding, then this is a discount factor
1583 that it applies to the funciton size before deciding whether to unfold
1584 it or not.
1585 </Para>
1586
1587 <Para>
1588 OK, folks, these magic numbers `30', `8', and '2' are mildly
1589 arbitrary; they are of the ``seem to be OK'' variety.  The `8' is the
1590 more critical one; it's what determines how eager GHC is about
1591 expanding unfoldings.
1592 </Para>
1593 </ListItem>
1594 </VarListEntry>
1595 <VarListEntry>
1596 <Term><Literal>-funbox-strict-fields</Literal>:</Term>
1597 <ListItem>
1598 <Para>
1599 <IndexTerm><Primary>-funbox-strict-fields option</Primary></IndexTerm>
1600 <IndexTerm><Primary>strict constructor fields</Primary></IndexTerm>
1601 <IndexTerm><Primary>constructor fields, strict</Primary></IndexTerm>
1602 </Para>
1603
1604 <Para>
1605 This option causes all constructor fields which are marked strict
1606 (i.e. ``!'') to be unboxed or unpacked if possible.  For example:
1607 </Para>
1608
1609 <Para>
1610
1611 <ProgramListing>
1612 data T = T !Float !Float
1613 </ProgramListing>
1614
1615 </Para>
1616
1617 <Para>
1618 will create a constructor <Literal>T</Literal> containing two unboxed floats if the
1619 <Literal>-funbox-strict-fields</Literal> flag is given.  This may not always be an
1620 optimisation: if the <Literal>T</Literal> constructor is scrutinised and the floats
1621 passed to a non-strict function for example, they will have to be
1622 reboxed (this is done automatically by the compiler).
1623 </Para>
1624
1625 <Para>
1626 This option should only be used in conjunction with <Literal>-O</Literal>, in order to
1627 expose unfoldings to the compiler so the reboxing can be removed as
1628 often as possible.  For example:
1629 </Para>
1630
1631 <Para>
1632
1633 <ProgramListing>
1634 f :: T -&#62; Float
1635 f (T f1 f2) = f1 + f2
1636 </ProgramListing>
1637
1638 </Para>
1639
1640 <Para>
1641 The compiler will avoid reboxing <Literal>f1</Literal> and <Literal>f2</Literal> by inlining <Literal>+</Literal> on
1642 floats, but only when <Literal>-O</Literal> is on.
1643 </Para>
1644
1645 <Para>
1646 Any single-constructor data is eligible for unpacking; for example
1647 </Para>
1648
1649 <Para>
1650
1651 <ProgramListing>
1652 data T = T !(Int,Int)
1653 </ProgramListing>
1654
1655 </Para>
1656
1657 <Para>
1658 will store the two <Literal>Int</Literal>s directly in the <Literal>T</Literal> constructor, by flattening
1659 the pair.  Multi-level unpacking is also supported:
1660 </Para>
1661
1662 <Para>
1663
1664 <ProgramListing>
1665 data T = T !S
1666 data S = S !Int !Int
1667 </ProgramListing>
1668
1669 </Para>
1670
1671 <Para>
1672 will store two unboxed <Literal>Int&num;</Literal>s directly in the <Literal>T</Literal> constructor.
1673 </Para>
1674 </ListItem>
1675 </VarListEntry>
1676 <VarListEntry>
1677 <Term><Literal>-fsemi-tagging</Literal>:</Term>
1678 <ListItem>
1679 <Para>
1680 This option (which <Emphasis>does not work</Emphasis> with the native-code generator)
1681 tells the compiler to add extra code to test for already-evaluated
1682 values.  You win if you have lots of such values during a run of your
1683 program, you lose otherwise.  (And you pay in extra code space.)
1684 </Para>
1685
1686 <Para>
1687 We have not played with <Literal>-fsemi-tagging</Literal> enough to recommend it.
1688 (For all we know, it doesn't even work anymore&hellip; Sigh.)
1689 </Para>
1690 </ListItem>
1691 </VarListEntry>
1692 </VariableList>
1693 </Para>
1694
1695 </Sect2>
1696
1697 <Sect2>
1698 <Title><Literal>-m*</Literal>: platform-specific flags</Title>
1699
1700 <Para>
1701 <IndexTerm><Primary>-m* options (GHC)</Primary></IndexTerm>
1702 <IndexTerm><Primary>platform-specific options</Primary></IndexTerm>
1703 <IndexTerm><Primary>machine-specific options</Primary></IndexTerm>
1704 </Para>
1705
1706 <Para>
1707 Some flags only make sense for particular target platforms.
1708 </Para>
1709
1710 <Para>
1711 <VariableList>
1712
1713 <VarListEntry>
1714 <Term><Literal>-mv8</Literal>:</Term>
1715 <ListItem>
1716 <Para>
1717 (SPARC machines)<IndexTerm><Primary>-mv8 option (SPARC only)</Primary></IndexTerm>
1718 Means to pass the like-named option to GCC; it says to use the
1719 Version 8 SPARC instructions, notably integer multiply and divide.
1720 The similiar <Literal>-m*</Literal> GCC options for SPARC also work, actually.
1721 </Para>
1722 </ListItem>
1723 </VarListEntry>
1724 <VarListEntry>
1725 <Term><Literal>-mlong-calls</Literal>:</Term>
1726 <ListItem>
1727 <Para>
1728 (HPPA machines)<IndexTerm><Primary>-mlong-calls option (HPPA only)</Primary></IndexTerm>
1729 Means to pass the like-named option to GCC.  Required for Very Big
1730 modules, maybe.  (Probably means you're in trouble&hellip;)
1731 </Para>
1732 </ListItem>
1733 </VarListEntry>
1734 <VarListEntry>
1735 <Term><Literal>-monly-[32]-regs</Literal>:</Term>
1736 <ListItem>
1737 <Para>
1738 (iX86 machines)<IndexTerm><Primary>-monly-N-regs option (iX86 only)</Primary></IndexTerm>
1739 GHC tries to ``steal'' four registers from GCC, for performance
1740 reasons; it almost always works.  However, when GCC is compiling some
1741 modules with four stolen registers, it will crash, probably saying:
1742
1743 <Screen>
1744 Foo.hc:533: fixed or forbidden register was spilled.
1745 This may be due to a compiler bug or to impossible asm
1746 statements or clauses.
1747 </Screen>
1748
1749 Just give some registers back with <Literal>-monly-N-regs</Literal>.  Try `3' first,
1750 then `2'.  If `2' doesn't work, please report the bug to us.
1751 </Para>
1752 </ListItem>
1753 </VarListEntry>
1754 </VariableList>
1755 </Para>
1756
1757 </Sect2>
1758
1759 <Sect2 id="optimise-C-compiler">
1760 <Title>Code improvement by the C compiler.
1761 </Title>
1762
1763 <Para>
1764 <IndexTerm><Primary>optimisation by GCC</Primary></IndexTerm>
1765 <IndexTerm><Primary>GCC optimisation</Primary></IndexTerm>
1766 </Para>
1767
1768 <Para>
1769 The C&nbsp;compiler (GCC) is run with <Literal>-O</Literal> turned on.  (It has
1770 to be, actually).
1771 </Para>
1772
1773 <Para>
1774 If you want to run GCC with <Literal>-O2</Literal>&mdash;which may be worth a few
1775 percent in execution speed&mdash;you can give a
1776 <Literal>-O2-for-C</Literal><IndexTerm><Primary>-O2-for-C option</Primary></IndexTerm> option.
1777 </Para>
1778
1779 </Sect2>
1780
1781 </Sect1>
1782
1783 <Sect1 id="options-phases">
1784 <Title>Options related to a particular phase
1785 </Title>
1786
1787 <Sect2 id="c-pre-processor">
1788 <Title>The C pre-processor
1789 </Title>
1790
1791 <Para>
1792 <IndexTerm><Primary>pre-processing: cpp</Primary></IndexTerm>
1793 <IndexTerm><Primary>C pre-processor options</Primary></IndexTerm>
1794 <IndexTerm><Primary>cpp, pre-processing with</Primary></IndexTerm>
1795 </Para>
1796
1797 <Para>
1798 The C pre-processor <Literal>cpp</Literal> is run over your Haskell code only if the
1799 <Literal>-cpp</Literal> option <IndexTerm><Primary>-cpp option</Primary></IndexTerm> is given.  Unless you are
1800 building a large system with significant doses of conditional
1801 compilation, you really shouldn't need it.
1802 <VariableList>
1803
1804 <VarListEntry>
1805 <Term><Literal>-D&lt;foo&gt;</Literal>:</Term>
1806 <ListItem>
1807 <Para>
1808 <IndexTerm><Primary>-D&lt;name&gt; option</Primary></IndexTerm>
1809 Define macro <Literal>&lt;foo&gt;</Literal> in the usual way.  NB: does <Emphasis>not</Emphasis> affect
1810 <Literal>-D</Literal> macros passed to the C&nbsp;compiler when compiling via C!  For those,
1811 use the <Literal>-optc-Dfoo</Literal> hack&hellip; (see <XRef LinkEnd="forcing-options-through">).
1812 </Para>
1813 </ListItem>
1814 </VarListEntry>
1815 <VarListEntry>
1816 <Term><Literal>-U&lt;foo&gt;</Literal>:</Term>
1817 <ListItem>
1818 <Para>
1819 <IndexTerm><Primary>-U&lt;name&gt; option</Primary></IndexTerm>
1820 Undefine macro <Literal>&lt;foo&gt;</Literal> in the usual way.
1821 </Para>
1822 </ListItem>
1823 </VarListEntry>
1824 <VarListEntry>
1825 <Term><Literal>-I&lt;dir&gt;</Literal>:</Term>
1826 <ListItem>
1827 <Para>
1828 <IndexTerm><Primary>-I&lt;dir&gt; option</Primary></IndexTerm>
1829 Specify a directory in which to look for <Literal>&num;include</Literal> files, in
1830 the usual C way.
1831 </Para>
1832 </ListItem>
1833 </VarListEntry>
1834 </VariableList>
1835 </Para>
1836
1837 <Para>
1838 The <Literal>ghc</Literal> driver pre-defines several macros when processing Haskell
1839 source code (<Literal>.hs</Literal> or <Literal>.lhs</Literal> files):
1840 </Para>
1841
1842 <Para>
1843 <VariableList>
1844
1845 <VarListEntry>
1846 <Term><Literal>&lowbar;&lowbar;HASKELL98&lowbar;&lowbar;</Literal>:</Term>
1847 <ListItem>
1848 <Para>
1849 <IndexTerm><Primary>&lowbar;&lowbar;HASKELL98&lowbar;&lowbar;</Primary></IndexTerm>
1850 If defined, this means that GHC supports the language defined by the
1851 Haskell 98 report.
1852 </Para>
1853 </ListItem>
1854 </VarListEntry>
1855 <VarListEntry>
1856 <Term><Literal>&lowbar;&lowbar;HASKELL&lowbar;&lowbar;=98</Literal>:</Term>
1857 <ListItem>
1858 <Para>
1859 <IndexTerm><Primary>&lowbar;&lowbar;HASKELL&lowbar;&lowbar;</Primary></IndexTerm>
1860 In GHC 4.04 and later, the <Literal>&lowbar;&lowbar;HASKELL&lowbar;&lowbar;</Literal> macro is defined as having
1861 the value <Literal>98</Literal>.
1862 </Para>
1863 </ListItem>
1864 </VarListEntry>
1865 <VarListEntry>
1866 <Term><Literal>&lowbar;&lowbar;HASKELL1&lowbar;&lowbar;</Literal>:</Term>
1867 <ListItem>
1868 <Para>
1869 <IndexTerm><Primary>&lowbar;&lowbar;HASKELL1&lowbar;&lowbar; macro</Primary></IndexTerm>
1870 If defined to <Emphasis>n</Emphasis>, that means GHC supports the Haskell language
1871 defined in the Haskell report version <Emphasis>1.n</Emphasis>.  Currently 5.  This
1872 macro is deprecated, and will probably disappear in future versions.
1873 </Para>
1874 </ListItem>
1875 </VarListEntry>
1876 <VarListEntry>
1877 <Term><Literal>&lowbar;&lowbar;GLASGOW&lowbar;HASKELL&lowbar;&lowbar;</Literal>:</Term>
1878 <ListItem>
1879 <Para>
1880 <IndexTerm><Primary>&lowbar;&lowbar;GLASGOW&lowbar;HASKELL&lowbar;&lowbar; macro</Primary></IndexTerm>
1881 For version <Emphasis>n</Emphasis> of the GHC system, this will be <Literal>&num;define</Literal>d to
1882 <Emphasis>100n</Emphasis>.  So, for version 4.00, it is 400.
1883 </Para>
1884
1885 <Para>
1886 With any luck, <Literal>&lowbar;&lowbar;GLASGOW&lowbar;HASKELL&lowbar;&lowbar;</Literal> will be undefined in all other
1887 implementations that support C-style pre-processing.
1888 </Para>
1889
1890 <Para>
1891 (For reference: the comparable symbols for other systems are:
1892 <Literal>&lowbar;&lowbar;HUGS&lowbar;&lowbar;</Literal> for Hugs and <Literal>&lowbar;&lowbar;HBC&lowbar;&lowbar;</Literal> for Chalmers.)
1893 </Para>
1894
1895 <Para>
1896 NB. This macro is set when pre-processing both Haskell source and C
1897 source, including the C source generated from a Haskell module
1898 (ie. <Literal>.hs</Literal>, <Literal>.lhs</Literal>, <Literal>.c</Literal> and <Literal>.hc</Literal> files).
1899 </Para>
1900 </ListItem>
1901 </VarListEntry>
1902 <VarListEntry>
1903 <Term><Literal>&lowbar;&lowbar;CONCURRENT&lowbar;HASKELL&lowbar;&lowbar;</Literal>:</Term>
1904 <ListItem>
1905 <Para>
1906 <IndexTerm><Primary>&lowbar;&lowbar;CONCURRENT&lowbar;HASKELL&lowbar;&lowbar; macro</Primary></IndexTerm>
1907 This symbol is defined when pre-processing Haskell (input) and
1908 pre-processing C (GHC output).  Since GHC from verion 4.00 now
1909 supports concurrent haskell by default, this symbol is always defined.
1910 </Para>
1911 </ListItem>
1912 </VarListEntry>
1913 <VarListEntry>
1914 <Term><Literal>&lowbar;&lowbar;PARALLEL&lowbar;HASKELL&lowbar;&lowbar;</Literal>:</Term>
1915 <ListItem>
1916 <Para>
1917 <IndexTerm><Primary>&lowbar;&lowbar;PARALLEL&lowbar;HASKELL&lowbar;&lowbar; macro</Primary></IndexTerm>
1918 Only defined when <Literal>-parallel</Literal> is in use!  This symbol is defined when
1919 pre-processing Haskell (input) and pre-processing C (GHC output).
1920 </Para>
1921 </ListItem>
1922 </VarListEntry>
1923 </VariableList>
1924 </Para>
1925
1926 <Para>
1927 Options other than the above can be forced through to the C
1928 pre-processor with the <Literal>-opt</Literal> flags (see
1929 <XRef LinkEnd="forcing-options-through">).
1930 </Para>
1931
1932 <Para>
1933 A small word of warning: <Literal>-cpp</Literal> is not friendly to ``string
1934 gaps''.<IndexTerm><Primary>-cpp vs string gaps</Primary></IndexTerm><IndexTerm><Primary>string gaps vs
1935 -cpp</Primary></IndexTerm>.  In other words, strings such as the following:
1936 </Para>
1937
1938 <Para>
1939
1940 <ProgramListing>
1941 strmod = "\
1942 \ p \
1943 \ "
1944 </ProgramListing>
1945
1946 </Para>
1947
1948 <Para>
1949 don't work with <Literal>-cpp</Literal>; <Literal>/usr/bin/cpp</Literal> elides the
1950 backslash-newline pairs.
1951 </Para>
1952
1953 <Para>
1954 However, it appears that if you add a space at the end of the line,
1955 then <Literal>cpp</Literal> (at least GNU <Literal>cpp</Literal> and possibly other <Literal>cpp</Literal>s)
1956 leaves the backslash-space pairs alone and the string gap works as
1957 expected.
1958 </Para>
1959
1960 </Sect2>
1961
1962 <Sect2 id="options-C-compiler">
1963 <Title>Options affecting the C compiler (if applicable)
1964 </Title>
1965
1966 <Para>
1967 <IndexTerm><Primary>include-file options</Primary></IndexTerm>
1968 <IndexTerm><Primary>C compiler options</Primary></IndexTerm>
1969 <IndexTerm><Primary>GCC options</Primary></IndexTerm>
1970 </Para>
1971
1972 <Para>
1973 At the moment, quite a few common C-compiler options are passed on
1974 quietly to the C compilation of Haskell-compiler-generated C files.
1975 THIS MAY CHANGE.  Meanwhile, options so sent are:
1976 </Para>
1977
1978 <Para>
1979
1980 <InformalTable>
1981 <TGroup Cols="2">
1982 <ColSpec Align="Left" Colsep="0">
1983 <ColSpec Align="Left" Colsep="0">
1984 <TBody>
1985 <Row>
1986 <Entry><Literal>-ansi</Literal> </Entry>
1987 <Entry> do ANSI C (not K&amp;R) </Entry>
1988 </Row>
1989 <Row>
1990 <Entry>
1991 <Literal>-pedantic</Literal> </Entry>
1992 <Entry> be so</Entry>
1993 </Row>
1994 <Row>
1995 <Entry>
1996 <Literal>-dgcc-lint</Literal> </Entry>
1997 <Entry> (hack) short for ``make GCC very paranoid''</Entry>
1998 </Row>
1999
2000 </TBody>
2001
2002 </TGroup>
2003 </InformalTable>
2004
2005 <IndexTerm><Primary>-ansi option (for GCC)</Primary></IndexTerm>
2006 <IndexTerm><Primary>-pedantic option (for GCC)</Primary></IndexTerm>
2007 <IndexTerm><Primary>-dgcc-lint option (GCC paranoia)</Primary></IndexTerm>
2008 </Para>
2009
2010 <Para>
2011 If you are compiling with lots of <Literal>ccalls</Literal>, etc., you may need to
2012 tell the C&nbsp;compiler about some <Literal>&num;include</Literal> files.  There is no real
2013 pretty way to do this, but you can use this hack from the
2014 command-line:
2015 </Para>
2016
2017 <Para>
2018
2019 <Screen>
2020 % ghc -c '-#include &#60;X/Xlib.h&#62;' Xstuff.lhs
2021 </Screen>
2022
2023 </Para>
2024
2025 </Sect2>
2026
2027 <Sect2 id="options-linker">
2028 <Title>Linking and consistency-checking
2029 </Title>
2030
2031 <Para>
2032 <IndexTerm><Primary>linker options</Primary></IndexTerm>
2033 <IndexTerm><Primary>ld options</Primary></IndexTerm>
2034 </Para>
2035
2036 <Para>
2037 GHC has to link your code with various libraries, possibly including:
2038 user-supplied, GHC-supplied, and system-supplied (<Literal>-lm</Literal> math
2039 library, for example).
2040 </Para>
2041
2042 <Para>
2043 <VariableList>
2044
2045 <VarListEntry>
2046 <Term><Literal>-l&lt;FOO&gt;</Literal>:</Term>
2047 <ListItem>
2048 <Para>
2049 <IndexTerm><Primary>-l&lt;lib&gt; option</Primary></IndexTerm>
2050 Link in a library named <Literal>lib&lt;FOO&gt;.a</Literal> which resides somewhere on the
2051 library directories path.
2052 </Para>
2053
2054 <Para>
2055 Because of the sad state of most UNIX linkers, the order of such
2056 options does matter.  Thus: <Literal>ghc -lbar *.o</Literal> is almost certainly
2057 wrong, because it will search <Literal>libbar.a</Literal> <Emphasis>before</Emphasis> it has
2058 collected unresolved symbols from the <Literal>*.o</Literal> files.
2059 <Literal>ghc *.o -lbar</Literal> is probably better.
2060 </Para>
2061
2062 <Para>
2063 The linker will of course be informed about some GHC-supplied
2064 libraries automatically; these are:
2065 </Para>
2066
2067 <Para>
2068
2069 <InformalTable>
2070 <TGroup Cols="2">
2071 <ColSpec Align="Left" Colsep="0">
2072 <ColSpec Align="Left" Colsep="0">
2073 <TBody>
2074 <Row>
2075 <Entry><Emphasis>-l equivalent</Emphasis> </Entry>
2076 <Entry> <Emphasis>description</Emphasis> </Entry>
2077 </Row>
2078
2079 <Row>
2080 <Entry>
2081 <Literal>-lHSrts,-lHSclib</Literal> </Entry>
2082 <Entry> basic runtime libraries </Entry>
2083 </Row>
2084 <Row>
2085 <Entry>
2086 <Literal>-lHS</Literal> </Entry>
2087 <Entry> standard Prelude library </Entry>
2088 </Row>
2089 <Row>
2090 <Entry>
2091 <Literal>-lHS&lowbar;cbits</Literal> </Entry>
2092 <Entry> C support code for standard Prelude library </Entry>
2093 </Row>
2094 <Row>
2095 <Entry>
2096 <Literal>-lgmp</Literal> </Entry>
2097 <Entry> GNU multi-precision library (for Integers)</Entry>
2098 </Row>
2099
2100 </TBody>
2101
2102 </TGroup>
2103 </InformalTable>
2104
2105 </Para>
2106
2107 <Para>
2108 <IndexTerm><Primary>-lHS library</Primary></IndexTerm>
2109 <IndexTerm><Primary>-lHS&lowbar;cbits library</Primary></IndexTerm>
2110 <IndexTerm><Primary>-lHSrts library</Primary></IndexTerm>
2111 <IndexTerm><Primary>-lgmp library</Primary></IndexTerm>
2112 </Para>
2113 </ListItem>
2114 </VarListEntry>
2115 <VarListEntry>
2116 <Term><Literal>-syslib &lt;name&gt;</Literal>:</Term>
2117 <ListItem>
2118 <Para>
2119 <IndexTerm><Primary>-syslib &lt;name&gt; option</Primary></IndexTerm>
2120 </Para>
2121
2122 <Para>
2123 If you are using a Haskell ``system library'' (e.g., the POSIX
2124 library), just use the <Literal>-syslib posix</Literal> option, and the correct code
2125 should be linked in.
2126 </Para>
2127 </ListItem>
2128 </VarListEntry>
2129 <VarListEntry>
2130 <Term><Literal>-L&lt;dir&gt;</Literal>:</Term>
2131 <ListItem>
2132 <Para>
2133 <IndexTerm><Primary>-L&lt;dir&gt; option</Primary></IndexTerm>
2134 Where to find user-supplied libraries&hellip;  Prepend the directory
2135 <Literal>&lt;dir&gt;</Literal> to the library directories path.
2136 </Para>
2137 </ListItem>
2138 </VarListEntry>
2139 <VarListEntry>
2140 <Term><Literal>-static</Literal>:</Term>
2141 <ListItem>
2142 <Para>
2143 <IndexTerm><Primary>-static option</Primary></IndexTerm>
2144 Tell the linker to avoid shared libraries.
2145 </Para>
2146 </ListItem>
2147 </VarListEntry>
2148 <VarListEntry>
2149 <Term><Literal>-no-link-chk</Literal> and <Literal>-link-chk</Literal>:</Term>
2150 <ListItem>
2151 <Para>
2152 <IndexTerm><Primary>-no-link-chk option</Primary></IndexTerm>
2153 <IndexTerm><Primary>-link-chk option</Primary></IndexTerm>
2154 <IndexTerm><Primary>consistency checking of executables</Primary></IndexTerm>
2155 By default, immediately after linking an executable, GHC verifies that
2156 the pieces that went into it were compiled with compatible flags; a
2157 ``consistency check''.
2158 (This is to avoid mysterious failures caused by non-meshing of
2159 incompatibly-compiled programs; e.g., if one <Literal>.o</Literal> file was compiled
2160 for a parallel machine and the others weren't.)  You may turn off this
2161 check with <Literal>-no-link-chk</Literal>.  You can turn it (back) on with
2162 <Literal>-link-chk</Literal> (the default).
2163 </Para>
2164 </ListItem>
2165 </VarListEntry>
2166 <VarListEntry>
2167 <Term><Literal>-no-hs-main</Literal>:</Term>
2168 <ListItem>
2169 <Para>
2170 <IndexTerm><Primary>-no-hs-main option</Primary></IndexTerm>
2171 <IndexTerm><Primary>linking Haskell libraries with foreign code</Primary></IndexTerm>
2172 </Para>
2173
2174 <Para>
2175 In the event you want to include ghc-compiled code as part of another
2176 (non-Haskell) program, the RTS will not be supplying its definition of
2177 <Literal>main()</Literal> at link-time, you will have to. To signal that to the
2178 driver script when linking, use <Literal>-no-hs-main</Literal>.
2179 </Para>
2180
2181 <Para>
2182 Notice that since the command-line passed to the linker is rather
2183 involved, you probably want to use the ghc driver script to do the
2184 final link of your `mixed-language' application. This is not a
2185 requirement though, just try linking once with <Literal>-v</Literal> on to see what
2186 options the driver passes through to the linker.
2187 </Para>
2188 </ListItem>
2189 </VarListEntry>
2190 </VariableList>
2191 </Para>
2192
2193 </Sect2>
2194
2195 </Sect1>
2196
2197 <Sect1>
2198 <Title>Using Concurrent Haskell</Title>
2199
2200 <Para>
2201 <IndexTerm><Primary>Concurrent Haskell&mdash;use</Primary></IndexTerm>
2202 </Para>
2203
2204 <Para>
2205 GHC (as of version 4.00) supports Concurrent Haskell by default,
2206 without requiring a special option or libraries compiled in a certain
2207 way.  To get access to the support libraries for Concurrent Haskell
2208 (ie. <Literal>Concurrent</Literal> and friends), use the <Literal>-syslib concurrent</Literal> option.
2209 </Para>
2210
2211 <Para>
2212 Three RTS options are provided for modifying the behaviour of the
2213 threaded runtime system.  See the descriptions of <Literal>-C[&lt;us&gt;]</Literal>, <Literal>-q</Literal>,
2214 and <Literal>-t&lt;num&gt;</Literal> in <XRef LinkEnd="parallel-rts-opts">.
2215 </Para>
2216
2217 <Para>
2218 Concurrent Haskell is described in more detail in <XRef LinkEnd="concurrent-and-parallel">.
2219 </Para>
2220
2221 </Sect1>
2222
2223 <Sect1>
2224 <Title>Using Parallel Haskell</Title>
2225
2226 <Para>
2227 <IndexTerm><Primary>Parallel Haskell&mdash;use</Primary></IndexTerm>
2228 </Para>
2229
2230 <Para>
2231 &lsqb;You won't be able to execute parallel Haskell programs unless PVM3
2232 (Parallel Virtual Machine, version 3) is installed at your site.]
2233 </Para>
2234
2235 <Para>
2236 To compile a Haskell program for parallel execution under PVM, use the
2237 <Literal>-parallel</Literal> option,<IndexTerm><Primary>-parallel option</Primary></IndexTerm> both when compiling
2238 <Emphasis>and linking</Emphasis>.  You will probably want to <Literal>import Parallel</Literal>
2239 into your Haskell modules.
2240 </Para>
2241
2242 <Para>
2243 To run your parallel program, once PVM is going, just invoke it ``as
2244 normal''.  The main extra RTS option is <Literal>-N&lt;n&gt;</Literal>, to say how many
2245 PVM ``processors'' your program to run on.  (For more details of
2246 all relevant RTS options, please see <XRef LinkEnd="parallel-rts-opts">.)
2247 </Para>
2248
2249 <Para>
2250 In truth, running Parallel Haskell programs and getting information
2251 out of them (e.g., parallelism profiles) is a battle with the vagaries of
2252 PVM, detailed in the following sections.
2253 </Para>
2254
2255 <Sect2>
2256 <Title>Dummy's guide to using PVM</Title>
2257
2258 <Para>
2259 <IndexTerm><Primary>PVM, how to use</Primary></IndexTerm>
2260 <IndexTerm><Primary>Parallel Haskell&mdash;PVM use</Primary></IndexTerm>
2261 Before you can run a parallel program under PVM, you must set the
2262 required environment variables (PVM's idea, not ours); something like,
2263 probably in your <Literal>.cshrc</Literal> or equivalent:
2264
2265 <ProgramListing>
2266 setenv PVM_ROOT /wherever/you/put/it
2267 setenv PVM_ARCH `$PVM_ROOT/lib/pvmgetarch`
2268 setenv PVM_DPATH $PVM_ROOT/lib/pvmd
2269 </ProgramListing>
2270
2271 </Para>
2272
2273 <Para>
2274 Creating and/or controlling your ``parallel machine'' is a purely-PVM
2275 business; nothing specific to Parallel Haskell.
2276 </Para>
2277
2278 <Para>
2279 You use the <Literal>pvm</Literal><IndexTerm><Primary>pvm command</Primary></IndexTerm> command to start PVM on your
2280 machine.  You can then do various things to control/monitor your
2281 ``parallel machine;'' the most useful being:
2282 </Para>
2283
2284 <Para>
2285 <InformalTable>
2286 <TGroup Cols=2>
2287 <ColSpec Align="Left">
2288 <TBody>
2289
2290 <Row>
2291 <Entry><Literal>Control-D</Literal></Entry>
2292 <Entry>exit <Literal>pvm</Literal>, leaving it running</Entry>
2293 </Row>
2294
2295 <Row>
2296 <Entry><Literal>halt</Literal></Entry>
2297 <Entry>kill off this ``parallel machine'' &amp; exit</Entry>
2298 </Row>
2299
2300 <Row>
2301 <Entry><Literal>add &lt;host&gt;</Literal></Entry>
2302 <Entry>add <Literal>&lt;host&gt;</Literal> as a processor</Entry>
2303 </Row>
2304
2305 <Row>
2306 <Entry><Literal>delete &lt;host&gt;</Literal></Entry>
2307 <Entry>delete <Literal>&lt;host&gt;</Literal></Entry>
2308 </Row>
2309
2310 <Row>
2311 <Entry><Literal>reset</Literal></Entry>
2312 <Entry>kill what's going, but leave PVM up</Entry>
2313 </Row>
2314
2315 <Row>
2316 <Entry><Literal>conf</Literal></Entry>
2317 <Entry>list the current configuration</Entry>
2318 </Row>
2319
2320 <Row>
2321 <Entry><Literal>ps</Literal></Entry>
2322 <Entry>report processes' status</Entry>
2323 </Row>
2324
2325 <Row>
2326 <Entry><Literal>pstat &lt;pid&gt;</Literal></Entry>
2327 <Entry>status of a particular process</Entry>
2328 </Row>
2329
2330 </TBody>
2331 </TGroup>
2332 </InformalTable>
2333 </Para>
2334
2335 <Para>
2336 The PVM documentation can tell you much, much more about <Literal>pvm</Literal>!
2337 </Para>
2338
2339 </Sect2>
2340
2341 <Sect2>
2342 <Title>Parallelism profiles</Title>
2343
2344 <Para>
2345 <IndexTerm><Primary>parallelism profiles</Primary></IndexTerm>
2346 <IndexTerm><Primary>profiles, parallelism</Primary></IndexTerm>
2347 <IndexTerm><Primary>visualisation tools</Primary></IndexTerm>
2348 </Para>
2349
2350 <Para>
2351 With Parallel Haskell programs, we usually don't care about the
2352 results&mdash;only with ``how parallel'' it was!  We want pretty pictures.
2353 </Para>
2354
2355 <Para>
2356 Parallelism profiles (&agrave; la <Literal>hbcpp</Literal>) can be generated with the
2357 <Literal>-q</Literal><IndexTerm><Primary>-q RTS option (concurrent, parallel)</Primary></IndexTerm> RTS option.  The
2358 per-processor profiling info is dumped into files named
2359 <Literal>&lt;full-path&gt;&lt;program&gt;.gr</Literal>.  These are then munged into a PostScript picture,
2360 which you can then display.  For example, to run your program
2361 <Literal>a.out</Literal> on 8 processors, then view the parallelism profile, do:
2362 </Para>
2363
2364 <Para>
2365
2366 <Screen>
2367 % ./a.out +RTS -N8 -q
2368 % grs2gr *.???.gr &#62; temp.gr     # combine the 8 .gr files into one
2369 % gr2ps -O temp.gr              # cvt to .ps; output in temp.ps
2370 % ghostview -seascape temp.ps   # look at it!
2371 </Screen>
2372
2373 </Para>
2374
2375 <Para>
2376 The scripts for processing the parallelism profiles are distributed
2377 in <Literal>ghc/utils/parallel/</Literal>.
2378 </Para>
2379
2380 </Sect2>
2381
2382 <Sect2>
2383 <Title>Other useful info about running parallel programs</Title>
2384
2385 <Para>
2386 The ``garbage-collection statistics'' RTS options can be useful for
2387 seeing what parallel programs are doing.  If you do either
2388 <Literal>+RTS -Sstderr</Literal><IndexTerm><Primary>-Sstderr RTS option</Primary></IndexTerm> or <Literal>+RTS -sstderr</Literal>, then
2389 you'll get mutator, garbage-collection, etc., times on standard
2390 error. The standard error of all PE's other than the `main thread'
2391 appears in <Literal>/tmp/pvml.nnn</Literal>, courtesy of PVM.
2392 </Para>
2393
2394 <Para>
2395 Whether doing <Literal>+RTS -Sstderr</Literal> or not, a handy way to watch
2396 what's happening overall is: <Literal>tail -f /tmp/pvml.nnn</Literal>.
2397 </Para>
2398
2399 </Sect2>
2400
2401 <Sect2 id="parallel-rts-opts">
2402 <Title>RTS options for Concurrent/Parallel Haskell
2403 </Title>
2404
2405 <Para>
2406 <IndexTerm><Primary>RTS options, concurrent</Primary></IndexTerm>
2407 <IndexTerm><Primary>RTS options, parallel</Primary></IndexTerm>
2408 <IndexTerm><Primary>Concurrent Haskell&mdash;RTS options</Primary></IndexTerm>
2409 <IndexTerm><Primary>Parallel Haskell&mdash;RTS options</Primary></IndexTerm>
2410 </Para>
2411
2412 <Para>
2413 Besides the usual runtime system (RTS) options
2414 (<XRef LinkEnd="runtime-control">), there are a few options particularly
2415 for concurrent/parallel execution.
2416 </Para>
2417
2418 <Para>
2419 <VariableList>
2420
2421 <VarListEntry>
2422 <Term><Literal>-N&lt;N&gt;</Literal>:</Term>
2423 <ListItem>
2424 <Para>
2425 <IndexTerm><Primary>-N&lt;N&gt; RTS option (parallel)</Primary></IndexTerm>
2426 (PARALLEL ONLY) Use <Literal>&lt;N&gt;</Literal> PVM processors to run this program;
2427 the default is 2.
2428 </Para>
2429 </ListItem>
2430 </VarListEntry>
2431 <VarListEntry>
2432 <Term><Literal>-C[&lt;us&gt;]</Literal>:</Term>
2433 <ListItem>
2434 <Para>
2435 <IndexTerm><Primary>-C&lt;us&gt; RTS option</Primary></IndexTerm>
2436 Sets the context switch interval to <Literal>&lt;us&gt;</Literal> microseconds.  A context
2437 switch will occur at the next heap allocation after the timer expires.
2438 With <Literal>-C0</Literal> or <Literal>-C</Literal>, context switches will occur as often as
2439 possible (at every heap allocation).  By default, context switches
2440 occur every 10 milliseconds.  Note that many interval timers are only
2441 capable of 10 millisecond granularity, so the default setting may be
2442 the finest granularity possible, short of a context switch at every
2443 heap allocation.
2444 </Para>
2445
2446 <Para>
2447 &lsqb;NOTE: this option currently has no effect (version 4.00).  Context
2448 switches happen when the current heap block is full, i.e. every 4k of
2449 allocation].
2450 </Para>
2451 </ListItem>
2452 </VarListEntry>
2453 <VarListEntry>
2454 <Term><Literal>-q[v]</Literal>:</Term>
2455 <ListItem>
2456 <Para>
2457 <IndexTerm><Primary>-q RTS option</Primary></IndexTerm>
2458 (PARALLEL ONLY) Produce a quasi-parallel profile of thread activity,
2459 in the file <Literal>&lt;program&gt;.qp</Literal>.  In the style of <Literal>hbcpp</Literal>, this profile
2460 records the movement of threads between the green (runnable) and red
2461 (blocked) queues.  If you specify the verbose suboption (<Literal>-qv</Literal>), the
2462 green queue is split into green (for the currently running thread
2463 only) and amber (for other runnable threads).  We do not recommend
2464 that you use the verbose suboption if you are planning to use the
2465 <Literal>hbcpp</Literal> profiling tools or if you are context switching at every heap
2466 check (with <Literal>-C</Literal>).
2467 </Para>
2468 </ListItem>
2469 </VarListEntry>
2470 <VarListEntry>
2471 <Term><Literal>-t&lt;num&gt;</Literal>:</Term>
2472 <ListItem>
2473 <Para>
2474 <IndexTerm><Primary>-t&lt;num&gt; RTS option</Primary></IndexTerm>
2475 (PARALLEL ONLY) Limit the number of concurrent threads per processor
2476 to <Literal>&lt;num&gt;</Literal>.  The default is 32.  Each thread requires slightly over 1K
2477 <Emphasis>words</Emphasis> in the heap for thread state and stack objects.  (For
2478 32-bit machines, this translates to 4K bytes, and for 64-bit machines,
2479 8K bytes.)
2480 </Para>
2481 </ListItem>
2482 </VarListEntry>
2483 <VarListEntry>
2484 <Term><Literal>-d</Literal>:</Term>
2485 <ListItem>
2486 <Para>
2487 <IndexTerm><Primary>-d RTS option (parallel)</Primary></IndexTerm>
2488 (PARALLEL ONLY) Turn on debugging.  It pops up one xterm (or GDB, or
2489 something&hellip;) per PVM processor.  We use the standard <Literal>debugger</Literal>
2490 script that comes with PVM3, but we sometimes meddle with the
2491 <Literal>debugger2</Literal> script.  We include ours in the GHC distribution,
2492 in <Literal>ghc/utils/pvm/</Literal>.
2493 </Para>
2494 </ListItem>
2495 </VarListEntry>
2496 <VarListEntry>
2497 <Term><Literal>-e&lt;num&gt;</Literal>:</Term>
2498 <ListItem>
2499 <Para>
2500 <IndexTerm><Primary>-e&lt;num&gt; RTS option (parallel)</Primary></IndexTerm>
2501 (PARALLEL ONLY) Limit the number of pending sparks per processor to
2502 <Literal>&lt;num&gt;</Literal>. The default is 100. A larger number may be appropriate if
2503 your program generates large amounts of parallelism initially.
2504 </Para>
2505 </ListItem>
2506 </VarListEntry>
2507 <VarListEntry>
2508 <Term><Literal>-Q&lt;num&gt;</Literal>:</Term>
2509 <ListItem>
2510 <Para>
2511 <IndexTerm><Primary>-Q&lt;num&gt; RTS option (parallel)</Primary></IndexTerm>
2512 (PARALLEL ONLY) Set the size of packets transmitted between processors
2513 to <Literal>&lt;num&gt;</Literal>. The default is 1024 words. A larger number may be
2514 appropriate if your machine has a high communication cost relative to
2515 computation speed.
2516 </Para>
2517 </ListItem>
2518 </VarListEntry>
2519 </VariableList>
2520 </Para>
2521
2522 </Sect2>
2523
2524 </Sect1>
2525
2526 &runtime
2527 &debug
2528
2529 </Chapter>