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 GHC is a command-line compiler: in order to compile a Haskell program,
   9 GHC must be invoked on the source file(s) by typing a command to the
  10 shell.  The steps involved in compiling a program can be automated
  11 using the <command>make</command> tool (this is especially useful if the program
  12 consists of multiple source files which depend on each other).  This
  13 section describes how to use GHC from the command-line.
  14 </para>
  15
  16 <Sect1 id="command-line-structure">
  17 <title>Overall command-line structure
  18 </title>
  19
  20 <para>
  21 <IndexTerm><Primary>structure, command-line</Primary></IndexTerm>
  22 <IndexTerm><Primary>command-line structure</Primary></IndexTerm>
  23 </para>
  24
  25 <para>
  26 An invocation of GHC takes the following form:
  27 </para>
  28
  29 <para>
  30
  31 <Screen>
  32 ghc [argument...]
  33 </Screen>
  34
  35 </para>
  36
  37 <para>
  38 Command-line arguments are either options or file names.
  39 </para>
  40
  41 <para>
  42 Command-line options begin with <literal>-</literal>.  They may <emphasis>not</emphasis> be
  43 grouped: <option>-vO</option> is different from <option>-v -O</option>.  Options need not
  44 precede filenames: e.g., <command>ghc *.o -o foo</command>.  All options are
  45 processed and then applied to all files; you cannot, for example, invoke
  46 <command>ghc -c -O1 Foo.hs -O2 Bar.hs</command> to apply different optimisation
  47 levels to the files <filename>Foo.hs</filename> and <filename>Bar.hs</filename>.  For conflicting
  48 options, e.g., <option>-c -S</option>, we reserve the right to do anything we
  49 want.  (Usually, the last one applies.)
  50 </para>
  51
  52 </Sect1>
  53
  54 <Sect1 id="file-suffixes">
  55 <title>Meaningful file suffixes
  56 </title>
  57
  58 <para>
  59 <IndexTerm><Primary>suffixes, file</Primary></IndexTerm>
  60 <IndexTerm><Primary>file suffixes for GHC</Primary></IndexTerm>
  61 </para>
  62
  63 <para>
  64 File names with &ldquo;meaningful&rdquo; suffixes (e.g., <filename>.lhs</filename> or <filename>.o</filename>)
  65 cause the &ldquo;right thing&rdquo; to happen to those files.
  66 </para>
  67
  68 <para>
  69 <VariableList>
  70
  71 <VarListEntry>
  72 <Term><filename>.lhs</filename>:</Term>
  73 <ListItem>
  74 <para>
  75 <IndexTerm><Primary>lhs suffix</Primary></IndexTerm>
  76 A &ldquo;literate Haskell&rdquo; module.
  77 </para>
  78 </ListItem>
  79 </VarListEntry>
  80 <VarListEntry>
  81 <Term><filename>.hs</filename>:</Term>
  82 <ListItem>
  83 <para>
  84 A not-so-literate Haskell module.
  85 </para>
  86 </ListItem>
  87 </VarListEntry>
  88 <VarListEntry>
  89 <Term><filename>.hi</filename>:</Term>
  90 <ListItem>
  91 <para>
  92 A Haskell interface file, probably compiler-generated.
  93 </para>
  94 </ListItem>
  95 </VarListEntry>
  96 <VarListEntry>
  97 <Term><filename>.hc</filename>:</Term>
  98 <ListItem>
  99 <para>
 100 Intermediate C file produced by the Haskell compiler.
 101 </para>
 102 </ListItem>
 103 </VarListEntry>
 104 <VarListEntry>
 105 <Term><filename>.c</filename>:</Term>
 106 <ListItem>
 107 <para>
 108 A C&nbsp;file not produced by the Haskell compiler.
 109 </para>
 110 </ListItem>
 111 </VarListEntry>
 112 <VarListEntry>
 113 <Term><filename>.s</filename>:</Term>
 114 <ListItem>
 115 <para>
 116 An assembly-language source file, usually
 117 produced by the compiler.
 118 </para>
 119 </ListItem>
 120 </VarListEntry>
 121 <VarListEntry>
 122 <Term><filename>.o</filename>:</Term>
 123 <ListItem>
 124 <para>
 125 An object file, produced by an assembler.
 126 </para>
 127 </ListItem>
 128 </VarListEntry>
 129 </VariableList>
 130 </para>
 131
 132 <para>
 133 Files with other suffixes (or without suffixes) are passed straight
 134 to the linker.
 135 </para>
 136
 137 </Sect1>
 138
 139   <sect1 id="options-help">
 140     <title>Help and verbosity options</title>
 141
 142     <IndexTerm><Primary>help options</Primary></IndexTerm>
 143     <IndexTerm><Primary>verbosity options</Primary></IndexTerm>
 144
 145     <variablelist>
 146       <varlistentry>
 147         <term><literal>-help</literal></term>
 148         <term><literal>-?</literal></term>
 149         <indexterm><primary><literal>-?</literal></primary></indexterm>
 150         <indexterm><primary><literal>-help</literal></primary></indexterm>
 151         <listitem>
 152           <para>Cause GHC to spew a long usage message to standard
 153           output and then exit.</para>
 154         </listitem>
 155       </varlistentry>
 156
 157       <varlistentry>
 158         <term><literal>-v</literal></term>
 159         <indexterm><primary><literal>-v</literal></primary></indexterm>
 160         <listitem>
 161           <para>The <option>-v</option> option makes GHC
 162           <emphasis>verbose</emphasis>: it reports its version number
 163           and shows (on stderr) exactly how it invokes each phase of
 164           the compilation system.  Moreover, it passes the
 165           <option>-v</option> flag to most phases; each reports its
 166           version number (and possibly some other information).</para>
 167
 168           <para>Please, oh please, use the <option>-v</option> option
 169           when reporting bugs!  Knowing that you ran the right bits in
 170           the right order is always the first thing we want to
 171           verify.</para>
 172         </listitem>
 173       </varlistentry>
 174
 175       <varlistentry>
 176         <term><literal>-v</literal><replaceable>n</replaceable></term>
 177         <indexterm><primary><option>-v</option></primary></indexterm>
 178         <listitem>
 179           <para>To provide more control over the compiler's verbosity,
 180           the <option>-v</option> flag takes an optional numeric
 181           argument.  Specifying <option>-v</option> on its own is
 182           equivalent to <option>-v3</option>, and the other levels
 183           have the following meanings:</para>
 184
 185           <variablelist>
 186             <varlistentry>
 187               <term><literal>-v0</literal></term>
 188               <listitem>
 189                 <para>Disable all non-essential messages (this is the
 190                 default).</para>
 191               </listitem>
 192             </varlistentry>
 193
 194             <varlistentry>
 195               <term><literal>-v1</literal></term>
 196               <listitem>
 197                 <para>Minimal verbosity: print one line per
 198                 compilation (this is the default when
 199                 <option>--make</option> or
 200                 <option>--interactive</option> is on).</para>
 201               </listitem>
 202             </varlistentry>
 203
 204             <varlistentry>
 205               <term><literal>-v2</literal></term>
 206               <listitem>
 207                 <para>Print the name of each compilation phase as it
 208                 is executed. (equivalent to
 209                 <option>-dshow-passes</option>).</para>
 210               </listitem>
 211             </varlistentry>
 212
 213             <varlistentry>
 214               <term><literal>-v3</literal></term>
 215               <listitem>
 216                 <para>The same as <option>-v2</option>, except that in
 217                 addition the full command line (if appropriate) for
 218                 each compilation phase is also printed.</para>
 219               </listitem>
 220             </varlistentry>
 221
 222             <varlistentry>
 223               <term><literal>-v4</literal></term>
 224               <listitem>
 225                 <para>The same as <option>-v3</option> except that the
 226                 intermediate program representation after each
 227                 compilation phase is also printed (excluding
 228                 preprocessed and C/assembly files).</para>
 229               </listitem>
 230             </varlistentry>
 231           </variablelist>
 232         </listitem>
 233       </varlistentry>
 234
 235       <varlistentry>
 236         <term><literal>--version</literal></term>
 237         <indexterm><primary><literal>--version</literal></primary></indexterm>
 238         <listitem>
 239           <para>Print a one-line string including GHC's version number.</para>
 240         </listitem>
 241       </varlistentry>
 242
 243       <varlistentry>
 244         <term><literal>--numeric-version</literal></term>
 245         <indexterm><primary><literal>--numeric-version</literal></primary></indexterm>
 246         <listitem>
 247           <para>Print GHC's numeric version number only.</para>
 248         </listitem>
 249       </varlistentry>
 250     </variablelist>
 251   </sect1>
 252
 253   <Sect1 id="options-order">
 254     <title>Running the right phases in the right order</title>
 255
 256     <indexterm><primary>order of passes in GHC</primary></indexterm>
 257     <indexterm><primary>pass ordering in GHC</primary></indexterm>
 258
 259
 260     <para>The basic task of the <command>ghc</command> driver is to
 261     run each input file through the right phases (compiling, linking,
 262     etc.).</para>
 263
 264     <para>The first phase to run is determined by the input-file
 265     suffix, and the last phase is determined by a flag.  If no
 266     relevant flag is present, then go all the way through linking.
 267     This table summarises:</para>
 268
 269 <InformalTable>
 270 <TGroup Cols="4">
 271 <ColSpec Align="Left">
 272 <ColSpec Align="Left">
 273 <ColSpec Align="Left">
 274 <ColSpec Align="Left">
 275 <TBody>
 276
 277 <Row>
 278 <Entry>Phase of the compilation system</Entry>
 279 <Entry>Suffix saying &ldquo;start here&rdquo;</Entry>
 280 <Entry>Flag saying &ldquo;stop after&rdquo;</Entry>
 281 <Entry>(suffix of) output file</Entry>
 282 </Row>
 283
 284 <Row>
 285 <Entry>
 286 literate pre-processor </Entry>
 287 <Entry> .lhs </Entry>
 288 <Entry> - </Entry>
 289 <Entry> .hs </Entry>
 290 </Row>
 291 <Row>
 292 <Entry>
 293 C pre-processor (opt.) </Entry>
 294 <Entry> .hs (with <literal>-cpp</literal>) </Entry>
 295 <Entry> -E </Entry>
 296 <Entry> .hspp </Entry>
 297 </Row>
 298 <Row>
 299 <Entry>
 300 Haskell compiler </Entry>
 301 <Entry> .hs </Entry>
 302 <Entry> -C, -S </Entry>
 303 <Entry> .hc, .s </Entry>
 304 </Row>
 305 <Row>
 306 <Entry>
 307 C compiler (opt.) </Entry>
 308 <Entry> .hc or .c </Entry>
 309 <Entry> -S </Entry>
 310 <Entry> .s </Entry>
 311 </Row>
 312 <Row>
 313 <Entry>
 314 assembler </Entry>
 315 <Entry> .s </Entry>
 316 <Entry> -c </Entry>
 317 <Entry> .o </Entry>
 318 </Row>
 319 <Row>
 320 <Entry>
 321 linker </Entry>
 322 <Entry> other </Entry>
 323 <Entry> - </Entry>
 324 <Entry> a.out </Entry>
 325 </Row>
 326 </TBody>
 327 </TGroup>
 328 </InformalTable>
 329
 330 <IndexTerm><Primary>-C option</Primary></IndexTerm>
 331 <IndexTerm><Primary>-S option</Primary></IndexTerm>
 332 <IndexTerm><Primary>-c option</Primary></IndexTerm>
 333
 334 <para>
 335 Thus, a common invocation would be: <command>ghc -c Foo.hs</command>
 336 </para>
 337
 338 <para>
 339 Note: What the Haskell compiler proper produces depends on whether a
 340 native-code generator is used (producing assembly language) or not
 341 (producing C).
 342 </para>
 343
 344     <para>NOTE: the option <option>-E</option><IndexTerm><Primary>-E
 345     option</Primary></IndexTerm> runs just the pre-processing passes
 346     of the compiler, dumping the result in a file.  Note that this
 347     differs from all GHCs prior to version 4.11, in which the result
 348     was dumped to the standard output.  If used in conjunction with
 349     -cpp, the output is the code blocks of the original (literal)
 350     source after having put it through the grinder that is the C
 351     pre-processor. Sans <option>-cpp</option>, the output is the
 352     de-litted version of the original source.</para>
 353
 354     <para>The following options also affect which phases get run:</para>
 355
 356     <variablelist>
 357       <varlistentry>
 358         <term><option>-cpp</option></term>
 359         <indexterm><primary><option>-cpp</option></primary></indexterm>
 360         <listitem>
 361           <para>Run the C pre-processor on the Haskell source before
 362           compiling it.  See <xref linkend="c-pre-processor"> for more
 363           details.</para>
 364         </listitem>
 365       </varlistentry>
 366
 367       <varlistentry>
 368         <term><option>-fasm</option></term>
 369         <indexterm><primary><option>-fasm</option></primary></indexterm>
 370         <listitem>
 371           <para>Use GHC's native code generator rather than compiling
 372           via C.  This will compile faster (up to twice as fast), but
 373           may produce code that is slightly slower than compiling via
 374           C.  <option>-fasm</option> is the default when optimisation
 375           is off (see <xref linkend="options-optimise">).</para>
 376         </listitem>
 377       </varlistentry>
 378
 379       <varlistentry>
 380         <term><option>-fvia-C</option></term>
 381         <indexterm><primary><option>-fvia-C</option></primary>
 382         </indexterm>
 383         <listitem>
 384           <para>Compile via C instead of using the native code
 385           generator.  This is default for optimised compilations, and
 386           on architectures for which GHC doesn't have a native code
 387           generator.</para>
 388         </listitem>
 389       </varlistentry>
 390     </variablelist>
 391   </sect1>
 392
 393   <sect1 id="options-output">
 394     <title>Re-directing the compilation output(s)</title>
 395
 396     <indexterm><primary>output-directing options</primary></indexterm>
 397     <indexterm><primary>redirecting compilation output</primary></indexterm>
 398
 399
 400     <variablelist>
 401       <varlistentry>
 402         <term><literal>-o</literal></term>
 403         <indexterm><primary><literal>-o</literal></primary></indexterm>
 404         <listitem>
 405           <para>GHC's compiled output normally goes into a
 406           <filename>.hc</filename>, <filename>.o</filename>, etc.,
 407           file, depending on the last-run compilation phase.  The
 408           option <option>-o foo</option><IndexTerm><Primary>-o
 409           option</Primary></IndexTerm> re-directs the output of that
 410           last-run phase to file <filename>foo</filename>.</para>
 411
 412           <para>Note: this &ldquo;feature&rdquo; can be
 413           counterintuitive: <command>ghc -C -o foo.o foo.hs</command>
 414           will put the intermediate C code in the file
 415           <filename>foo.o</filename>, name notwithstanding!</para>
 416         </listitem>
 417       </varlistentry>
 418
 419       <varlistentry>
 420         <term><literal>-odir</literal></term>
 421         <indexterm><primary><literal>-odir</literal></primary></indexterm>
 422         <listitem>
 423           <para>The <option>-o</option> option isn't of much use if
 424           you have <emphasis>several</emphasis> input files&hellip;
 425           Non-interface output files are normally put in the same
 426           directory as their corresponding input file came from.  You
 427           may specify that they be put in another directory using the
 428           <option>-odir &lt;dir&gt;</option><IndexTerm><Primary>-odir
 429           &lt;dir&gt; option</Primary></IndexTerm> (the &ldquo;Oh,
 430           dear&rdquo; option).  For example:</para>
 431
 432 <Screen>
 433 % ghc -c parse/Foo.hs parse/Bar.hs gurgle/Bumble.hs -odir `arch`
 434 </Screen>
 435
 436           <para>The output files, <filename>Foo.o</filename>,
 437           <filename>Bar.o</filename>, and
 438           <filename>Bumble.o</filename> would be put into a
 439           subdirectory named after the architecture of the executing
 440           machine (<filename>sun4</filename>,
 441           <filename>mips</filename>, etc).  The directory must already
 442           exist; it won't be created.</para>
 443
 444           <para>Note that the <option>-odir</option> option does
 445           <emphasis>not</emphasis> affect where the interface files
 446           are put.  In the above example, they would still be put in
 447           <filename>parse/Foo.hi</filename>,
 448           <filename>parse/Bar.hi</filename>, and
 449           <filename>gurgle/Bumble.hi</filename>.</para>
 450         </listitem>
 451       </varlistentry>
 452
 453       <varlistentry>
 454         <term><literal>-ohi</literal></term>
 455         <indexterm><primary><literal>-ohi</literal></primary></indexterm>
 456         <listitem>
 457           <para></para>
 458         </listitem>
 459       </varlistentry>
 460
 461       <varlistentry>
 462         <term><literal>-osuf</literal></term>
 463         <term><literal>-hisuf</literal></term>
 464         <indexterm><primary><literal>-osuf</literal></primary></indexterm>
 465         <indexterm><primary><literal>-hisuf</literal></primary></indexterm>
 466         <listitem>
 467           <para>EXOTICA: The <option>-osuf
 468           &lt;suffix&gt;</option><IndexTerm><Primary>-osuf
 469           &lt;suffix&gt; option</Primary></IndexTerm> will change the
 470           <filename>.o</filename> file suffix for object files to
 471           whatever you specify.  (We use this in compiling the
 472           prelude.).</para>
 473
 474           <para>Similarly, the <option>-hisuf
 475           &lt;suffix&gt;</option><IndexTerm><Primary>-hisuf
 476           &lt;suffix&gt; option</Primary></IndexTerm> will change the
 477           <filename>.hi</filename> file suffix for non-system
 478           interface files (see <XRef LinkEnd="hi-options">).</para>
 479
 480           <para>The <option>-hisuf</option>/<option>-osuf</option>
 481           game is useful if you want to compile a program with both
 482           GHC and HBC (say) in the same directory.  Let HBC use the
 483           standard <filename>.hi</filename>/<filename>.o</filename>
 484           suffixes; add <option>-hisuf g&lowbar;hi -osuf
 485           g&lowbar;o</option> to your <command>make</command> rule for
 486           GHC compiling&hellip;</para>
 487         </listitem>
 488       </varlistentry>
 489     </variablelist>
 490
 491     <sect2 id="keeping-intermediates">
 492       <title>Keeping Intermediate Files</title>
 493       <indexterm><primary>intermediate files, saving</primary>
 494       </indexterm>
 495       <indexterm><primary><literal>.hc</literal> files, saving</primary>
 496       </indexterm>
 497       <indexterm><primary><literal>.s</literal> files, saving</primary>
 498       </indexterm>
 499
 500
 501       <para>The following options are useful for keeping certain
 502       intermediate files around, when normally GHC would throw these
 503       away after compilation:</para>
 504
 505       <variablelist>
 506         <varlistentry>
 507           <term><literal>-keep-hc-files</literal></term>
 508           <indexterm>
 509             <primary><literal>-keep-hc-files</literal></primary>
 510           </indexterm>
 511           <listitem>
 512             <para>Keep intermediate <literal>.hc</literal> files when
 513             doing <literal>.hs</literal>-to-<literal>.o</literal>
 514             compilations via C (NOTE: <literal>.hc</literal> files
 515             aren't generated when using the native code generator, you
 516             may need to use <literal>-fvia-C</literal> to force them
 517             to be produced).</para>
 518           </listitem>
 519         </varlistentry>
 520
 521         <varlistentry>
 522           <term><literal>-keep-s-files</literal></term>
 523           <indexterm>
 524             <primary><literal>-keep-s-files</literal></primary>
 525           </indexterm>
 526           <listitem>
 527             <para>Keep intermediate <literal>.s</literal> files.</para>
 528           </listitem>
 529         </varlistentry>
 530
 531         <varlistentry>
 532           <term><literal>-keep-raw-s-files</literal></term>
 533           <indexterm>
 534             <primary><literal>-keep-raw-s-files</literal></primary>
 535           </indexterm>
 536           <listitem>
 537             <para>Keep intermediate <literal>.raw-s</literal> files.
 538             These are the direct output from the C compiler, before
 539             GHC does &ldquo;assembly mangling&rdquo; to produce the
 540             <literal>.s</literal> file.  Again, these are not produced
 541             when using the native code generator.</para>
 542           </listitem>
 543         </varlistentry>
 544
 545         <varlistentry>
 546           <term><literal>-keep-tmp-files</literal></term>
 547           <indexterm>
 548             <primary><literal>-keep-tmp-files</literal></primary>
 549           </indexterm>
 550           <indexterm>
 551             <primary>temporary files</primary>
 552             <secondary>keeping</secondary>
 553           </indexterm>
 554           <listitem>
 555             <para>Instructs the GHC driver not to delete any of its
 556             temporary files, which it normally keeps in
 557             <literal>/tmp</literal> (or possibly elsewhere; see <xref
 558             linkend="temp-files">).  Running GHC with
 559             <literal>-v</literal> will show you what temporary files
 560             were generated along the way.</para>
 561           </listitem>
 562         </varlistentry>
 563       </variablelist>
 564     </sect2>
 565
 566     <sect2 id="temp-files">
 567       <title>Redirecting temporary files</title>
 568
 569       <indexterm>
 570         <primary>temporary files</primary>
 571         <secondary>redirecting</secondary>
 572       </indexterm>
 573
 574       <variablelist>
 575         <varlistentry>
 576           <term><literal>-tmpdir</literal></term>
 577           <indexterm><primary><literal>-tmpdir</literal></primary></indexterm>
 578           <listitem>
 579             <para>If you have trouble because of running out of space
 580             in <filename>/tmp</filename> (or wherever your
 581             installation thinks temporary files should go), you may
 582             use the <option>-tmpdir
 583             &lt;dir&gt;</option><IndexTerm><Primary>-tmpdir
 584             &lt;dir&gt; option</Primary></IndexTerm> option to specify
 585             an alternate directory.  For example, <option>-tmpdir
 586             .</option> says to put temporary files in the current
 587             working directory.</para>
 588
 589             <para>Alternatively, use your <Constant>TMPDIR</Constant>
 590             environment variable.<IndexTerm><Primary>TMPDIR
 591             environment variable</Primary></IndexTerm> Set it to the
 592             name of the directory where temporary files should be put.
 593             GCC and other programs will honour the
 594             <Constant>TMPDIR</Constant> variable as well.</para>
 595
 596             <para>Even better idea: Set the
 597             <Constant>DEFAULT_TMPDIR</Constant> make variable when
 598             building GHC, and never worry about
 599             <Constant>TMPDIR</Constant> again. (see the build
 600             documentation).</para>
 601           </listitem>
 602         </varlistentry>
 603       </variablelist>
 604     </sect2>
 605
 606   </sect1>
 607
 608   <sect1 id="options-sanity">
 609     <title>Warnings and sanity-checking</title>
 610
 611     <indexterm><primary>sanity-checking options</primary></indexterm>
 612     <indexterm><primary>warnings</primary></indexterm>
 613
 614
 615     <para>GHC has a number of options that select which types of
 616     non-fatal error messages, otherwise known as warnings, can be
 617     generated during compilation.  By default, you get a standard set
 618     of warnings which are generally likely to indicate bugs in your
 619     program.  These are:
 620     <option>-fwarn-overlpapping-patterns</option>,
 621     <option>-fwarn-deprecations</option>,
 622     <option>-fwarn-duplicate-exports</option>,
 623     <option>-fwarn-missing-fields</option>, and
 624     <option>-fwarn-missing-methods</option>.  The following flags are
 625     simple ways to select standard &ldquo;packages&rdquo; of warnings:
 626     </para>
 627
 628     <VariableList>
 629
 630       <varlistentry>
 631         <term><option>-W</option>:</term>
 632         <listitem>
 633           <IndexTerm><Primary>-W option</Primary></IndexTerm>
 634           <para>Provides the standard warnings plus
 635           <option>-fwarn-incomplete-patterns</option>,
 636           <option>-fwarn-unused-matches</option>,
 637           <option>-fwarn-unused-imports</option> and
 638           <option>-fwarn-unused-binds</option>.</para>
 639         </listitem>
 640       </varlistentry>
 641
 642       <varlistentry>
 643         <term><option>-w</option>:</term>
 644         <listitem>
 645           <IndexTerm><Primary>-w option</Primary></IndexTerm>
 646           <para>Turns off all warnings, including the standard ones.</para>
 647         </listitem>
 648       </varlistentry>
 649
 650       <varlistentry>
 651         <term><option>-Wall</option>:</term>
 652         <listitem>
 653           <indexterm><primary>-Wall option</primary></indexterm>
 654           <para>Turns on all warning options.</para>
 655         </listitem>
 656       </varlistentry>
 657
 658     </variablelist>
 659
 660     <para>The full set of warning options is described below.  To turn
 661     off any warning, simply give the corresponding
 662     <option>-fno-warn-...</option> option on the command line.</para>
 663
 664     <variablelist>
 665
 666       <varlistentry>
 667         <term><option>-fwarn-deprecations</option>:</term>
 668         <listitem>
 669           <indexterm><primary><option>-fwarn-deprecations</option></primary>
 670           </indexterm>
 671           <indexterm><primary>deprecations</primary></indexterm>
 672           <para>Causes a warning to be emitted when a deprecated
 673           function or type is used.  Entities can be marked as
 674           deprecated using a pragma, see <xref
 675           linkend="deprecated-pragma">.</para>
 676         </listitem>
 677       </varlistentry>
 678
 679       <varlistentry>
 680         <term><option>-fwarn-duplicate-exports</option>:</term>
 681         <listitem>
 682           <indexterm><primary>-fwarn-duplicate-exports option</primary></indexterm>
 683           <indexterm><primary>duplicate exports, warning</primary></indexterm>
 684           <indexterm><primary>export lists, duplicates</primary></indexterm>
 685
 686           <para>Have the compiler warn about duplicate entries in
 687           export lists. This is useful information if you maintain
 688           large export lists, and want to avoid the continued export
 689           of a definition after you've deleted (one) mention of it in
 690           the export list.</para>
 691
 692           <para>This option is on by default.</para>
 693         </listitem>
 694       </varlistentry>
 695
 696       <varlistentry>
 697         <term><option>-fwarn-hi-shadowing</option>:</term>
 698         <listitem>
 699           <indexterm><primary>-fwarn-hi-shadowing option</primary></indexterm>
 700           <indexterm><primary>shadowing</primary>
 701             <secondary>interface files</secondary></indexterm>
 702
 703           <para>Causes the compiler to emit a warning when a module or
 704           interface file in the current directory is shadowing one
 705           with the same module name in a library or other
 706           directory.</para>
 707         </listitem>
 708       </varlistentry>
 709
 710       <varlistentry>
 711         <term><option>-fwarn-incomplete-patterns</option>:</term>
 712         <listitem>
 713           <indexterm><primary>-fwarn-incomplete-patterns option</primary></indexterm>
 714           <indexterm><primary>incomplete patterns, warning</primary></indexterm>
 715           <indexterm><primary>patterns, incomplete</primary></indexterm>
 716
 717           <para>Similarly for incomplete patterns, the function
 718           <function>g</function> below will fail when applied to
 719           non-empty lists, so the compiler will emit a warning about
 720           this when <option>-fwarn-incomplete-patterns</option> is
 721           enabled.</para>
 722
 723 <programlisting>
 724 g [] = 2
 725 </programlisting>
 726
 727           <para>This option isn't enabled be default because it can be
 728           a bit noisy, and it doesn't always indicate a bug in the
 729           program.  However, it's generally considered good practice
 730           to cover all the cases in your functions.</para>
 731         </listitem>
 732       </varlistentry>
 733
 734       <varlistentry>
 735         <term><option>-fwarn-missing-fields</option>:</term>
 736         <listitem>
 737           <indexterm><primary>-fwarn-missing-fields option</primary></indexterm>
 738           <indexterm><primary>missing fields, warning</primary></indexterm>
 739           <indexterm><primary>fields, missing</primary></indexterm>
 740
 741           <para>This option is on by default, and warns you whenever
 742           the construction of a labelled field constructor isn't
 743           complete, missing initializers for one or more fields. While
 744           not an error (the missing fields are initialised with
 745           bottoms), it is often an indication of a programmer error.</para>
 746         </listitem>
 747       </varlistentry>
 748
 749       <varlistentry>
 750         <term><option>-fwarn-missing-methods</option>:</term>
 751         <listitem>
 752           <indexterm><primary>-fwarn-missing-methods option</primary></indexterm>
 753           <indexterm><primary>missing methods, warning</primary></indexterm>
 754           <indexterm><primary>methods, missing</primary></indexterm>
 755
 756           <para>This option is on by default, and warns you whenever
 757           an instance declaration is missing one or more methods, and
 758           the corresponding class declaration has no default
 759           declaration for them.</para>
 760         </listitem>
 761       </varlistentry>
 762
 763       <varlistentry>
 764         <term><option>-fwarn-missing-signatures</option>:</term>
 765         <listitem>
 766           <indexterm><primary>-fwarn-missing-signatures option</primary></indexterm>
 767           <indexterm><primary>type signatures, missing</primary></indexterm>
 768
 769           <para>If you would like GHC to check that every top-level
 770           function/value has a type signature, use the
 771           <option>-fwarn-missing-signatures</option> option.  This
 772           option is off by default.</para>
 773         </listitem>
 774       </varlistentry>
 775
 776       <varlistentry>
 777         <term><option>-fwarn-name-shadowing</option>:</term>
 778         <listitem>
 779           <indexterm><primary>-fwarn-name-shadowing option</primary></indexterm>
 780           <indexterm><primary>shadowing, warning</primary></indexterm>
 781
 782           <para>This option causes a warning to be emitted whenever an
 783           inner-scope value has the same name as an outer-scope value,
 784           i.e. the inner value shadows the outer one.  This can catch
 785           typographical errors that turn into hard-to-find bugs, e.g.,
 786           in the inadvertent cyclic definition <literal>let x = ... x
 787           ... in</literal>.</para>
 788
 789           <para>Consequently, this option does
 790           <emphasis>will</emphasis> complain about cyclic recursive
 791           definitions.</para>
 792         </listitem>
 793       </varlistentry>
 794
 795       <varlistentry>
 796         <term><option>-fwarn-overlapping-patterns</option>:</term>
 797         <indexterm><primary>-fwarn-overlapping-patterns option</primary></indexterm>
 798         <indexterm><primary>overlapping patterns, warning</primary></indexterm>
 799         <indexterm><primary>patterns, overlapping</primary></indexterm>
 800         <listitem>
 801           <para>By default, the compiler will warn you if a set of
 802           patterns are overlapping, i.e.,</para>
 803
 804 <programlisting>
 805 f :: String -&#62; Int
 806 f []     = 0
 807 f (_:xs) = 1
 808 f "2"    = 2
 809 </programlisting>
 810
 811           <para>where the last pattern match in <Function>f</Function>
 812           won't ever be reached, as the second pattern overlaps
 813           it. More often than not, redundant patterns is a programmer
 814           mistake/error, so this option is enabled by default.</para>
 815         </listitem>
 816       </varlistentry>
 817
 818       <varlistentry>
 819         <term><option>-fwarn-simple-patterns</option>:</term>
 820         <listitem>
 821           <indexterm><primary><option>-fwarn-simple-patterns</option></primary>
 822           </indexterm>
 823           <para>Causes the compiler to warn about lambda-bound
 824           patterns that can fail, eg. <literal>\(x:xs)->...</literal>.
 825           Normally, these aren't treated as incomplete patterns by
 826           <option>-fwarn-incomplete-patterns</option>.</para>
 827         </listitem>
 828       </varlistentry>
 829
 830       <varlistentry>
 831         <term><option>-fwarn-type-defaults</option>:</term>
 832         <listitem>
 833           <indexterm><primary>-fwarn-type-defaults option</primary></indexterm>
 834           <indexterm><primary>defaulting mechanism, warning</primary></indexterm>
 835           <para>Have the compiler warn/inform you where in your source
 836           the Haskell defaulting mechanism for numeric types kicks
 837           in. This is useful information when converting code from a
 838           context that assumed one default into one with another,
 839           e.g., the `default default' for Haskell 1.4 caused the
 840           otherwise unconstrained value <Constant>1</Constant> to be
 841           given the type <literal>Int</literal>, whereas Haskell 98
 842           defaults it to <literal>Integer</literal>.  This may lead to
 843           differences in performance and behaviour, hence the
 844           usefulness of being non-silent about this.</para>
 845
 846           <para>This warning is off by default.</para>
 847         </listitem>
 848       </varlistentry>
 849
 850       <varlistentry>
 851         <term><option>-fwarn-unused-binds</option>:</term>
 852         <listitem>
 853           <indexterm><primary>-fwarn-unused-binds option</primary></indexterm>
 854           <indexterm><primary>unused binds, warning</primary></indexterm>
 855           <indexterm><primary>binds, unused</primary></indexterm>
 856           <para>Report any function definitions (and local bindings)
 857           which are unused.  For top-level functions, the warning is
 858           only given if the binding is not exported.</para>
 859         </listitem>
 860       </varlistentry>
 861
 862       <varlistentry>
 863         <term><option>-fwarn-unused-imports</option>:</term>
 864         <listitem>
 865           <indexterm><primary>-fwarn-unused-imports option</primary></indexterm>
 866           <indexterm><primary>unused imports, warning</primary></indexterm>
 867           <indexterm><primary>imports, unused</primary></indexterm>
 868
 869           <para>Report any objects that are explicitly imported but
 870           never used.</para>
 871         </listitem>
 872       </varlistentry>
 873
 874       <varlistentry>
 875         <term><option>-fwarn-unused-matches</option>:</term>
 876         <listitem>
 877           <indexterm><primary>-fwarn-unused-matches option</primary></indexterm>
 878           <indexterm><primary>unused matches, warning</primary></indexterm>
 879           <indexterm><primary>matches, unused</primary></indexterm>
 880
 881           <para>Report all unused variables which arise from pattern
 882           matches, including patterns consisting of a single variable.
 883           For instance <literal>f x y = []</literal> would report
 884           <VarName>x</VarName> and <VarName>y</VarName> as unused.  To
 885           eliminate the warning, all unused variables can be replaced
 886           with wildcards.</para>
 887         </listitem>
 888       </varlistentry>
 889
 890     </VariableList>
 891
 892     <para>If you're feeling really paranoid, the
 893     <option>-dcore-lint</option> option<indexterm><primary>-dcore-lint
 894     option</primary></indexterm> is a good choice.  It turns on
 895     heavyweight intra-pass sanity-checking within GHC.  (It checks
 896     GHC's sanity, not yours.)</para>
 897
 898   </sect1>
 899
 900   &separate;
 901   &packages;
 902
 903   <sect1 id="options-optimise">
 904     <title>Optimisation (code improvement)</title>
 905
 906     <indexterm><primary>optimisation</primary></indexterm>
 907     <indexterm><primary>improvement, code</primary></indexterm>
 908
 909     <para>The <option>-O*</option> options specify convenient
 910     &ldquo;packages&rdquo; of optimisation flags; the
 911     <option>-f*</option> options described later on specify
 912     <emphasis>individual</emphasis> optimisations to be turned on/off;
 913     the <option>-m*</option> options specify
 914     <emphasis>machine-specific</emphasis> optimisations to be turned
 915     on/off.</para>
 916
 917     <sect2 id="optimise-pkgs">
 918       <title><option>-O*</option>: convenient &ldquo;packages&rdquo; of optimisation flags.</title>
 919
 920       <para>There are <emphasis>many</emphasis> options that affect
 921       the quality of code produced by GHC.  Most people only have a
 922       general goal, something like &ldquo;Compile quickly&rdquo; or
 923       &ldquo;Make my program run like greased lightning.&rdquo; The
 924       following &ldquo;packages&rdquo; of optimisations (or lack
 925       thereof) should suffice.</para>
 926
 927       <para>Once you choose a <option>-O*</option>
 928       &ldquo;package,&rdquo; stick with it&mdash;don't chop and
 929       change.  Modules' interfaces <emphasis>will</emphasis> change
 930       with a shift to a new <option>-O*</option> option, and you may
 931       have to recompile a large chunk of all importing modules before
 932       your program can again be run safely (see <XRef
 933       LinkEnd="recomp">).</para>
 934
 935       <variablelist>
 936
 937         <varlistentry>
 938           <term>No <option>-O*</option>-type option specified:</term>
 939           <indexterm><primary>-O* not specified</primary></indexterm>
 940           <listitem>
 941             <para>This is taken to mean: &ldquo;Please compile
 942             quickly; I'm not over-bothered about compiled-code
 943             quality.&rdquo; So, for example: <command>ghc -c
 944             Foo.hs</command></para>
 945           </listitem>
 946         </varlistentry>
 947
 948         <varlistentry>
 949           <term><option>-O0</option>:</term>
 950           <indexterm><primary><option>-O0</option></primary></indexterm>
 951           <listitem>
 952             <para>Means &ldquo;turn off all optimisation&rdquo;,
 953             reverting to the same settings as if no
 954             <option>-O</option> options had been specified.  Saying
 955             <option>-O0</option> can be useful if
 956             eg. <command>make</command> has inserted a
 957             <option>-O</option> on the command line already.</para>
 958           </listitem>
 959         </varlistentry>
 960
 961         <varlistentry>
 962           <term><option>-O</option> or <option>-O1</option>:</term>
 963           <indexterm><primary>-O option</primary></indexterm>
 964           <indexterm><primary>-O1 option</primary></indexterm>
 965           <indexterm><primary>optimise</primary><secondary>normally</secondary></indexterm>
 966           <listitem>
 967             <para>Means: &ldquo;Generate good-quality code without
 968             taking too long about it.&rdquo; Thus, for example:
 969             <command>ghc -c -O Main.lhs</command></para>
 970           </listitem>
 971         </varlistentry>
 972
 973         <varlistentry>
 974           <term><option>-O2</option>:</term>
 975           <indexterm><primary>-O2 option</primary></indexterm>
 976           <indexterm><primary>optimise</primary><secondary>aggressively</secondary></indexterm>
 977           <listitem>
 978             <para>Means: &ldquo;Apply every non-dangerous
 979             optimisation, even if it means significantly longer
 980             compile times.&rdquo;</para>
 981
 982             <para>The avoided &ldquo;dangerous&rdquo; optimisations
 983             are those that can make runtime or space
 984             <emphasis>worse</emphasis> if you're unlucky.  They are
 985             normally turned on or off individually.</para>
 986
 987             <para>At the moment, <option>-O2</option> is
 988             <emphasis>unlikely</emphasis> to produce better code than
 989             <option>-O</option>.</para>
 990           </listitem>
 991         </varlistentry>
 992
 993         <varlistentry>
 994           <term><option>-O2-for-C</option>:</term>
 995           <indexterm><primary>-O2-for-C option</primary></indexterm>
 996           <indexterm><primary>gcc, invoking with -O2</primary></indexterm>
 997           <listitem>
 998             <para>Says to run GCC with <option>-O2</option>, which may
 999             be worth a few percent in execution speed.  Don't forget
1000             <option>-fvia-C</option>, lest you use the native-code
1001             generator and bypass GCC altogether!</para>
1002           </listitem>
1003         </varlistentry>
1004
1005         <varlistentry>
1006           <term><option>-Ofile &lt;file&gt;</option>:</term>
1007           <indexterm><primary>-Ofile &lt;file&gt; option</primary></indexterm>
1008           <indexterm><primary>optimising, customised</primary></indexterm>
1009           <listitem>
1010             <para>(NOTE: not supported yet in GHC 5.x.  Please ask if
1011             you're interested in this.)</para>
1012
1013             <para>For those who need <emphasis>absolute</emphasis>
1014             control over <emphasis>exactly</emphasis> what options are
1015             used (e.g., compiler writers, sometimes :-), a list of
1016             options can be put in a file and then slurped in with
1017             <option>-Ofile</option>.</para>
1018
1019             <para>In that file, comments are of the
1020             <literal>&num;</literal>-to-end-of-line variety; blank
1021             lines and most whitespace is ignored.</para>
1022
1023             <para>Please ask if you are baffled and would like an
1024             example of <option>-Ofile</option>!</para>
1025           </listitem>
1026         </varlistentry>
1027       </variablelist>
1028
1029       <para>We don't use a <option>-O*</option> flag for day-to-day
1030       work.  We use <option>-O</option> to get respectable speed;
1031       e.g., when we want to measure something.  When we want to go for
1032       broke, we tend to use <option>-O -fvia-C -O2-for-C</option> (and
1033       we go for lots of coffee breaks).</para>
1034
1035       <para>The easiest way to see what <option>-O</option> (etc.)
1036       &ldquo;really mean&rdquo; is to run with <option>-v</option>,
1037       then stand back in amazement.</para>
1038     </sect2>
1039
1040     <sect2 id="options-f">
1041       <title><option>-f*</option>: platform-independent flags</title>
1042
1043       <indexterm><primary>-f* options (GHC)</primary></indexterm>
1044       <indexterm><primary>-fno-* options (GHC)</primary></indexterm>
1045
1046       <para>These flags turn on and off individual optimisations.
1047       They are normally set via the <option>-O</option> options
1048       described above, and as such, you shouldn't need to set any of
1049       them explicitly (indeed, doing so could lead to unexpected
1050       results).  However, there are one or two that may be of
1051       interest:</para>
1052
1053       <variablelist>
1054         <varlistentry>
1055           <term><option>-fexcess-precision</option>:</term>
1056           <listitem>
1057             <indexterm><primary><option>-fexcess-precision</option></primary></indexterm>
1058             <para>When this option is given, intermediate floating
1059             point values can have a <emphasis>greater</emphasis>
1060             precision/range than the final type.  Generally this is a
1061             good thing, but some programs may rely on the exact
1062             precision/range of
1063             <literal>Float</literal>/<literal>Double</literal> values
1064             and should not use this option for their compilation.</para>
1065           </listitem>
1066         </varlistentry>
1067
1068         <varlistentry>
1069           <term><option>-fno-strictness</option></term>
1070           <indexterm><primary><option>-fno-strictness</option></primary>
1071           </indexterm>
1072           <listitem>
1073             <para>Turns off the strictness analyser; sometimes it eats
1074             too many cycles.</para>
1075           </listitem>
1076         </varlistentry>
1077
1078         <varlistentry>
1079           <term><option>-fno-cpr-analyse</option></term>
1080           <indexterm><primary><option>-fno-cpr-analyse</option></primary>
1081           </indexterm>
1082           <listitem>
1083             <para>Turns off the CPR (constructed product result)
1084             analysis; it is somewhat experimental.</para>
1085           </listitem>
1086         </varlistentry>
1087
1088         <varlistentry>
1089           <term><option>-funbox-strict-fields</option>:</term>
1090           <listitem>
1091             <indexterm><primary><option>-funbox-strict-fields</option></primary></indexterm>
1092             <indexterm><primary>strict constructor fields</primary></indexterm>
1093             <indexterm><primary>constructor fields, strict</primary></indexterm>
1094
1095             <para>This option causes all constructor fields which are
1096             marked strict (i.e. &ldquo;!&rdquo;) to be unboxed or
1097             unpacked if possible.  For example:</para>
1098
1099 <ProgramListing>
1100 data T = T !Float !Float
1101 </ProgramListing>
1102
1103             <para>will create a constructor <literal>T</literal>
1104             containing two unboxed floats if the
1105             <option>-funbox-strict-fields</option> flag is given.
1106             This may not always be an optimisation: if the
1107             <Function>T</Function> constructor is scrutinised and the
1108             floats passed to a non-strict function for example, they
1109             will have to be reboxed (this is done automatically by the
1110             compiler).</para>
1111
1112             <para>This option should only be used in conjunction with
1113             <option>-O</option>, in order to expose unfoldings to the
1114             compiler so the reboxing can be removed as often as
1115             possible.  For example:</para>
1116
1117 <ProgramListing>
1118 f :: T -&#62; Float
1119 f (T f1 f2) = f1 + f2
1120 </ProgramListing>
1121
1122             <para>The compiler will avoid reboxing
1123             <Function>f1</Function> and <Function>f2</Function> by
1124             inlining <Function>+</Function> on floats, but only when
1125             <option>-O</option> is on.</para>
1126
1127             <para>Any single-constructor data is eligible for
1128             unpacking; for example</para>
1129
1130 <ProgramListing>
1131 data T = T !(Int,Int)
1132 </ProgramListing>
1133
1134             <para>will store the two <literal>Int</literal>s directly
1135             in the <Function>T</Function> constructor, by flattening
1136             the pair.  Multi-level unpacking is also supported:</para>
1137
1138 <ProgramListing>
1139 data T = T !S
1140 data S = S !Int !Int
1141 </ProgramListing>
1142
1143             <para>will store two unboxed <literal>Int&num;</literal>s
1144             directly in the <Function>T</Function> constructor.</para>
1145           </listitem>
1146         </varlistentry>
1147
1148         <varlistentry>
1149           <term><option>-funfolding-update-in-place&lt;n&gt;</option></term>
1150           <indexterm><primary><option>-funfolding-update-in-place</option></primary></indexterm>
1151           <listitem>
1152             <para>Switches on an experimental "optimisation".
1153             Switching it on makes the compiler a little keener to
1154             inline a function that returns a constructor, if the
1155             context is that of a thunk.
1156 <ProgramListing>
1157    x = plusInt a b
1158 </ProgramListing>
1159             If we inlined plusInt we might get an opportunity to use
1160             update-in-place for the thunk 'x'.</para>
1161           </listitem>
1162         </varlistentry>
1163
1164         <varlistentry>
1165           <term><option>-funfolding-interface-threshold&lt;n&gt;</option>:</term>
1166           <listitem>
1167             <indexterm><primary><option>-funfolding-interface-threshold</option></primary></indexterm>
1168             <indexterm><primary>inlining, controlling</primary></indexterm>
1169             <indexterm><primary>unfolding, controlling</primary></indexterm>
1170
1171             <para>(Default: 30) By raising or lowering this number,
1172             you can raise or lower the amount of pragmatic junk that
1173             gets spewed into interface files.  (An unfolding has a
1174             &ldquo;size&rdquo; that reflects the cost in terms of
1175             &ldquo;code bloat&rdquo; of expanding that unfolding in
1176             another module.  A bigger function would be assigned a
1177             bigger cost.)</para>
1178           </listitem>
1179         </varlistentry>
1180
1181         <varlistentry>
1182           <term><option>-funfolding-creation-threshold&lt;n&gt;</option>:</term>
1183           <listitem>
1184             <indexterm><primary><option>-funfolding-creation-threshold</option></primary></indexterm>
1185             <indexterm><primary>inlining, controlling</primary></indexterm>
1186             <indexterm><primary>unfolding, controlling</primary></indexterm>
1187
1188             <para>(Default: 30) This option is similar to
1189             <option>-funfolding-interface-threshold</option>, except
1190             that it governs unfoldings within a single module.
1191             Increasing this figure is more likely to result in longer
1192             compile times than faster code.  The next option is more
1193             useful:</para>
1194           </listitem>
1195         </varlistentry>
1196
1197         <varlistentry>
1198           <term><option>-funfolding-use-threshold&lt;n&gt;</option>:</term>
1199           <listitem>
1200             <indexterm><primary><option>-funfolding-use-threshold</option></primary></indexterm>
1201             <indexterm><primary>inlining, controlling</primary></indexterm>
1202             <indexterm><primary>unfolding, controlling</primary></indexterm>
1203
1204             <para>(Default: 8) This is the magic cut-off figure for
1205             unfolding: below this size, a function definition will be
1206             unfolded at the call-site, any bigger and it won't.  The
1207             size computed for a function depends on two things: the
1208             actual size of the expression minus any discounts that
1209             apply (see <option>-funfolding-con-discount</option>).</para>
1210           </listitem>
1211         </varlistentry>
1212       </variablelist>
1213
1214     </sect2>
1215
1216   </sect1>
1217
1218 &phases;
1219
1220 <Sect1 id="sec-using-concurrent">
1221 <title>Using Concurrent Haskell</title>
1222
1223 <para>
1224 <indexterm><primary>Concurrent Haskell&mdash;use</primary></indexterm>
1225 </para>
1226
1227 <para>
1228 GHC (as of version 4.00) supports Concurrent Haskell by default,
1229 without requiring a special option or libraries compiled in a certain
1230 way.  To get access to the support libraries for Concurrent Haskell
1231 (i.e. <literal>Concurrent</literal> and friends), use the
1232 <option>-package concurrent</option> option.
1233 </para>
1234
1235 <para>
1236 Three RTS options are provided for modifying the behaviour of the
1237 threaded runtime system.  See the descriptions of
1238 <option>-C[&lt;us&gt;]</option>, <option>-q</option>, and
1239 <option>-t&lt;num&gt;</option> in <XRef LinkEnd="parallel-rts-opts">.
1240 </para>
1241
1242 <para>
1243 Concurrent Haskell is described in more detail in <XRef
1244 LinkEnd="sec-Concurrent">.
1245 </para>
1246
1247 </Sect1>
1248
1249 <Sect1 id="sec-using-parallel">
1250 <title>Using Parallel Haskell</title>
1251
1252 <para>
1253 <indexterm><primary>Parallel Haskell&mdash;use</primary></indexterm>
1254 </para>
1255
1256 <para>
1257 &lsqb;You won't be able to execute parallel Haskell programs unless PVM3
1258 (Parallel Virtual Machine, version 3) is installed at your site.]
1259 </para>
1260
1261 <para>
1262 To compile a Haskell program for parallel execution under PVM, use the
1263 <option>-parallel</option> option,<indexterm><primary>-parallel
1264 option</primary></indexterm> both when compiling <emphasis>and
1265 linking</emphasis>.  You will probably want to <literal>import
1266 Parallel</literal> into your Haskell modules.
1267 </para>
1268
1269 <para>
1270 To run your parallel program, once PVM is going, just invoke it
1271 &ldquo;as normal&rdquo;.  The main extra RTS option is
1272 <option>-N&lt;n&gt;</option>, to say how many PVM
1273 &ldquo;processors&rdquo; your program to run on.  (For more details of
1274 all relevant RTS options, please see <XRef
1275 LinkEnd="parallel-rts-opts">.)
1276 </para>
1277
1278 <para>
1279 In truth, running Parallel Haskell programs and getting information
1280 out of them (e.g., parallelism profiles) is a battle with the vagaries of
1281 PVM, detailed in the following sections.
1282 </para>
1283
1284 <sect2>
1285 <title>Dummy's guide to using PVM</title>
1286
1287 <para>
1288 <indexterm><primary>PVM, how to use</primary></indexterm>
1289 <indexterm><primary>Parallel Haskell&mdash;PVM use</primary></indexterm>
1290 Before you can run a parallel program under PVM, you must set the
1291 required environment variables (PVM's idea, not ours); something like,
1292 probably in your <filename>.cshrc</filename> or equivalent:
1293
1294 <ProgramListing>
1295 setenv PVM_ROOT /wherever/you/put/it
1296 setenv PVM_ARCH `$PVM_ROOT/lib/pvmgetarch`
1297 setenv PVM_DPATH $PVM_ROOT/lib/pvmd
1298 </ProgramListing>
1299
1300 </para>
1301
1302 <para>
1303 Creating and/or controlling your &ldquo;parallel machine&rdquo; is a purely-PVM
1304 business; nothing specific to Parallel Haskell.
1305 </para>
1306
1307 <para>
1308 You use the <command>pvm</command><indexterm><primary>pvm command</primary></indexterm> command to start PVM on your
1309 machine.  You can then do various things to control/monitor your
1310 &ldquo;parallel machine;&rdquo; the most useful being:
1311 </para>
1312
1313 <para>
1314 <InformalTable>
1315 <TGroup Cols=2>
1316 <ColSpec Align="Left">
1317 <TBody>
1318
1319 <Row>
1320 <Entry><KeyCombo><KeyCap>Control</KeyCap><KeyCap>D</KeyCap></KeyCombo></Entry>
1321 <Entry>exit <command>pvm</command>, leaving it running</Entry>
1322 </Row>
1323
1324 <Row>
1325 <Entry><command>halt</command></Entry>
1326 <Entry>kill off this &ldquo;parallel machine&rdquo; &amp; exit</Entry>
1327 </Row>
1328
1329 <Row>
1330 <Entry><command>add &lt;host&gt;</command></Entry>
1331 <Entry>add <command>&lt;host&gt;</command> as a processor</Entry>
1332 </Row>
1333
1334 <Row>
1335 <Entry><command>delete &lt;host&gt;</command></Entry>
1336 <Entry>delete <command>&lt;host&gt;</command></Entry>
1337 </Row>
1338
1339 <Row>
1340 <Entry><command>reset</command></Entry>
1341 <Entry>kill what's going, but leave PVM up</Entry>
1342 </Row>
1343
1344 <Row>
1345 <Entry><command>conf</command></Entry>
1346 <Entry>list the current configuration</Entry>
1347 </Row>
1348
1349 <Row>
1350 <Entry><command>ps</command></Entry>
1351 <Entry>report processes' status</Entry>
1352 </Row>
1353
1354 <Row>
1355 <Entry><command>pstat &lt;pid&gt;</command></Entry>
1356 <Entry>status of a particular process</Entry>
1357 </Row>
1358
1359 </TBody>
1360 </TGroup>
1361 </InformalTable>
1362 </para>
1363
1364 <para>
1365 The PVM documentation can tell you much, much more about <command>pvm</command>!
1366 </para>
1367
1368 </sect2>
1369
1370 <sect2>
1371 <title>Parallelism profiles</title>
1372
1373 <para>
1374 <indexterm><primary>parallelism profiles</primary></indexterm>
1375 <indexterm><primary>profiles, parallelism</primary></indexterm>
1376 <indexterm><primary>visualisation tools</primary></indexterm>
1377 </para>
1378
1379 <para>
1380 With Parallel Haskell programs, we usually don't care about the
1381 results&mdash;only with &ldquo;how parallel&rdquo; it was!  We want pretty pictures.
1382 </para>
1383
1384 <para>
1385 Parallelism profiles (&agrave; la <command>hbcpp</command>) can be generated with the
1386 <option>-q</option><indexterm><primary>-q RTS option (concurrent, parallel)</primary></indexterm> RTS option.  The
1387 per-processor profiling info is dumped into files named
1388 <filename>&lt;full-path&gt;&lt;program&gt;.gr</filename>.  These are then munged into a PostScript picture,
1389 which you can then display.  For example, to run your program
1390 <filename>a.out</filename> on 8 processors, then view the parallelism profile, do:
1391 </para>
1392
1393 <para>
1394
1395 <Screen>
1396 % ./a.out +RTS -N8 -q
1397 % grs2gr *.???.gr &#62; temp.gr     # combine the 8 .gr files into one
1398 % gr2ps -O temp.gr              # cvt to .ps; output in temp.ps
1399 % ghostview -seascape temp.ps   # look at it!
1400 </Screen>
1401
1402 </para>
1403
1404 <para>
1405 The scripts for processing the parallelism profiles are distributed
1406 in <filename>ghc/utils/parallel/</filename>.
1407 </para>
1408
1409 </sect2>
1410
1411 <sect2>
1412 <title>Other useful info about running parallel programs</title>
1413
1414 <para>
1415 The &ldquo;garbage-collection statistics&rdquo; RTS options can be useful for
1416 seeing what parallel programs are doing.  If you do either
1417 <option>+RTS -Sstderr</option><indexterm><primary>-Sstderr RTS option</primary></indexterm> or <option>+RTS -sstderr</option>, then
1418 you'll get mutator, garbage-collection, etc., times on standard
1419 error. The standard error of all PE's other than the `main thread'
1420 appears in <filename>/tmp/pvml.nnn</filename>, courtesy of PVM.
1421 </para>
1422
1423 <para>
1424 Whether doing <option>+RTS -Sstderr</option> or not, a handy way to watch
1425 what's happening overall is: <command>tail -f /tmp/pvml.nnn</command>.
1426 </para>
1427
1428 </sect2>
1429
1430 <Sect2 id="parallel-rts-opts">
1431 <title>RTS options for Concurrent/Parallel Haskell
1432 </title>
1433
1434 <para>
1435 <indexterm><primary>RTS options, concurrent</primary></indexterm>
1436 <indexterm><primary>RTS options, parallel</primary></indexterm>
1437 <indexterm><primary>Concurrent Haskell&mdash;RTS options</primary></indexterm>
1438 <indexterm><primary>Parallel Haskell&mdash;RTS options</primary></indexterm>
1439 </para>
1440
1441 <para>
1442 Besides the usual runtime system (RTS) options
1443 (<XRef LinkEnd="runtime-control">), there are a few options particularly
1444 for concurrent/parallel execution.
1445 </para>
1446
1447 <para>
1448 <VariableList>
1449
1450 <varlistentry>
1451 <term><option>-N&lt;N&gt;</option>:</term>
1452 <listitem>
1453 <para>
1454 <indexterm><primary>-N&lt;N&gt; RTS option (parallel)</primary></indexterm>
1455 (PARALLEL ONLY) Use <literal>&lt;N&gt;</literal> PVM processors to run this program;
1456 the default is 2.
1457 </para>
1458 </listitem>
1459 </varlistentry>
1460 <varlistentry>
1461 <term><option>-C[&lt;us&gt;]</option>:</term>
1462 <listitem>
1463 <para>
1464 <indexterm><primary>-C&lt;us&gt; RTS option</primary></indexterm> Sets
1465 the context switch interval to <literal>&lt;s&gt;</literal> seconds.
1466 A context switch will occur at the next heap block allocation after
1467 the timer expires (a heap block allocation occurs every 4k of
1468 allocation).  With <option>-C0</option> or <option>-C</option>,
1469 context switches will occur as often as possible (at every heap block
1470 allocation).  By default, context switches occur every 20ms
1471 milliseconds.  Note that GHC's internal timer ticks every 20ms, and
1472 the context switch timer is always a multiple of this timer, so 20ms
1473 is the maximum granularity available for timed context switches.
1474 </para>
1475 </listitem>
1476 </varlistentry>
1477 <varlistentry>
1478 <term><option>-q[v]</option>:</term>
1479 <listitem>
1480 <para>
1481 <indexterm><primary>-q RTS option</primary></indexterm>
1482 (PARALLEL ONLY) Produce a quasi-parallel profile of thread activity,
1483 in the file <FIlename>&lt;program&gt;.qp</FIlename>.  In the style of <command>hbcpp</command>, this profile
1484 records the movement of threads between the green (runnable) and red
1485 (blocked) queues.  If you specify the verbose suboption (<option>-qv</option>), the
1486 green queue is split into green (for the currently running thread
1487 only) and amber (for other runnable threads).  We do not recommend
1488 that you use the verbose suboption if you are planning to use the
1489 <command>hbcpp</command> profiling tools or if you are context switching at every heap
1490 check (with <option>-C</option>).
1491 </para>
1492 </listitem>
1493 </varlistentry>
1494 <varlistentry>
1495 <term><option>-t&lt;num&gt;</option>:</term>
1496 <listitem>
1497 <para>
1498 <indexterm><primary>-t&lt;num&gt; RTS option</primary></indexterm>
1499 (PARALLEL ONLY) Limit the number of concurrent threads per processor
1500 to <literal>&lt;num&gt;</literal>.  The default is 32.  Each thread requires slightly over 1K
1501 <emphasis>words</emphasis> in the heap for thread state and stack objects.  (For
1502 32-bit machines, this translates to 4K bytes, and for 64-bit machines,
1503 8K bytes.)
1504 </para>
1505 </listitem>
1506 </varlistentry>
1507 <varlistentry>
1508 <term><option>-d</option>:</term>
1509 <listitem>
1510 <para>
1511 <indexterm><primary>-d RTS option (parallel)</primary></indexterm>
1512 (PARALLEL ONLY) Turn on debugging.  It pops up one xterm (or GDB, or
1513 something&hellip;) per PVM processor.  We use the standard <command>debugger</command>
1514 script that comes with PVM3, but we sometimes meddle with the
1515 <command>debugger2</command> script.  We include ours in the GHC distribution,
1516 in <filename>ghc/utils/pvm/</filename>.
1517 </para>
1518 </listitem>
1519 </varlistentry>
1520 <varlistentry>
1521 <term><option>-e&lt;num&gt;</option>:</term>
1522 <listitem>
1523 <para>
1524 <indexterm><primary>-e&lt;num&gt; RTS option (parallel)</primary></indexterm>
1525 (PARALLEL ONLY) Limit the number of pending sparks per processor to
1526 <literal>&lt;num&gt;</literal>. The default is 100. A larger number may be appropriate if
1527 your program generates large amounts of parallelism initially.
1528 </para>
1529 </listitem>
1530 </varlistentry>
1531 <varlistentry>
1532 <term><option>-Q&lt;num&gt;</option>:</term>
1533 <listitem>
1534 <para>
1535 <indexterm><primary>-Q&lt;num&gt; RTS option (parallel)</primary></indexterm>
1536 (PARALLEL ONLY) Set the size of packets transmitted between processors
1537 to <literal>&lt;num&gt;</literal>. The default is 1024 words. A larger number may be
1538 appropriate if your machine has a high communication cost relative to
1539 computation speed.
1540 </para>
1541 </listitem>
1542 </varlistentry>
1543 </VariableList>
1544 </para>
1545
1546 </sect2>
1547
1548 </Sect1>
1549
1550   <sect1 id="options-platform">
1551     <title>Platform-specific Flags</title>
1552
1553     <indexterm><primary>-m* options</primary></indexterm>
1554     <indexterm><primary>platform-specific options</primary></indexterm>
1555     <indexterm><primary>machine-specific options</primary></indexterm>
1556
1557     <para>Some flags only make sense for particular target
1558     platforms.</para>
1559
1560     <variablelist>
1561
1562       <varlistentry>
1563         <term><option>-mv8</option>:</term>
1564         <listitem>
1565           <para>(SPARC machines)<indexterm><primary>-mv8 option (SPARC
1566           only)</primary></indexterm> Means to pass the like-named
1567           option to GCC; it says to use the Version 8 SPARC
1568           instructions, notably integer multiply and divide.  The
1569           similiar <option>-m*</option> GCC options for SPARC also
1570           work, actually.</para>
1571         </listitem>
1572       </varlistentry>
1573
1574       <varlistentry>
1575         <term><option>-mlong-calls</option>:</term>
1576         <listitem>
1577           <para>(HPPA machines)<indexterm><primary>-mlong-calls option
1578           (HPPA only)</primary></indexterm> Means to pass the
1579           like-named option to GCC.  Required for Very Big modules,
1580           maybe.  (Probably means you're in trouble&hellip;)</para>
1581         </listitem>
1582       </varlistentry>
1583
1584       <varlistentry>
1585         <term><option>-monly-[32]-regs</option>:</term>
1586         <listitem>
1587           <para>(iX86 machines)<indexterm><primary>-monly-N-regs
1588           option (iX86 only)</primary></indexterm> GHC tries to
1589           &ldquo;steal&rdquo; four registers from GCC, for performance
1590           reasons; it almost always works.  However, when GCC is
1591           compiling some modules with four stolen registers, it will
1592           crash, probably saying:
1593
1594 <Screen>
1595 Foo.hc:533: fixed or forbidden register was spilled.
1596 This may be due to a compiler bug or to impossible asm
1597 statements or clauses.
1598 </Screen>
1599
1600           Just give some registers back with
1601           <option>-monly-N-regs</option>.  Try `3' first, then `2'.
1602           If `2' doesn't work, please report the bug to us.</para>
1603         </listitem>
1604       </varlistentry>
1605     </variablelist>
1606
1607   </sect1>
1608
1609 &runtime
1610 &debug
1611 &flags
1612
1613 </Chapter>
1614
1615 <!-- Emacs stuff:
1616      ;;; Local Variables: ***
1617      ;;; mode: sgml ***
1618      ;;; sgml-parent-document: ("users_guide.sgml" "book" "chapter") ***
1619      ;;; End: ***
1620  -->