<Chapter id="using-GHC">
-<Title>Using GHC
-</Title>
+<title>Using GHC
+</title>
-<Para>
+<para>
<IndexTerm><Primary>GHC, using</Primary></IndexTerm>
<IndexTerm><Primary>using GHC</Primary></IndexTerm>
-</Para>
-
-<Para>
GHC is a command-line compiler: in order to compile a Haskell program,
GHC must be invoked on the source file(s) by typing a command to the
shell. The steps involved in compiling a program can be automated
-using the <Literal>make</Literal> tool (this is especially useful if the program
+using the <command>make</command> tool (this is especially useful if the program
consists of multiple source files which depend on each other). This
section describes how to use GHC from the command-line.
-</Para>
+</para>
<Sect1 id="command-line-structure">
-<Title>Overall command-line structure
-</Title>
+<title>Overall command-line structure
+</title>
-<Para>
+<para>
<IndexTerm><Primary>structure, command-line</Primary></IndexTerm>
<IndexTerm><Primary>command-line structure</Primary></IndexTerm>
-</Para>
+</para>
-<Para>
+<para>
An invocation of GHC takes the following form:
-</Para>
+</para>
-<Para>
+<para>
<Screen>
ghc [argument...]
</Screen>
-</Para>
+</para>
-<Para>
+<para>
Command-line arguments are either options or file names.
-</Para>
+</para>
-<Para>
-Command-line options begin with <Literal>-</Literal>. They may <Emphasis>not</Emphasis> be
-grouped: <Literal>-vO</Literal> is different from <Literal>-v -O</Literal>. Options need not
-precede filenames: e.g., <Literal>ghc *.o -o foo</Literal>. All options are
+<para>
+Command-line options begin with <literal>-</literal>. They may <emphasis>not</emphasis> be
+grouped: <option>-vO</option> is different from <option>-v -O</option>. Options need not
+precede filenames: e.g., <command>ghc *.o -o foo</command>. All options are
processed and then applied to all files; you cannot, for example, invoke
-<Literal>ghc -c -O1 Foo.hs -O2 Bar.hs</Literal> to apply different optimisation
-levels to the files <Literal>Foo.hs</Literal> and <Literal>Bar.hs</Literal>. For conflicting
-options, e.g., <Literal>-c -S</Literal>, we reserve the right to do anything we
+<command>ghc -c -O1 Foo.hs -O2 Bar.hs</command> to apply different optimisation
+levels to the files <filename>Foo.hs</filename> and <filename>Bar.hs</filename>. For conflicting
+options, e.g., <option>-c -S</option>, we reserve the right to do anything we
want. (Usually, the last one applies.)
-</Para>
+</para>
</Sect1>
<Sect1 id="file-suffixes">
-<Title>Meaningful file suffixes
-</Title>
+<title>Meaningful file suffixes
+</title>
-<Para>
+<para>
<IndexTerm><Primary>suffixes, file</Primary></IndexTerm>
<IndexTerm><Primary>file suffixes for GHC</Primary></IndexTerm>
-</Para>
+</para>
-<Para>
-File names with ``meaningful'' suffixes (e.g., <Literal>.lhs</Literal> or <Literal>.o</Literal>)
-cause the ``right thing'' to happen to those files.
-</Para>
+<para>
+File names with “meaningful” suffixes (e.g., <filename>.lhs</filename> or <filename>.o</filename>)
+cause the “right thing” to happen to those files.
+</para>
-<Para>
+<para>
<VariableList>
<VarListEntry>
-<Term><Literal>.lhs</Literal>:</Term>
+<Term><filename>.lhs</filename>:</Term>
<ListItem>
-<Para>
+<para>
<IndexTerm><Primary>lhs suffix</Primary></IndexTerm>
-A ``literate Haskell'' module.
-</Para>
+A “literate Haskell” module.
+</para>
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>.hs</Literal>:</Term>
+<Term><filename>.hs</filename>:</Term>
<ListItem>
-<Para>
+<para>
A not-so-literate Haskell module.
-</Para>
+</para>
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>.hi</Literal>:</Term>
+<Term><filename>.hi</filename>:</Term>
<ListItem>
-<Para>
+<para>
A Haskell interface file, probably compiler-generated.
-</Para>
+</para>
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>.hc</Literal>:</Term>
+<Term><filename>.hc</filename>:</Term>
<ListItem>
-<Para>
+<para>
Intermediate C file produced by the Haskell compiler.
-</Para>
+</para>
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>.c</Literal>:</Term>
+<Term><filename>.c</filename>:</Term>
<ListItem>
-<Para>
+<para>
A C file not produced by the Haskell compiler.
-</Para>
+</para>
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>.s</Literal>:</Term>
+<Term><filename>.s</filename>:</Term>
<ListItem>
-<Para>
+<para>
An assembly-language source file, usually
produced by the compiler.
-</Para>
+</para>
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Literal>.o</Literal>:</Term>
+<Term><filename>.o</filename>:</Term>
<ListItem>
-<Para>
+<para>
An object file, produced by an assembler.
-</Para>
+</para>
</ListItem>
</VarListEntry>
</VariableList>
-</Para>
+</para>
-<Para>
+<para>
Files with other suffixes (or without suffixes) are passed straight
to the linker.
-</Para>
-
-</Sect1>
-
-<Sect1 id="options-help">
-<Title>Help and verbosity options
-</Title>
-
-<Para>
-<IndexTerm><Primary>help options (GHC)</Primary></IndexTerm>
-<IndexTerm><Primary>verbose option (GHC)</Primary></IndexTerm>
-</Para>
-
-<Para>
-A good option to start with is the <Literal>-help</Literal> (or <Literal>-?</Literal>) option.
-<IndexTerm><Primary>-help option</Primary></IndexTerm>
-<IndexTerm><Primary>-? option</Primary></IndexTerm>
-GHC spews a long message to standard output and then exits.
-</Para>
-
-<Para>
-The <Literal>-v</Literal><IndexTerm><Primary>-v option</Primary></IndexTerm> option makes GHC <Emphasis>verbose</Emphasis>: it
-reports its version number and shows (on stderr) exactly how it invokes each
-phase of the compilation system. Moreover, it passes
-the <Literal>-v</Literal> flag to most phases; each reports
-its version number (and possibly some other information).
-</Para>
-
-<Para>
-Please, oh please, use the <Literal>-v</Literal> option when reporting bugs!
-Knowing that you ran the right bits in the right order is always the
-first thing we want to verify.
-</Para>
-
-<Para>
-If you're just interested in the compiler version number, the
-<Literal>--version</Literal><IndexTerm><Primary>--version option</Primary></IndexTerm> option prints out a
-one-line string containing the requested info.
-</Para>
+</para>
</Sect1>
-<Sect1 id="options-order">
-<Title>Running the right phases in the right order
-</Title>
+ <sect1 id="options-help">
+ <title>Help and verbosity options</title>
+
+ <IndexTerm><Primary>help options</Primary></IndexTerm>
+ <IndexTerm><Primary>verbosity options</Primary></IndexTerm>
+
+ <variablelist>
+ <varlistentry>
+ <term><literal>-help</literal></term>
+ <term><literal>-?</literal></term>
+ <indexterm><primary><literal>-?</literal></primary></indexterm>
+ <indexterm><primary><literal>-help</literal></primary></indexterm>
+ <listitem>
+ <para>Cause GHC to spew a long usage message to standard
+ output and then exit.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>-v</literal></term>
+ <indexterm><primary><literal>-v</literal></primary></indexterm>
+ <listitem>
+ <para>The <option>-v</option> option makes GHC
+ <emphasis>verbose</emphasis>: it reports its version number
+ and shows (on stderr) exactly how it invokes each phase of
+ the compilation system. Moreover, it passes the
+ <option>-v</option> flag to most phases; each reports its
+ version number (and possibly some other information).</para>
+
+ <para>Please, oh please, use the <option>-v</option> option
+ when reporting bugs! Knowing that you ran the right bits in
+ the right order is always the first thing we want to
+ verify.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>-v</literal><replaceable>n</replaceable></term>
+ <indexterm><primary><option>-v</option></primary></indexterm>
+ <listitem>
+ <para>To provide more control over the compiler's verbosity,
+ the <option>-v</option> flag takes an optional numeric
+ argument. Specifying <option>-v</option> on its own is
+ equivalent to <option>-v3</option>, and the other levels
+ have the following meanings:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><literal>-v0</literal></term>
+ <listitem>
+ <para>Disable all non-essential messages (this is the
+ default).</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>-v1</literal></term>
+ <listitem>
+ <para>Minimal verbosity: print one line per
+ compilation (this is the default when
+ <option>--make</option> or
+ <option>--interactive</option> is on).</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>-v2</literal></term>
+ <listitem>
+ <para>Print the name of each compilation phase as it
+ is executed. (equivalent to
+ <option>-dshow-passes</option>).</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>-v3</literal></term>
+ <listitem>
+ <para>The same as <option>-v2</option>, except that in
+ addition the full command line (if appropriate) for
+ each compilation phase is also printed.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>-v4</literal></term>
+ <listitem>
+ <para>The same as <option>-v3</option> except that the
+ intermediate program representation after each
+ compilation phase is also printed (excluding
+ preprocessed and C/assembly files).</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>--version</literal></term>
+ <indexterm><primary><literal>--version</literal></primary></indexterm>
+ <listitem>
+ <para>Print a one-line string including GHC's version number.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>--numeric-version</literal></term>
+ <indexterm><primary><literal>--numeric-version</literal></primary></indexterm>
+ <listitem>
+ <para>Print GHC's numeric version number only.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sect1>
+
+ <Sect1 id="options-order">
+ <title>Running the right phases in the right order</title>
+
+ <indexterm><primary>order of passes in GHC</primary></indexterm>
+ <indexterm><primary>pass ordering in GHC</primary></indexterm>
+
+
+ <para>The basic task of the <command>ghc</command> driver is to
+ run each input file through the right phases (compiling, linking,
+ etc.).</para>
+
+ <para>The first phase to run is determined by the input-file
+ suffix, and the last phase is determined by a flag. If no
+ relevant flag is present, then go all the way through linking.
+ This table summarises:</para>
-<Para>
-<IndexTerm><Primary>order of passes in GHC</Primary></IndexTerm>
-<IndexTerm><Primary>pass ordering in GHC</Primary></IndexTerm>
-The basic task of the <Literal>ghc</Literal> driver is to run each input file
-through the right phases (compiling, linking, etc.).
-</Para>
-
-<Para>
-The first phase to run is determined by the input-file suffix, and the
-last phase is determined by a flag. If no relevant flag is present,
-then go all the way through linking. This table summarises:
-</Para>
-
-<Para>
<InformalTable>
<TGroup Cols="4">
<ColSpec Align="Left">
<Row>
<Entry>Phase of the compilation system</Entry>
-<Entry>Suffix saying ``start here''</Entry>
-<Entry>Flag saying ``stop after''</Entry>
+<Entry>Suffix saying “start here”</Entry>
+<Entry>Flag saying “stop after”</Entry>
<Entry>(suffix of) output file</Entry>
</Row>
literate pre-processor </Entry>
<Entry> .lhs </Entry>
<Entry> - </Entry>
-<Entry> - </Entry>
+<Entry> .hs </Entry>
</Row>
<Row>
<Entry>
C pre-processor (opt.) </Entry>
-<Entry> - </Entry>
-<Entry> - </Entry>
-<Entry> - </Entry>
+<Entry> .hs (with <literal>-cpp</literal>) </Entry>
+<Entry> -E </Entry>
+<Entry> .hspp </Entry>
</Row>
<Row>
<Entry>
<IndexTerm><Primary>-C option</Primary></IndexTerm>
<IndexTerm><Primary>-S option</Primary></IndexTerm>
<IndexTerm><Primary>-c option</Primary></IndexTerm>
-</Para>
-<Para>
-Thus, a common invocation would be: <Literal>ghc -c Foo.hs</Literal>
-</Para>
+<para>
+Thus, a common invocation would be: <command>ghc -c Foo.hs</command>
+</para>
-<Para>
+<para>
Note: What the Haskell compiler proper produces depends on whether a
native-code generator is used (producing assembly language) or not
(producing C).
-</Para>
-
-<Para>
-The option <Literal>-cpp</Literal><IndexTerm><Primary>-cpp option</Primary></IndexTerm> must be given for the C
-pre-processor phase to be run, that is, the pre-processor will be run
-over your Haskell source file before continuing.
-</Para>
-
-<Para>
-The option <Literal>-E</Literal><IndexTerm><Primary>-E option</Primary></IndexTerm> runs just the pre-processing
-passes of the compiler, outputting the result on stdout before
-stopping. If used in conjunction with -cpp, the output is the
-code blocks of the original (literal) source after having put it
-through the grinder that is the C pre-processor. Sans <Literal>-cpp</Literal>, the
-output is the de-litted version of the original source.
-</Para>
-
-<Para>
-The option <Literal>-optcpp-E</Literal><IndexTerm><Primary>-optcpp-E option</Primary></IndexTerm> runs just the
-pre-processing stage of the C-compiling phase, sending the result to
-stdout. (For debugging or obfuscation contests, usually.)
-</Para>
-
-</Sect1>
-
-<Sect1 id="options-output">
-<Title>Re-directing the compilation output(s)
-</Title>
-
-<Para>
-<IndexTerm><Primary>output-directing options</Primary></IndexTerm>
-</Para>
-
-<Para>
-GHC's compiled output normally goes into a <Literal>.hc</Literal>, <Literal>.o</Literal>, etc., file,
-depending on the last-run compilation phase. The option <Literal>-o
-foo</Literal><IndexTerm><Primary>-o option</Primary></IndexTerm> re-directs the output of that last-run
-phase to file <Literal>foo</Literal>.
-</Para>
-
-<Para>
-Note: this ``feature'' can be counterintuitive:
-<Literal>ghc -C -o foo.o foo.hs</Literal> will put the intermediate C code in the
-file <Literal>foo.o</Literal>, name notwithstanding!
-</Para>
-
-<Para>
-EXOTICA: But the <Literal>-o</Literal> option isn't of much use if you have
-<Emphasis>several</Emphasis> input files… Non-interface output files are
-normally put in the same directory as their corresponding input file
-came from. You may specify that they be put in another directory
-using the <Literal>-odir <dir></Literal><IndexTerm><Primary>-odir <dir> option</Primary></IndexTerm> (the
-``Oh, dear'' option). For example:
-</Para>
-
-<Para>
+</para>
+
+ <para>NOTE: the option <option>-E</option><IndexTerm><Primary>-E
+ option</Primary></IndexTerm> runs just the pre-processing passes
+ of the compiler, dumping the result in a file. Note that this
+ differs from all GHCs prior to version 4.11, in which the result
+ was dumped to the standard output. If used in conjunction with
+ -cpp, the output is the code blocks of the original (literal)
+ source after having put it through the grinder that is the C
+ pre-processor. Sans <option>-cpp</option>, the output is the
+ de-litted version of the original source.</para>
+
+ <para>The following options also affect which phases get run:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><option>-cpp</option></term>
+ <indexterm><primary><option>-cpp</option></primary></indexterm>
+ <listitem>
+ <para>Run the C pre-processor on the Haskell source before
+ compiling it. See <xref linkend="c-pre-processor"> for more
+ details.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-fasm</option></term>
+ <indexterm><primary><option>-fasm</option></primary></indexterm>
+ <listitem>
+ <para>Use GHC's native code generator rather than compiling
+ via C. This will compile faster (up to twice as fast), but
+ may produce code that is slightly slower than compiling via
+ C. <option>-fasm</option> is the default when optimisation
+ is off (see <xref linkend="options-optimise">).</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-fvia-C</option></term>
+ <indexterm><primary><option>-fvia-C</option></primary>
+ </indexterm>
+ <listitem>
+ <para>Compile via C instead of using the native code
+ generator. This is default for optimised compilations, and
+ on architectures for which GHC doesn't have a native code
+ generator.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sect1>
+
+ <sect1 id="options-output">
+ <title>Re-directing the compilation output(s)</title>
+
+ <indexterm><primary>output-directing options</primary></indexterm>
+ <indexterm><primary>redirecting compilation output</primary></indexterm>
+
+
+ <variablelist>
+ <varlistentry>
+ <term><literal>-o</literal></term>
+ <indexterm><primary><literal>-o</literal></primary></indexterm>
+ <listitem>
+ <para>GHC's compiled output normally goes into a
+ <filename>.hc</filename>, <filename>.o</filename>, etc.,
+ file, depending on the last-run compilation phase. The
+ option <option>-o foo</option><IndexTerm><Primary>-o
+ option</Primary></IndexTerm> re-directs the output of that
+ last-run phase to file <filename>foo</filename>.</para>
+
+ <para>Note: this “feature” can be
+ counterintuitive: <command>ghc -C -o foo.o foo.hs</command>
+ will put the intermediate C code in the file
+ <filename>foo.o</filename>, name notwithstanding!</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>-odir</literal></term>
+ <indexterm><primary><literal>-odir</literal></primary></indexterm>
+ <listitem>
+ <para>The <option>-o</option> option isn't of much use if
+ you have <emphasis>several</emphasis> input files…
+ Non-interface output files are normally put in the same
+ directory as their corresponding input file came from. You
+ may specify that they be put in another directory using the
+ <option>-odir <dir></option><IndexTerm><Primary>-odir
+ <dir> option</Primary></IndexTerm> (the “Oh,
+ dear” option). For example:</para>
<Screen>
% ghc -c parse/Foo.hs parse/Bar.hs gurgle/Bumble.hs -odir `arch`
</Screen>
-</Para>
-
-<Para>
-The output files, <Literal>Foo.o</Literal>, <Literal>Bar.o</Literal>, and <Literal>Bumble.o</Literal> would be
-put into a subdirectory named after the architecture of the executing
-machine (<Literal>sun4</Literal>, <Literal>mips</Literal>, etc). The directory must already
-exist; it won't be created.
-</Para>
-
-<Para>
-Note that the <Literal>-odir</Literal> option does <Emphasis>not</Emphasis> affect where the
-interface files are put. In the above example, they would still be
-put in <Literal>parse/Foo.hi</Literal>, <Literal>parse/Bar.hi</Literal>, and <Literal>gurgle/Bumble.hi</Literal>.
-</Para>
-
-<Para>
-MORE EXOTICA: The <Literal>-osuf <suffix></Literal><IndexTerm><Primary>-osuf <suffix>
-option</Primary></IndexTerm> will change the <Literal>.o</Literal> file suffix for object files to
-whatever you specify. (We use this in compiling the prelude.).
-Similarly, the <Literal>-hisuf <suffix></Literal><IndexTerm><Primary>-hisuf <suffix>
-option</Primary></IndexTerm> will change the <Literal>.hi</Literal> file suffix for non-system
-interface files (see <XRef LinkEnd="hi-options">).
-</Para>
-
-<Para>
-The <Literal>-hisuf</Literal>/<Literal>-osuf</Literal> game is useful if you want to compile a program
-with both GHC and HBC (say) in the same directory. Let HBC use the
-standard <Literal>.hi</Literal>/<Literal>.o</Literal> suffixes; add <Literal>-hisuf g_hi -osuf g_o</Literal> to your
-<Literal>make</Literal> rule for GHC compiling…
-</Para>
-
-<Para>
-FURTHER EXOTICA: If you are doing a normal <Literal>.hs</Literal>-to-<Literal>.o</Literal> compilation
-but would like to hang onto the intermediate <Literal>.hc</Literal> C file, just
-throw in a <Literal>-keep-hc-file-too</Literal> option<IndexTerm><Primary>-keep-hc-file-too option</Primary></IndexTerm>.
-If you would like to look at the assembler output, toss in a
-<Literal>-keep-s-file-too</Literal>,<IndexTerm><Primary>-keep-s-file-too option</Primary></IndexTerm> too.
-</Para>
-
-<Sect2 id="saving-ghc-stderr">
-<Title>Saving GHC's standard error output
-</Title>
-
-<Para>
-<IndexTerm><Primary>standard error, saving</Primary></IndexTerm>
-</Para>
-
-<Para>
-Sometimes, you may cause GHC to be rather chatty on standard error;
-with <Literal>-v</Literal>, for example. You can instruct GHC to <Emphasis>append</Emphasis> this
-output to a particular log file with a <Literal>-odump <blah></Literal><IndexTerm><Primary>-odump
-<blah> option</Primary></IndexTerm> option.
-</Para>
-
-</Sect2>
-
-<Sect2 id="temp-files">
-<Title>Redirecting temporary files
-</Title>
-
-<Para>
-<IndexTerm><Primary>temporary files, redirecting</Primary></IndexTerm>
-</Para>
-
-<Para>
-If you have trouble because of running out of space in <Literal>/tmp</Literal> (or
-wherever your installation thinks temporary files should go), you may
-use the <Literal>-tmpdir <dir></Literal><IndexTerm><Primary>-tmpdir <dir> option</Primary></IndexTerm> option
-to specify an alternate directory. For example, <Literal>-tmpdir .</Literal> says to
-put temporary files in the current working directory.
-</Para>
-
-<Para>
-Alternatively, use your <Literal>TMPDIR</Literal> environment variable.<IndexTerm><Primary>TMPDIR
-environment variable</Primary></IndexTerm> Set it to the name of the directory where
-temporary files should be put. GCC and other programs will honour the
-<Literal>TMPDIR</Literal> variable as well.
-</Para>
-
-<Para>
-Even better idea: Set the <Literal>TMPDIR</Literal> variable when building GHC, and
-never worry about <Literal>TMPDIR</Literal> again. (see the build documentation).
-</Para>
-
-</Sect2>
-
-</Sect1>
-
-<Sect1 id="options-sanity">
-<Title>Warnings and sanity-checking
-</Title>
-
-<Para>
-<IndexTerm><Primary>sanity-checking options</Primary></IndexTerm>
-<IndexTerm><Primary>warnings</Primary></IndexTerm>
-GHC has a number of options that select which types of non-fatal error
-messages, otherwise known as warnings, can be generated during
-compilation. By default, you get a standard set of warnings which are
-generally likely to indicate bugs in your program. These are:
-<Literal>-fwarn-overlpapping-patterns</Literal>, <Literal>-fwarn-duplicate-exports</Literal>, and
-<Literal>-fwarn-missing-methods</Literal>. The following flags are simple ways to
-select standard ``packages'' of warnings:
-</Para>
-
-<Para>
-<VariableList>
-
-<VarListEntry>
-<Term><Literal>-Wnot</Literal>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-Wnot option</Primary></IndexTerm>
-Turns off all warnings, including the standard ones.
-</Para>
-</ListItem>
-</VarListEntry>
-
-<VarListEntry>
-<Term><Literal>-w</Literal>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-w option</Primary></IndexTerm>
-Synonym for <Literal>-Wnot</Literal>.
-</Para>
-</ListItem>
-</VarListEntry>
-
-<VarListEntry>
-<Term><Literal>-W</Literal>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-W option</Primary></IndexTerm>
-Provides the standard warnings plus <Literal>-fwarn-incomplete-patterns</Literal>,
-<Literal>-fwarn-unused-imports</Literal> and <Literal>-fwarn-unused-binds</Literal>.
-</Para>
-</ListItem>
-</VarListEntry>
-
-<VarListEntry>
-<Term><Literal>-Wall</Literal>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-Wall option</Primary></IndexTerm>
-Turns on all warning options.
-</Para>
-</ListItem>
-</VarListEntry>
-
-</VariableList>
-</Para>
-
-<Para>
-The full set of warning options is described below. To turn off any
-warning, simply give the corresponding <Literal>-fno-warn-...</Literal> option on
-the command line.
-</Para>
-
-<Para>
-<VariableList>
-
-<VarListEntry>
-<Term><Literal>-fwarn-name-shadowing</Literal>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-fwarn-name-shadowing option</Primary></IndexTerm>
-<IndexTerm><Primary>shadowing, warning</Primary></IndexTerm>This option causes a warning to be emitted whenever an inner-scope
-value has the same name as an outer-scope value, i.e. the inner value
-shadows the outer one. This can catch typographical errors that turn
-into hard-to-find bugs, e.g., in the inadvertent cyclic definition
-<Literal>let x = ... x ... in</Literal>.
-</Para>
-
-<Para>
-Consequently, this option does <Emphasis>not</Emphasis> allow cyclic recursive
-definitions.
-</Para>
-</ListItem>
-</VarListEntry>
-
-<VarListEntry>
-<Term><Literal>-fwarn-overlapping-patterns</Literal>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-fwarn-overlapping-patterns option</Primary></IndexTerm>
-<IndexTerm><Primary>overlapping patterns, warning</Primary></IndexTerm>
-<IndexTerm><Primary>patterns, overlapping</Primary></IndexTerm>
-By default, the compiler will warn you if a set of patterns are
-overlapping, i.e.,
-</Para>
-
-<Para>
-<ProgramListing>
+ <para>The output files, <filename>Foo.o</filename>,
+ <filename>Bar.o</filename>, and
+ <filename>Bumble.o</filename> would be put into a
+ subdirectory named after the architecture of the executing
+ machine (<filename>sun4</filename>,
+ <filename>mips</filename>, etc). The directory must already
+ exist; it won't be created.</para>
+
+ <para>Note that the <option>-odir</option> option does
+ <emphasis>not</emphasis> affect where the interface files
+ are put. In the above example, they would still be put in
+ <filename>parse/Foo.hi</filename>,
+ <filename>parse/Bar.hi</filename>, and
+ <filename>gurgle/Bumble.hi</filename>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>-ohi</literal></term>
+ <indexterm><primary><literal>-ohi</literal></primary></indexterm>
+ <listitem>
+ <para></para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>-osuf</literal></term>
+ <term><literal>-hisuf</literal></term>
+ <indexterm><primary><literal>-osuf</literal></primary></indexterm>
+ <indexterm><primary><literal>-hisuf</literal></primary></indexterm>
+ <listitem>
+ <para>EXOTICA: The <option>-osuf
+ <suffix></option><IndexTerm><Primary>-osuf
+ <suffix> option</Primary></IndexTerm> will change the
+ <filename>.o</filename> file suffix for object files to
+ whatever you specify. (We use this in compiling the
+ prelude.).</para>
+
+ <para>Similarly, the <option>-hisuf
+ <suffix></option><IndexTerm><Primary>-hisuf
+ <suffix> option</Primary></IndexTerm> will change the
+ <filename>.hi</filename> file suffix for non-system
+ interface files (see <XRef LinkEnd="hi-options">).</para>
+
+ <para>The <option>-hisuf</option>/<option>-osuf</option>
+ game is useful if you want to compile a program with both
+ GHC and HBC (say) in the same directory. Let HBC use the
+ standard <filename>.hi</filename>/<filename>.o</filename>
+ suffixes; add <option>-hisuf g_hi -osuf
+ g_o</option> to your <command>make</command> rule for
+ GHC compiling…</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <sect2 id="keeping-intermediates">
+ <title>Keeping Intermediate Files</title>
+ <indexterm><primary>intermediate files, saving</primary>
+ </indexterm>
+ <indexterm><primary><literal>.hc</literal> files, saving</primary>
+ </indexterm>
+ <indexterm><primary><literal>.s</literal> files, saving</primary>
+ </indexterm>
+
+
+ <para>The following options are useful for keeping certain
+ intermediate files around, when normally GHC would throw these
+ away after compilation:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><literal>-keep-hc-files</literal></term>
+ <indexterm>
+ <primary><literal>-keep-hc-files</literal></primary>
+ </indexterm>
+ <listitem>
+ <para>Keep intermediate <literal>.hc</literal> files when
+ doing <literal>.hs</literal>-to-<literal>.o</literal>
+ compilations via C (NOTE: <literal>.hc</literal> files
+ aren't generated when using the native code generator, you
+ may need to use <literal>-fvia-C</literal> to force them
+ to be produced).</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>-keep-s-files</literal></term>
+ <indexterm>
+ <primary><literal>-keep-s-files</literal></primary>
+ </indexterm>
+ <listitem>
+ <para>Keep intermediate <literal>.s</literal> files.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>-keep-raw-s-files</literal></term>
+ <indexterm>
+ <primary><literal>-keep-raw-s-files</literal></primary>
+ </indexterm>
+ <listitem>
+ <para>Keep intermediate <literal>.raw-s</literal> files.
+ These are the direct output from the C compiler, before
+ GHC does “assembly mangling” to produce the
+ <literal>.s</literal> file. Again, these are not produced
+ when using the native code generator.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>-keep-tmp-files</literal></term>
+ <indexterm>
+ <primary><literal>-keep-tmp-files</literal></primary>
+ </indexterm>
+ <indexterm>
+ <primary>temporary files</primary>
+ <secondary>keeping</secondary>
+ </indexterm>
+ <listitem>
+ <para>Instructs the GHC driver not to delete any of its
+ temporary files, which it normally keeps in
+ <literal>/tmp</literal> (or possibly elsewhere; see <xref
+ linkend="temp-files">). Running GHC with
+ <literal>-v</literal> will show you what temporary files
+ were generated along the way.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sect2>
+
+ <sect2 id="temp-files">
+ <title>Redirecting temporary files</title>
+
+ <indexterm>
+ <primary>temporary files</primary>
+ <secondary>redirecting</secondary>
+ </indexterm>
+
+ <variablelist>
+ <varlistentry>
+ <term><literal>-tmpdir</literal></term>
+ <indexterm><primary><literal>-tmpdir</literal></primary></indexterm>
+ <listitem>
+ <para>If you have trouble because of running out of space
+ in <filename>/tmp</filename> (or wherever your
+ installation thinks temporary files should go), you may
+ use the <option>-tmpdir
+ <dir></option><IndexTerm><Primary>-tmpdir
+ <dir> option</Primary></IndexTerm> option to specify
+ an alternate directory. For example, <option>-tmpdir
+ .</option> says to put temporary files in the current
+ working directory.</para>
+
+ <para>Alternatively, use your <Constant>TMPDIR</Constant>
+ environment variable.<IndexTerm><Primary>TMPDIR
+ environment variable</Primary></IndexTerm> Set it to the
+ name of the directory where temporary files should be put.
+ GCC and other programs will honour the
+ <Constant>TMPDIR</Constant> variable as well.</para>
+
+ <para>Even better idea: Set the
+ <Constant>DEFAULT_TMPDIR</Constant> make variable when
+ building GHC, and never worry about
+ <Constant>TMPDIR</Constant> again. (see the build
+ documentation).</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sect2>
+
+ </sect1>
+
+ <sect1 id="options-sanity">
+ <title>Warnings and sanity-checking</title>
+
+ <indexterm><primary>sanity-checking options</primary></indexterm>
+ <indexterm><primary>warnings</primary></indexterm>
+
+
+ <para>GHC has a number of options that select which types of
+ non-fatal error messages, otherwise known as warnings, can be
+ generated during compilation. By default, you get a standard set
+ of warnings which are generally likely to indicate bugs in your
+ program. These are:
+ <option>-fwarn-overlpapping-patterns</option>,
+ <option>-fwarn-deprecations</option>,
+ <option>-fwarn-duplicate-exports</option>,
+ <option>-fwarn-missing-fields</option>, and
+ <option>-fwarn-missing-methods</option>. The following flags are
+ simple ways to select standard “packages” of warnings:
+ </para>
+
+ <VariableList>
+
+ <varlistentry>
+ <term><option>-W</option>:</term>
+ <listitem>
+ <IndexTerm><Primary>-W option</Primary></IndexTerm>
+ <para>Provides the standard warnings plus
+ <option>-fwarn-incomplete-patterns</option>,
+ <option>-fwarn-unused-matches</option>,
+ <option>-fwarn-unused-imports</option> and
+ <option>-fwarn-unused-binds</option>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-w</option>:</term>
+ <listitem>
+ <IndexTerm><Primary>-w option</Primary></IndexTerm>
+ <para>Turns off all warnings, including the standard ones.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Wall</option>:</term>
+ <listitem>
+ <indexterm><primary>-Wall option</primary></indexterm>
+ <para>Turns on all warning options.</para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+
+ <para>The full set of warning options is described below. To turn
+ off any warning, simply give the corresponding
+ <option>-fno-warn-...</option> option on the command line.</para>
+
+ <variablelist>
+
+ <varlistentry>
+ <term><option>-fwarn-deprecations</option>:</term>
+ <listitem>
+ <indexterm><primary><option>-fwarn-deprecations</option></primary>
+ </indexterm>
+ <indexterm><primary>deprecations</primary></indexterm>
+ <para>Causes a warning to be emitted when a deprecated
+ function or type is used. Entities can be marked as
+ deprecated using a pragma, see <xref
+ linkend="deprecated-pragma">.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-fwarn-duplicate-exports</option>:</term>
+ <listitem>
+ <indexterm><primary>-fwarn-duplicate-exports option</primary></indexterm>
+ <indexterm><primary>duplicate exports, warning</primary></indexterm>
+ <indexterm><primary>export lists, duplicates</primary></indexterm>
+
+ <para>Have the compiler warn about duplicate entries in
+ export lists. This is useful information if you maintain
+ large export lists, and want to avoid the continued export
+ of a definition after you've deleted (one) mention of it in
+ the export list.</para>
+
+ <para>This option is on by default.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-fwarn-hi-shadowing</option>:</term>
+ <listitem>
+ <indexterm><primary>-fwarn-hi-shadowing option</primary></indexterm>
+ <indexterm><primary>shadowing</primary>
+ <secondary>interface files</secondary></indexterm>
+
+ <para>Causes the compiler to emit a warning when a module or
+ interface file in the current directory is shadowing one
+ with the same module name in a library or other
+ directory.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-fwarn-incomplete-patterns</option>:</term>
+ <listitem>
+ <indexterm><primary>-fwarn-incomplete-patterns option</primary></indexterm>
+ <indexterm><primary>incomplete patterns, warning</primary></indexterm>
+ <indexterm><primary>patterns, incomplete</primary></indexterm>
+
+ <para>Similarly for incomplete patterns, the function
+ <function>g</function> below will fail when applied to
+ non-empty lists, so the compiler will emit a warning about
+ this when <option>-fwarn-incomplete-patterns</option> is
+ enabled.</para>
+
+<programlisting>
+g [] = 2
+</programlisting>
+
+ <para>This option isn't enabled be default because it can be
+ a bit noisy, and it doesn't always indicate a bug in the
+ program. However, it's generally considered good practice
+ to cover all the cases in your functions.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-fwarn-missing-fields</option>:</term>
+ <listitem>
+ <indexterm><primary>-fwarn-missing-fields option</primary></indexterm>
+ <indexterm><primary>missing fields, warning</primary></indexterm>
+ <indexterm><primary>fields, missing</primary></indexterm>
+
+ <para>This option is on by default, and warns you whenever
+ the construction of a labelled field constructor isn't
+ complete, missing initializers for one or more fields. While
+ not an error (the missing fields are initialised with
+ bottoms), it is often an indication of a programmer error.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-fwarn-missing-methods</option>:</term>
+ <listitem>
+ <indexterm><primary>-fwarn-missing-methods option</primary></indexterm>
+ <indexterm><primary>missing methods, warning</primary></indexterm>
+ <indexterm><primary>methods, missing</primary></indexterm>
+
+ <para>This option is on by default, and warns you whenever
+ an instance declaration is missing one or more methods, and
+ the corresponding class declaration has no default
+ declaration for them.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-fwarn-missing-signatures</option>:</term>
+ <listitem>
+ <indexterm><primary>-fwarn-missing-signatures option</primary></indexterm>
+ <indexterm><primary>type signatures, missing</primary></indexterm>
+
+ <para>If you would like GHC to check that every top-level
+ function/value has a type signature, use the
+ <option>-fwarn-missing-signatures</option> option. This
+ option is off by default.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-fwarn-name-shadowing</option>:</term>
+ <listitem>
+ <indexterm><primary>-fwarn-name-shadowing option</primary></indexterm>
+ <indexterm><primary>shadowing, warning</primary></indexterm>
+
+ <para>This option causes a warning to be emitted whenever an
+ inner-scope value has the same name as an outer-scope value,
+ i.e. the inner value shadows the outer one. This can catch
+ typographical errors that turn into hard-to-find bugs, e.g.,
+ in the inadvertent cyclic definition <literal>let x = ... x
+ ... in</literal>.</para>
+
+ <para>Consequently, this option does
+ <emphasis>will</emphasis> complain about cyclic recursive
+ definitions.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-fwarn-overlapping-patterns</option>:</term>
+ <indexterm><primary>-fwarn-overlapping-patterns option</primary></indexterm>
+ <indexterm><primary>overlapping patterns, warning</primary></indexterm>
+ <indexterm><primary>patterns, overlapping</primary></indexterm>
+ <listitem>
+ <para>By default, the compiler will warn you if a set of
+ patterns are overlapping, i.e.,</para>
+
+<programlisting>
f :: String -> Int
f [] = 0
f (_:xs) = 1
f "2" = 2
-</ProgramListing>
-</Para>
-
-<Para>
-where the last pattern match in <Literal>f</Literal> won't ever be reached, as the
-second pattern overlaps it. More often than not, redundant patterns
-is a programmer mistake/error, so this option is enabled by default.
-</Para>
-</ListItem>
-</VarListEntry>
+</programlisting>
+
+ <para>where the last pattern match in <Function>f</Function>
+ won't ever be reached, as the second pattern overlaps
+ it. More often than not, redundant patterns is a programmer
+ mistake/error, so this option is enabled by default.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-fwarn-simple-patterns</option>:</term>
+ <listitem>
+ <indexterm><primary><option>-fwarn-simple-patterns</option></primary>
+ </indexterm>
+ <para>Causes the compiler to warn about lambda-bound
+ patterns that can fail, eg. <literal>\(x:xs)->...</literal>.
+ Normally, these aren't treated as incomplete patterns by
+ <option>-fwarn-incomplete-patterns</option>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-fwarn-type-defaults</option>:</term>
+ <listitem>
+ <indexterm><primary>-fwarn-type-defaults option</primary></indexterm>
+ <indexterm><primary>defaulting mechanism, warning</primary></indexterm>
+ <para>Have the compiler warn/inform you where in your source
+ the Haskell defaulting mechanism for numeric types kicks
+ in. This is useful information when converting code from a
+ context that assumed one default into one with another,
+ e.g., the `default default' for Haskell 1.4 caused the
+ otherwise unconstrained value <Constant>1</Constant> to be
+ given the type <literal>Int</literal>, whereas Haskell 98
+ defaults it to <literal>Integer</literal>. This may lead to
+ differences in performance and behaviour, hence the
+ usefulness of being non-silent about this.</para>
+
+ <para>This warning is off by default.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-fwarn-unused-binds</option>:</term>
+ <listitem>
+ <indexterm><primary>-fwarn-unused-binds option</primary></indexterm>
+ <indexterm><primary>unused binds, warning</primary></indexterm>
+ <indexterm><primary>binds, unused</primary></indexterm>
+ <para>Report any function definitions (and local bindings)
+ which are unused. For top-level functions, the warning is
+ only given if the binding is not exported.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-fwarn-unused-imports</option>:</term>
+ <listitem>
+ <indexterm><primary>-fwarn-unused-imports option</primary></indexterm>
+ <indexterm><primary>unused imports, warning</primary></indexterm>
+ <indexterm><primary>imports, unused</primary></indexterm>
+
+ <para>Report any objects that are explicitly imported but
+ never used.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-fwarn-unused-matches</option>:</term>
+ <listitem>
+ <indexterm><primary>-fwarn-unused-matches option</primary></indexterm>
+ <indexterm><primary>unused matches, warning</primary></indexterm>
+ <indexterm><primary>matches, unused</primary></indexterm>
+
+ <para>Report all unused variables which arise from pattern
+ matches, including patterns consisting of a single variable.
+ For instance <literal>f x y = []</literal> would report
+ <VarName>x</VarName> and <VarName>y</VarName> as unused. To
+ eliminate the warning, all unused variables can be replaced
+ with wildcards.</para>
+ </listitem>
+ </varlistentry>
+
+ </VariableList>
+
+ <para>If you're feeling really paranoid, the
+ <option>-dcore-lint</option> option<indexterm><primary>-dcore-lint
+ option</primary></indexterm> is a good choice. It turns on
+ heavyweight intra-pass sanity-checking within GHC. (It checks
+ GHC's sanity, not yours.)</para>
+
+ </sect1>
+
+ &separate;
+ &packages;
+
+ <sect1 id="options-optimise">
+ <title>Optimisation (code improvement)</title>
+
+ <indexterm><primary>optimisation</primary></indexterm>
+ <indexterm><primary>improvement, code</primary></indexterm>
+
+ <para>The <option>-O*</option> options specify convenient
+ “packages” of optimisation flags; the
+ <option>-f*</option> options described later on specify
+ <emphasis>individual</emphasis> optimisations to be turned on/off;
+ the <option>-m*</option> options specify
+ <emphasis>machine-specific</emphasis> optimisations to be turned
+ on/off.</para>
+
+ <sect2 id="optimise-pkgs">
+ <title><option>-O*</option>: convenient “packages” of optimisation flags.</title>
+
+ <para>There are <emphasis>many</emphasis> options that affect
+ the quality of code produced by GHC. Most people only have a
+ general goal, something like “Compile quickly” or
+ “Make my program run like greased lightning.” The
+ following “packages” of optimisations (or lack
+ thereof) should suffice.</para>
+
+ <para>Once you choose a <option>-O*</option>
+ “package,” stick with it—don't chop and
+ change. Modules' interfaces <emphasis>will</emphasis> change
+ with a shift to a new <option>-O*</option> option, and you may
+ have to recompile a large chunk of all importing modules before
+ your program can again be run safely (see <XRef
+ LinkEnd="recomp">).</para>
+
+ <variablelist>
+
+ <varlistentry>
+ <term>No <option>-O*</option>-type option specified:</term>
+ <indexterm><primary>-O* not specified</primary></indexterm>
+ <listitem>
+ <para>This is taken to mean: “Please compile
+ quickly; I'm not over-bothered about compiled-code
+ quality.” So, for example: <command>ghc -c
+ Foo.hs</command></para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-O0</option>:</term>
+ <indexterm><primary><option>-O0</option></primary></indexterm>
+ <listitem>
+ <para>Means “turn off all optimisation”,
+ reverting to the same settings as if no
+ <option>-O</option> options had been specified. Saying
+ <option>-O0</option> can be useful if
+ eg. <command>make</command> has inserted a
+ <option>-O</option> on the command line already.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-O</option> or <option>-O1</option>:</term>
+ <indexterm><primary>-O option</primary></indexterm>
+ <indexterm><primary>-O1 option</primary></indexterm>
+ <indexterm><primary>optimise</primary><secondary>normally</secondary></indexterm>
+ <listitem>
+ <para>Means: “Generate good-quality code without
+ taking too long about it.” Thus, for example:
+ <command>ghc -c -O Main.lhs</command></para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-O2</option>:</term>
+ <indexterm><primary>-O2 option</primary></indexterm>
+ <indexterm><primary>optimise</primary><secondary>aggressively</secondary></indexterm>
+ <listitem>
+ <para>Means: “Apply every non-dangerous
+ optimisation, even if it means significantly longer
+ compile times.”</para>
+
+ <para>The avoided “dangerous” optimisations
+ are those that can make runtime or space
+ <emphasis>worse</emphasis> if you're unlucky. They are
+ normally turned on or off individually.</para>
+
+ <para>At the moment, <option>-O2</option> is
+ <emphasis>unlikely</emphasis> to produce better code than
+ <option>-O</option>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-O2-for-C</option>:</term>
+ <indexterm><primary>-O2-for-C option</primary></indexterm>
+ <indexterm><primary>gcc, invoking with -O2</primary></indexterm>
+ <listitem>
+ <para>Says to run GCC with <option>-O2</option>, which may
+ be worth a few percent in execution speed. Don't forget
+ <option>-fvia-C</option>, lest you use the native-code
+ generator and bypass GCC altogether!</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Ofile <file></option>:</term>
+ <indexterm><primary>-Ofile <file> option</primary></indexterm>
+ <indexterm><primary>optimising, customised</primary></indexterm>
+ <listitem>
+ <para>(NOTE: not supported yet in GHC 5.x. Please ask if
+ you're interested in this.)</para>
+
+ <para>For those who need <emphasis>absolute</emphasis>
+ control over <emphasis>exactly</emphasis> what options are
+ used (e.g., compiler writers, sometimes :-), a list of
+ options can be put in a file and then slurped in with
+ <option>-Ofile</option>.</para>
+
+ <para>In that file, comments are of the
+ <literal>#</literal>-to-end-of-line variety; blank
+ lines and most whitespace is ignored.</para>
+
+ <para>Please ask if you are baffled and would like an
+ example of <option>-Ofile</option>!</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>We don't use a <option>-O*</option> flag for day-to-day
+ work. We use <option>-O</option> to get respectable speed;
+ e.g., when we want to measure something. When we want to go for
+ broke, we tend to use <option>-O -fvia-C -O2-for-C</option> (and
+ we go for lots of coffee breaks).</para>
+
+ <para>The easiest way to see what <option>-O</option> (etc.)
+ “really mean” is to run with <option>-v</option>,
+ then stand back in amazement.</para>
+ </sect2>
+
+ <sect2 id="options-f">
+ <title><option>-f*</option>: platform-independent flags</title>
+
+ <indexterm><primary>-f* options (GHC)</primary></indexterm>
+ <indexterm><primary>-fno-* options (GHC)</primary></indexterm>
+
+ <para>These flags turn on and off individual optimisations.
+ They are normally set via the <option>-O</option> options
+ described above, and as such, you shouldn't need to set any of
+ them explicitly (indeed, doing so could lead to unexpected
+ results). However, there are one or two that may be of
+ interest:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><option>-fexcess-precision</option>:</term>
+ <listitem>
+ <indexterm><primary><option>-fexcess-precision</option></primary></indexterm>
+ <para>When this option is given, intermediate floating
+ point values can have a <emphasis>greater</emphasis>
+ precision/range than the final type. Generally this is a
+ good thing, but some programs may rely on the exact
+ precision/range of
+ <literal>Float</literal>/<literal>Double</literal> values
+ and should not use this option for their compilation.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-fno-strictness</option></term>
+ <indexterm><primary><option>-fno-strictness</option></primary>
+ </indexterm>
+ <listitem>
+ <para>Turns off the strictness analyser; sometimes it eats
+ too many cycles.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-fno-cpr-analyse</option></term>
+ <indexterm><primary><option>-fno-cpr-analyse</option></primary>
+ </indexterm>
+ <listitem>
+ <para>Turns off the CPR (constructed product result)
+ analysis; it is somewhat experimental.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-funbox-strict-fields</option>:</term>
+ <listitem>
+ <indexterm><primary><option>-funbox-strict-fields</option></primary></indexterm>
+ <indexterm><primary>strict constructor fields</primary></indexterm>
+ <indexterm><primary>constructor fields, strict</primary></indexterm>
+
+ <para>This option causes all constructor fields which are
+ marked strict (i.e. “!”) to be unboxed or
+ unpacked if possible. For example:</para>
-<VarListEntry>
-<Term><Literal>-fwarn-incomplete-patterns</Literal>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-fwarn-incomplete-patterns option</Primary></IndexTerm>
-<IndexTerm><Primary>incomplete patterns, warning</Primary></IndexTerm>
-<IndexTerm><Primary>patterns, incomplete</Primary></IndexTerm>
-Similarly for incomplete patterns, the function <Literal>g</Literal> below will fail
-when applied to non-empty lists, so the compiler will emit a warning
-about this when <Literal>-fwarn-incomplete-patterns</Literal> is enabled.
-</Para>
-
-<Para>
<ProgramListing>
-g [] = 2
+data T = T !Float !Float
</ProgramListing>
-</Para>
-
-<Para>
-This option isn't enabled be default because it can be a bit noisy,
-and it doesn't always indicate a bug in the program. However, it's
-generally considered good practice to cover all the cases in your
-functions.
-</Para>
-</ListItem>
-</VarListEntry>
-
-<VarListEntry>
-<Term><Literal>-fwarn-missing-methods</Literal>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-fwarn-missing-methods option</Primary></IndexTerm>
-<IndexTerm><Primary>missing methods, warning</Primary></IndexTerm>
-<IndexTerm><Primary>methods, missing</Primary></IndexTerm>
-This option is on by default, and warns you whenever an instance
-declaration is missing one or more methods, and the corresponding
-class declaration has no default declaration for them.
-</Para>
-</ListItem>
-</VarListEntry>
-
-<VarListEntry>
-<Term><Literal>-fwarn-missing-fields</Literal>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-fwarn-missing-fields option</Primary></IndexTerm>
-<IndexTerm><Primary>missing fields, warning</Primary></IndexTerm>
-<IndexTerm><Primary>fields, missing</Primary></IndexTerm>
-This option is on by default, and warns you whenever the construction
-of a labelled field constructor isn't complete, missing initializers
-for one or more fields. While not an error (the missing fields are
-initialised with bottoms), it is often an indication of a programmer
-error.
-</Para>
-</ListItem>
-</VarListEntry>
-
-<VarListEntry>
-<Term><Literal>-fwarn-unused-imports</Literal>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-fwarn-unused-imports option</Primary></IndexTerm>
-<IndexTerm><Primary>unused imports, warning</Primary></IndexTerm>
-<IndexTerm><Primary>imports, unused</Primary></IndexTerm>
-Report any objects that are explicitly imported but never used.
-</Para>
-</ListItem>
-</VarListEntry>
-
-<VarListEntry>
-<Term><Literal>-fwarn-unused-binds</Literal>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-fwarn-unused-binds option</Primary></IndexTerm>
-<IndexTerm><Primary>unused binds, warning</Primary></IndexTerm>
-<IndexTerm><Primary>binds, unused</Primary></IndexTerm>
-Report any function definitions (and local bindings) which are unused.
-For top-level functions, the warning is only given if the binding is
-not exported.
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Literal>-fwarn-unused-matches</Literal>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-fwarn-unused-matches option</Primary></IndexTerm>
-<IndexTerm><Primary>unused matches, warning</Primary></IndexTerm>
-<IndexTerm><Primary>matches, unused</Primary></IndexTerm>
-Report all unused variables which arise from pattern matches,
-including patterns consisting of a single variable. For instance <Literal>f x
-y = []</Literal> would report <Literal>x</Literal> and <Literal>y</Literal> as unused. To eliminate the warning,
-all unused variables can be replaced with wildcards.
-</Para>
-</ListItem>
-</VarListEntry>
-
-<VarListEntry>
-<Term><Literal>-fwarn-duplicate-exports</Literal>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-fwarn-duplicate-exports option</Primary></IndexTerm>
-<IndexTerm><Primary>duplicate exports, warning</Primary></IndexTerm>
-<IndexTerm><Primary>export lists, duplicates</Primary></IndexTerm>
-Have the compiler warn about duplicate entries in export lists. This
-is useful information if you maintain large export lists, and want to
-avoid the continued export of a definition after you've deleted (one)
-mention of it in the export list.
-</Para>
-
-<Para>
-This option is on by default.
-</Para>
-</ListItem>
-</VarListEntry>
-
-<VarListEntry>
-<Term><Literal>-fwarn-type-defaults</Literal>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-fwarn-type-defaults option</Primary></IndexTerm>
-<IndexTerm><Primary>defaulting mechanism, warning</Primary></IndexTerm>
-Have the compiler warn/inform you where in your source the Haskell
-defaulting mechanism for numeric types kicks in. This is useful
-information when converting code from a context that assumed one
-default into one with another, e.g., the `default default' for Haskell
-1.4 caused the otherwise unconstrained value <Literal>1</Literal> to be given
-the type <Literal>Int</Literal>, whereas Haskell 98 defaults it to
-<Literal>Integer</Literal>. This may lead to differences in performance and
-behaviour, hence the usefulness of being non-silent about this.
-</Para>
-
-<Para>
-This warning is off by default.
-</Para>
-</ListItem>
-</VarListEntry>
-
-<VarListEntry>
-<Term><Literal>-fwarn-missing-signatures</Literal>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-fwarn-missing-signatures option</Primary></IndexTerm>
-<IndexTerm><Primary>type signatures, missing</Primary></IndexTerm>
-If you would like GHC to check that every top-level function/value has
-a type signature, use the <Literal>-fwarn-missing-signatures</Literal> option. This
-option is off by default.
-</Para>
-</ListItem>
-</VarListEntry>
-</VariableList>
-</Para>
-
-<Para>
-If you're feeling really paranoid, the <Literal>-dcore-lint</Literal>
-option<IndexTerm><Primary>-dcore-lint option</Primary></IndexTerm> is a good choice. It turns on
-heavyweight intra-pass sanity-checking within GHC. (It checks GHC's
-sanity, not yours.)
-</Para>
-
-</Sect1>
-
-<Sect1 id="separate-compilation">
-<Title>Separate compilation
-</Title>
-
-<Para>
-<IndexTerm><Primary>separate compilation</Primary></IndexTerm>
-<IndexTerm><Primary>recompilation checker</Primary></IndexTerm>
-<IndexTerm><Primary>make and recompilation</Primary></IndexTerm>
-</Para>
-
-<Para>
-This section describes how GHC supports separate compilation.
-</Para>
-
-<Sect2 id="hi-files">
-<Title>Interface files
-</Title>
-
-<Para>
-<IndexTerm><Primary>interface files</Primary></IndexTerm>
-<IndexTerm><Primary>.hi files</Primary></IndexTerm>
-</Para>
-
-<Para>
-When GHC compiles a source file <Literal>F</Literal> which contains a module <Literal>A</Literal>, say,
-it generates an object <Literal>F.o</Literal>, <Emphasis>and</Emphasis> a companion <Emphasis>interface
-file</Emphasis> <Literal>A.hi</Literal>. The interface file is not intended for human
-consumption, as you'll see if you take a look at one. It's merely
-there to help the compiler compile other modules in the same program.
-</Para>
-
-<Para>
-NOTE: Having the name of the interface file follow the module name and
-not the file name, means that working with tools such as <Literal>make(1)</Literal>
-become harder. <Literal>make</Literal> implicitly assumes that any output files
-produced by processing a translation unit will have file names that
-can be derived from the file name of the translation unit. For
-instance, pattern rules becomes unusable. For this reason, we
-recommend you stick to using the same file name as the module name.
-</Para>
-
-<Para>
-The interface file for <Literal>A</Literal> contains information needed by the compiler
-when it compiles any module <Literal>B</Literal> that imports <Literal>A</Literal>, whether directly or
-indirectly. When compiling <Literal>B</Literal>, GHC will read <Literal>A.hi</Literal> to find the
-details that it needs to know about things defined in <Literal>A</Literal>.
-</Para>
-
-<Para>
-Furthermore, when compiling module <Literal>C</Literal> which imports <Literal>B</Literal>, GHC may
-decide that it needs to know something about <Literal>A</Literal>—for example, <Literal>B</Literal>
-might export a function that involves a type defined in <Literal>A</Literal>. In this
-case, GHC will go and read <Literal>A.hi</Literal> even though <Literal>C</Literal> does not explicitly
-import <Literal>A</Literal> at all.
-</Para>
-
-<Para>
-The interface file may contain all sorts of things that aren't
-explicitly exported from <Literal>A</Literal> by the programmer. For example, even
-though a data type is exported abstractly, <Literal>A.hi</Literal> will contain the
-full data type definition. For small function definitions, <Literal>A.hi</Literal>
-will contain the complete definition of the function. For bigger
-functions, <Literal>A.hi</Literal> will contain strictness information about the
-function. And so on. GHC puts much more information into <Literal>.hi</Literal> files
-when optimisation is turned on with the <Literal>-O</Literal> flag. Without <Literal>-O</Literal> it
-puts in just the minimum; with <Literal>-O</Literal> it lobs in a whole pile of stuff.
-<IndexTerm><Primary>optimsation, effect on .hi files</Primary></IndexTerm>
-</Para>
-
-<Para>
-<Literal>A.hi</Literal> should really be thought of as a compiler-readable version of
-<Literal>A.o</Literal>. If you use a <Literal>.hi</Literal> file that wasn't generated by the same
-compilation run that generates the <Literal>.o</Literal> file the compiler may assume
-all sorts of incorrect things about <Literal>A</Literal>, resulting in core dumps and
-other unpleasant happenings.
-</Para>
-
-</Sect2>
-
-<Sect2 id="options-finding-imports">
-<Title>Finding interface files
-</Title>
-
-<Para>
-<IndexTerm><Primary>interface files, finding them</Primary></IndexTerm>
-<IndexTerm><Primary>finding interface files</Primary></IndexTerm>
-</Para>
-
-<Para>
-In your program, you import a module <Literal>Foo</Literal> by saying
-<Literal>import Foo</Literal>. GHC goes looking for an interface file, <Literal>Foo.hi</Literal>.
-It has a builtin list of directories (notably including <Literal>.</Literal>) where
-it looks.
-</Para>
-
-<Para>
-<VariableList>
-
-<VarListEntry>
-<Term><Literal>-i<dirs></Literal></Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-i<dirs> option</Primary></IndexTerm>This flag
-prepends a colon-separated list of <Literal>dirs</Literal> to the ``import
-directories'' list.
-See also <XRef LinkEnd="recomp"> for the significance of using
-relative and absolute pathnames in the <Literal>-i</Literal> list.
-</Para>
-</ListItem>
-</VarListEntry>
-
-<VarListEntry>
-<Term><Literal>-i</Literal></Term>
-<ListItem>
-<Para>
-resets the ``import directories'' list back to nothing.
-</Para>
-</ListItem>
-</VarListEntry>
-
-<VarListEntry>
-<Term><Literal>-fno-implicit-prelude</Literal></Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-fno-implicit-prelude option</Primary></IndexTerm>
-GHC normally imports <Literal>Prelude.hi</Literal> files for you. If you'd rather it
-didn't, then give it a <Literal>-fno-implicit-prelude</Literal> option. You are
-unlikely to get very far without a Prelude, but, hey, it's a free
-country.
-</Para>
-</ListItem>
-</VarListEntry>
-
-<VarListEntry>
-<Term><Literal>-syslib <lib></Literal></Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-syslib <lib> option</Primary></IndexTerm>
-If you are using a system-supplied non-Prelude library (e.g., the
-POSIX library), just use a <Literal>-syslib posix</Literal> option (for example). The
-right interface files should then be available. <XRef LinkEnd="ghc-prelude"> lists the
-libraries available by this mechanism.
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Literal>-I<dir></Literal></Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-I<dir> option</Primary></IndexTerm>
-Once a Haskell module has been compiled to C (<Literal>.hc</Literal> file), you may
-wish to specify where GHC tells the C compiler to look for <Literal>.h</Literal> files.
-(Or, if you are using the <Literal>-cpp</Literal> option<IndexTerm><Primary>-cpp option</Primary></IndexTerm>, where
-it tells the C pre-processor to look…) For this purpose, use a <Literal>-I</Literal>
-option in the usual C-ish way.
-</Para>
-</ListItem>
-</VarListEntry>
+ <para>will create a constructor <literal>T</literal>
+ containing two unboxed floats if the
+ <option>-funbox-strict-fields</option> flag is given.
+ This may not always be an optimisation: if the
+ <Function>T</Function> constructor is scrutinised and the
+ floats passed to a non-strict function for example, they
+ will have to be reboxed (this is done automatically by the
+ compiler).</para>
-</VariableList>
-</Para>
-
-</Sect2>
-
-<Sect2 id="hi-options">
-<Title>Other options related to interface files
-</Title>
-
-<Para>
-<IndexTerm><Primary>interface files, options</Primary></IndexTerm>
-The interface output may be directed to another file
-<Literal>bar2/Wurble.iface</Literal> with the option <Literal>-ohi bar2/Wurble.iface</Literal><IndexTerm><Primary>-ohi
-<file> option</Primary></IndexTerm> (not recommended).
-</Para>
-
-<Para>
-To avoid generating an interface file at all, use a <Literal>-nohi</Literal>
-option.<IndexTerm><Primary>-nohi option</Primary></IndexTerm>
-</Para>
-
-<Para>
-The compiler does not overwrite an existing <Literal>.hi</Literal> interface file if
-the new one is byte-for-byte the same as the old one; this is friendly
-to <Literal>make</Literal>. When an interface does change, it is often enlightening to
-be informed. The <Literal>-hi-diffs</Literal><IndexTerm><Primary>-hi-diffs option</Primary></IndexTerm> option will
-make <Literal>ghc</Literal> run <Literal>diff</Literal> on the old and new <Literal>.hi</Literal> files. You can also
-record the difference in the interface file itself, the
-<Literal>-keep-hi-diffs</Literal><IndexTerm><Primary>-keep-hi-diffs</Primary></IndexTerm> option takes care of that.
-</Para>
-
-<Para>
-The <Literal>.hi</Literal> files from GHC contain ``usage'' information which changes
-often and uninterestingly. If you really want to see these changes
-reported, you need to use the
-<Literal>-hi-diffs-with-usages</Literal><IndexTerm><Primary>-hi-diffs-with-usages option</Primary></IndexTerm>
-option.
-</Para>
-
-<Para>
-Interface files are normally jammed full of compiler-produced
-<Emphasis>pragmas</Emphasis>, which record arities, strictness info, etc. If you
-think these pragmas are messing you up (or you are doing some kind of
-weird experiment), you can tell GHC to ignore them with the
-<Literal>-fignore-interface-pragmas</Literal><IndexTerm><Primary>-fignore-interface-pragmas
-option</Primary></IndexTerm> option.
-</Para>
-
-<Para>
-When compiling without optimisations on, the compiler is extra-careful
-about not slurping in data constructors and instance declarations that
-it will not need. If you believe it is getting it wrong and not
-importing stuff which you think it should, this optimisation can be
-turned off with <Literal>-fno-prune-tydecls</Literal> and <Literal>-fno-prune-instdecls</Literal>.
-<IndexTerm><Primary>-fno-prune-tydecls option</Primary></IndexTerm><IndexTerm><Primary>-fno-prune-instdecls
-option</Primary></IndexTerm>
-</Para>
-
-<Para>
-See also <XRef LinkEnd="options-linker">, which describes how the linker finds standard
-Haskell libraries.
-</Para>
-
-</Sect2>
-
-<Sect2 id="recomp">
-<Title>The recompilation checker
-</Title>
-
-<Para>
-<IndexTerm><Primary>recompilation checker</Primary></IndexTerm>
-</Para>
-
-<Para>
-In the olden days, GHC compared the newly-generated <Literal>.hi</Literal> file with
-the previous version; if they were identical, it left the old one
-alone and didn't change its modification date. In consequence,
-importers of a module with an unchanged output <Literal>.hi</Literal> file were not
-recompiled.
-</Para>
-
-<Para>
-This doesn't work any more. In our earlier example, module <Literal>C</Literal> does
-not import module <Literal>A</Literal> directly, yet changes to <Literal>A.hi</Literal> should force a
-recompilation of <Literal>C</Literal>. And some changes to <Literal>A</Literal> (changing the
-definition of a function that appears in an inlining of a function
-exported by <Literal>B</Literal>, say) may conceivably not change <Literal>B.hi</Literal> one jot. So
-now…
-</Para>
-
-<Para>
-GHC keeps a version number on each interface file, and on each type
-signature within the interface file. It also keeps in every interface
-file a list of the version numbers of everything it used when it last
-compiled the file. If the source file's modification date is earlier
-than the <Literal>.o</Literal> file's date (i.e. the source hasn't changed since the
-file was last compiled), GHC will be clever. It compares the version
-numbers on the things it needs this time with the version numbers on
-the things it needed last time (gleaned from the interface file of the
-module being compiled); if they are all the same it stops compiling
-rather early in the process saying ``Compilation IS NOT required''.
-What a beautiful sight!
-</Para>
-
-<Para>
-GHC <Emphasis>only</Emphasis> keeps detailed dependency information for ``user'' modules,
-not for ``library'' modules. It distinguishes the two by a hack: a module
-whose <Literal>.hi</Literal> file has an absolute path name is considered a library module,
-while a relative path name indicates a user module. So if you have a
-multi-directory application, use <Emphasis>relative</Emphasis> path names in your
-<Literal>-i</Literal> path, to force GHC to record detailed dependency information.
-Use absolute path names only for directories containing slowly-changing
-library modules.
-</Para>
-
-<Para>
-A path is considered ``absolute'' if it starts with ``<Literal>/</Literal>'', or
-``<Literal>A:/</Literal>'', or ``<Literal>A:\</Literal>'' (or ``<Literal>B:/</Literal>'', ``<Literal>B:\</Literal>'' etc).
-</Para>
-
-<Para>
-Patrick Sansom had a workshop paper about how all this is done (though
-the details have changed quite a bit). Ask
-him (email: <ULink
-URL="mailto:sansom@dcs.gla.ac.uk"
->sansom@dcs.gla.ac.uk</ULink
->) if you want a copy.
-</Para>
-
-</Sect2>
-
-<Sect2 id="using-make">
-<Title>Using <Literal>make</Literal>
-</Title>
-
-<Para>
-<IndexTerm><Primary><literal>make</literal></Primary></IndexTerm>
-</Para>
-
-<Para>
-It is reasonably straightforward to set up a <Literal>Makefile</Literal> to use with
-GHC, assuming you name your source files the same as your modules.
-Thus:
-</Para>
-
-<Para>
+ <para>This option should only be used in conjunction with
+ <option>-O</option>, in order to expose unfoldings to the
+ compiler so the reboxing can be removed as often as
+ possible. For example:</para>
<ProgramListing>
-HC = ghc
-HC_OPTS = -cpp $(EXTRA_HC_OPTS)
-
-SRCS = Main.lhs Foo.lhs Bar.lhs
-OBJS = Main.o Foo.o Bar.o
-
-.SUFFIXES : .o .hi .lhs .hc .s
-
-cool_pgm : $(OBJS)
- rm $@
- $(HC) -o $@ $(HC_OPTS) $(OBJS)
-
-# Standard suffix rules
-.o.hi:
- @:
+f :: T -> Float
+f (T f1 f2) = f1 + f2
+</ProgramListing>
-.lhs.o:
- $(HC) -c $< $(HC_OPTS)
+ <para>The compiler will avoid reboxing
+ <Function>f1</Function> and <Function>f2</Function> by
+ inlining <Function>+</Function> on floats, but only when
+ <option>-O</option> is on.</para>
-.hs.o:
- $(HC) -c $< $(HC_OPTS)
+ <para>Any single-constructor data is eligible for
+ unpacking; for example</para>
-# Inter-module dependencies
-Foo.o Foo.hc Foo.s : Baz.hi # Foo imports Baz
-Main.o Main.hc Main.s : Foo.hi Baz.hi # Main imports Foo and Baz
+<ProgramListing>
+data T = T !(Int,Int)
</ProgramListing>
-</Para>
-
-<Para>
-(Sophisticated <Literal>make</Literal> variants may achieve some of the above more
-elegantly. Notably, <Literal>gmake</Literal>'s pattern rules let you write the more
-comprehensible:
-</Para>
-
-<Para>
+ <para>will store the two <literal>Int</literal>s directly
+ in the <Function>T</Function> constructor, by flattening
+ the pair. Multi-level unpacking is also supported:</para>
<ProgramListing>
-%.o : %.lhs
- $(HC) -c $< $(HC_OPTS)
+data T = T !S
+data S = S !Int !Int
</ProgramListing>
-</Para>
+ <para>will store two unboxed <literal>Int#</literal>s
+ directly in the <Function>T</Function> constructor.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-funfolding-update-in-place<n></option></term>
+ <indexterm><primary><option>-funfolding-update-in-place</option></primary></indexterm>
+ <listitem>
+ <para>Switches on an experimental "optimisation".
+ Switching it on makes the compiler a little keener to
+ inline a function that returns a constructor, if the
+ context is that of a thunk.
+<ProgramListing>
+ x = plusInt a b
+</ProgramListing>
+ If we inlined plusInt we might get an opportunity to use
+ update-in-place for the thunk 'x'.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-funfolding-interface-threshold<n></option>:</term>
+ <listitem>
+ <indexterm><primary><option>-funfolding-interface-threshold</option></primary></indexterm>
+ <indexterm><primary>inlining, controlling</primary></indexterm>
+ <indexterm><primary>unfolding, controlling</primary></indexterm>
+
+ <para>(Default: 30) By raising or lowering this number,
+ you can raise or lower the amount of pragmatic junk that
+ gets spewed into interface files. (An unfolding has a
+ “size” that reflects the cost in terms of
+ “code bloat” of expanding that unfolding in
+ another module. A bigger function would be assigned a
+ bigger cost.)</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-funfolding-creation-threshold<n></option>:</term>
+ <listitem>
+ <indexterm><primary><option>-funfolding-creation-threshold</option></primary></indexterm>
+ <indexterm><primary>inlining, controlling</primary></indexterm>
+ <indexterm><primary>unfolding, controlling</primary></indexterm>
+
+ <para>(Default: 30) This option is similar to
+ <option>-funfolding-interface-threshold</option>, except
+ that it governs unfoldings within a single module.
+ Increasing this figure is more likely to result in longer
+ compile times than faster code. The next option is more
+ useful:</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-funfolding-use-threshold<n></option>:</term>
+ <listitem>
+ <indexterm><primary><option>-funfolding-use-threshold</option></primary></indexterm>
+ <indexterm><primary>inlining, controlling</primary></indexterm>
+ <indexterm><primary>unfolding, controlling</primary></indexterm>
+
+ <para>(Default: 8) This is the magic cut-off figure for
+ unfolding: below this size, a function definition will be
+ unfolded at the call-site, any bigger and it won't. The
+ size computed for a function depends on two things: the
+ actual size of the expression minus any discounts that
+ apply (see <option>-funfolding-con-discount</option>).</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ </sect2>
+
+ </sect1>
+
+&phases;
+
+<Sect1 id="sec-using-concurrent">
+<title>Using Concurrent Haskell</title>
+
+<para>
+<indexterm><primary>Concurrent Haskell—use</primary></indexterm>
+</para>
+
+<para>
+GHC (as of version 4.00) supports Concurrent Haskell by default,
+without requiring a special option or libraries compiled in a certain
+way. To get access to the support libraries for Concurrent Haskell
+(i.e. <literal>Concurrent</literal> and friends), use the
+<option>-package concurrent</option> option.
+</para>
-<Para>
-What we've shown should work with any <Literal>make</Literal>.)
-</Para>
+<para>
+Three RTS options are provided for modifying the behaviour of the
+threaded runtime system. See the descriptions of
+<option>-C[<us>]</option>, <option>-q</option>, and
+<option>-t<num></option> in <XRef LinkEnd="parallel-rts-opts">.
+</para>
-<Para>
-Note the cheesy <Literal>.o.hi</Literal> rule: It records the dependency of the
-interface (<Literal>.hi</Literal>) file on the source. The rule says a <Literal>.hi</Literal> file can
-be made from a <Literal>.o</Literal> file by doing…nothing. Which is true.
-</Para>
+<para>
+Concurrent Haskell is described in more detail in <XRef
+LinkEnd="sec-Concurrent">.
+</para>
-<Para>
-Note the inter-module dependencies at the end of the Makefile, which
-take the form
-</Para>
+</Sect1>
-<Para>
+<Sect1 id="sec-using-parallel">
+<title>Using Parallel Haskell</title>
-<ProgramListing>
-Foo.o Foo.hc Foo.s : Baz.hi # Foo imports Baz
-</ProgramListing>
+<para>
+<indexterm><primary>Parallel Haskell—use</primary></indexterm>
+</para>
-</Para>
+<para>
+[You won't be able to execute parallel Haskell programs unless PVM3
+(Parallel Virtual Machine, version 3) is installed at your site.]
+</para>
-<Para>
-They tell <Literal>make</Literal> that if any of <Literal>Foo.o</Literal>, <Literal>Foo.hc</Literal> or <Literal>Foo.s</Literal> have an
-earlier modification date than <Literal>Baz.hi</Literal>, then the out-of-date file
-must be brought up to date. To bring it up to date, <Literal>make</Literal> looks for
-a rule to do so; one of the preceding suffix rules does the job
-nicely.
-</Para>
+<para>
+To compile a Haskell program for parallel execution under PVM, use the
+<option>-parallel</option> option,<indexterm><primary>-parallel
+option</primary></indexterm> both when compiling <emphasis>and
+linking</emphasis>. You will probably want to <literal>import
+Parallel</literal> into your Haskell modules.
+</para>
+
+<para>
+To run your parallel program, once PVM is going, just invoke it
+“as normal”. The main extra RTS option is
+<option>-N<n></option>, to say how many PVM
+“processors” your program to run on. (For more details of
+all relevant RTS options, please see <XRef
+LinkEnd="parallel-rts-opts">.)
+</para>
+
+<para>
+In truth, running Parallel Haskell programs and getting information
+out of them (e.g., parallelism profiles) is a battle with the vagaries of
+PVM, detailed in the following sections.
+</para>
-<Para>
-Putting inter-dependencies of the form <Literal>Foo.o : Bar.hi</Literal> into your
-<Literal>Makefile</Literal> by hand is rather error-prone. Don't worry—never fear,
-<Literal>mkdependHS</Literal> is here! (and is distributed as part of GHC) Add the
-following to your <Literal>Makefile</Literal>:
-</Para>
+<sect2>
+<title>Dummy's guide to using PVM</title>
-<Para>
+<para>
+<indexterm><primary>PVM, how to use</primary></indexterm>
+<indexterm><primary>Parallel Haskell—PVM use</primary></indexterm>
+Before you can run a parallel program under PVM, you must set the
+required environment variables (PVM's idea, not ours); something like,
+probably in your <filename>.cshrc</filename> or equivalent:
<ProgramListing>
-depend :
- mkdependHS -- $(HC_OPTS) -- $(SRCS)
+setenv PVM_ROOT /wherever/you/put/it
+setenv PVM_ARCH `$PVM_ROOT/lib/pvmgetarch`
+setenv PVM_DPATH $PVM_ROOT/lib/pvmd
</ProgramListing>
-</Para>
+</para>
-<Para>
-Now, before you start compiling, and any time you change the <Literal>imports</Literal>
-in your program, do <Literal>make depend</Literal> before you do <Literal>make cool_pgm</Literal>.
-<Literal>mkdependHS</Literal> will append the needed dependencies to your <Literal>Makefile</Literal>.
-<Literal>mkdependHS</Literal> is fully described in <XRef LinkEnd="mkdependHS">.
-</Para>
-
-<Para>
-A few caveats about this simple scheme:
-</Para>
+<para>
+Creating and/or controlling your “parallel machine” is a purely-PVM
+business; nothing specific to Parallel Haskell.
+</para>
-<Para>
+<para>
+You use the <command>pvm</command><indexterm><primary>pvm command</primary></indexterm> command to start PVM on your
+machine. You can then do various things to control/monitor your
+“parallel machine;” the most useful being:
+</para>
-<ItemizedList>
-<ListItem>
+<para>
+<InformalTable>
+<TGroup Cols=2>
+<ColSpec Align="Left">
+<TBody>
-<Para>
- You may need to compile some modules explicitly to create their
-interfaces in the first place (e.g., <Literal>make Bar.o</Literal> to create <Literal>Bar.hi</Literal>).
+<Row>
+<Entry><KeyCombo><KeyCap>Control</KeyCap><KeyCap>D</KeyCap></KeyCombo></Entry>
+<Entry>exit <command>pvm</command>, leaving it running</Entry>
+</Row>
-</Para>
-</ListItem>
-<ListItem>
+<Row>
+<Entry><command>halt</command></Entry>
+<Entry>kill off this “parallel machine” & exit</Entry>
+</Row>
-<Para>
- You may have to type <Literal>make</Literal> more than once for the dependencies
-to have full effect. However, a <Literal>make</Literal> run that does nothing
-<Emphasis>does</Emphasis> mean ``everything's up-to-date.''
+<Row>
+<Entry><command>add <host></command></Entry>
+<Entry>add <command><host></command> as a processor</Entry>
+</Row>
-</Para>
-</ListItem>
-<ListItem>
+<Row>
+<Entry><command>delete <host></command></Entry>
+<Entry>delete <command><host></command></Entry>
+</Row>
-<Para>
- This scheme will work with mutually-recursive modules but,
-again, it may take multiple iterations to ``settle.''
+<Row>
+<Entry><command>reset</command></Entry>
+<Entry>kill what's going, but leave PVM up</Entry>
+</Row>
-</Para>
-</ListItem>
+<Row>
+<Entry><command>conf</command></Entry>
+<Entry>list the current configuration</Entry>
+</Row>
-</ItemizedList>
+<Row>
+<Entry><command>ps</command></Entry>
+<Entry>report processes' status</Entry>
+</Row>
-</Para>
+<Row>
+<Entry><command>pstat <pid></command></Entry>
+<Entry>status of a particular process</Entry>
+</Row>
-</Sect2>
+</TBody>
+</TGroup>
+</InformalTable>
+</para>
-<Sect2 id="mutual-recursion">
-<Title>How to compile mutually recursive modules
-</Title>
+<para>
+The PVM documentation can tell you much, much more about <command>pvm</command>!
+</para>
-<Para>
-<IndexTerm><Primary>module system, recursion</Primary></IndexTerm>
-<IndexTerm><Primary>recursion, between modules</Primary></IndexTerm>
-</Para>
+</sect2>
-<Para>
-Currently, the compiler does not have proper support for dealing with
-mutually recursive modules:
-</Para>
+<sect2>
+<title>Parallelism profiles</title>
-<Para>
+<para>
+<indexterm><primary>parallelism profiles</primary></indexterm>
+<indexterm><primary>profiles, parallelism</primary></indexterm>
+<indexterm><primary>visualisation tools</primary></indexterm>
+</para>
-<ProgramListing>
-module A where
+<para>
+With Parallel Haskell programs, we usually don't care about the
+results—only with “how parallel” it was! We want pretty pictures.
+</para>
-import B
+<para>
+Parallelism profiles (à la <command>hbcpp</command>) can be generated with the
+<option>-q</option><indexterm><primary>-q RTS option (concurrent, parallel)</primary></indexterm> RTS option. The
+per-processor profiling info is dumped into files named
+<filename><full-path><program>.gr</filename>. These are then munged into a PostScript picture,
+which you can then display. For example, to run your program
+<filename>a.out</filename> on 8 processors, then view the parallelism profile, do:
+</para>
-newtype TA = MkTA Int
+<para>
-f :: TB -> TA
-f (MkTB x) = MkTA x
---------
-module B where
+<Screen>
+% ./a.out +RTS -N8 -q
+% grs2gr *.???.gr > temp.gr # combine the 8 .gr files into one
+% gr2ps -O temp.gr # cvt to .ps; output in temp.ps
+% ghostview -seascape temp.ps # look at it!
+</Screen>
-import A
+</para>
-data TB = MkTB !Int
+<para>
+The scripts for processing the parallelism profiles are distributed
+in <filename>ghc/utils/parallel/</filename>.
+</para>
-g :: TA -> TB
-g (MkTA x) = MkTB x
-</ProgramListing>
+</sect2>
-</Para>
+<sect2>
+<title>Other useful info about running parallel programs</title>
-<Para>
-When compiling either module A and B, the compiler will try (in vain)
-to look for the interface file of the other. So, to get mutually
-recursive modules off the ground, you need to hand write an interface
-file for A or B, so as to break the loop. These hand-written
-interface files are called <Literal>hi-boot</Literal> files, and are placed in a file
-called <Literal><module>.hi-boot</Literal>. To import from an <Literal>hi-boot</Literal> file instead
-of the standard <Literal>.hi</Literal> file, use the following syntax in the importing module:
-<IndexTerm><Primary>hi-boot files</Primary></IndexTerm>
-<IndexTerm><Primary>importing, hi-boot files</Primary></IndexTerm>
-</Para>
+<para>
+The “garbage-collection statistics” RTS options can be useful for
+seeing what parallel programs are doing. If you do either
+<option>+RTS -Sstderr</option><indexterm><primary>-Sstderr RTS option</primary></indexterm> or <option>+RTS -sstderr</option>, then
+you'll get mutator, garbage-collection, etc., times on standard
+error. The standard error of all PE's other than the `main thread'
+appears in <filename>/tmp/pvml.nnn</filename>, courtesy of PVM.
+</para>
-<Para>
+<para>
+Whether doing <option>+RTS -Sstderr</option> or not, a handy way to watch
+what's happening overall is: <command>tail -f /tmp/pvml.nnn</command>.
+</para>
-<ProgramListing>
-import {-# SOURCE #-} A
-</ProgramListing>
+</sect2>
-</Para>
+<Sect2 id="parallel-rts-opts">
+<title>RTS options for Concurrent/Parallel Haskell
+</title>
-<Para>
-The hand-written interface need only contain the bare minimum of
-information needed to get the bootstrapping process started. For
-example, it doesn't need to contain declarations for <Emphasis>everything</Emphasis>
-that module <Literal>A</Literal> exports, only the things required by the module that
-imports <Literal>A</Literal> recursively.
-</Para>
+<para>
+<indexterm><primary>RTS options, concurrent</primary></indexterm>
+<indexterm><primary>RTS options, parallel</primary></indexterm>
+<indexterm><primary>Concurrent Haskell—RTS options</primary></indexterm>
+<indexterm><primary>Parallel Haskell—RTS options</primary></indexterm>
+</para>
-<Para>
-For the example at hand, the boot interface file for A would look like
-the following:
-</Para>
+<para>
+Besides the usual runtime system (RTS) options
+(<XRef LinkEnd="runtime-control">), there are a few options particularly
+for concurrent/parallel execution.
+</para>
-<Para>
+<para>
+<VariableList>
-<ProgramListing>
-__interface A 1 404 where
-__export A TA{MkTA} ;
-1 newtype TA = MkTA PrelBase.Int ;
-</ProgramListing>
+<varlistentry>
+<term><option>-N<N></option>:</term>
+<listitem>
+<para>
+<indexterm><primary>-N<N> RTS option (parallel)</primary></indexterm>
+(PARALLEL ONLY) Use <literal><N></literal> PVM processors to run this program;
+the default is 2.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><option>-C[<us>]</option>:</term>
+<listitem>
+<para>
+<indexterm><primary>-C<us> RTS option</primary></indexterm> Sets
+the context switch interval to <literal><s></literal> seconds.
+A context switch will occur at the next heap block allocation after
+the timer expires (a heap block allocation occurs every 4k of
+allocation). With <option>-C0</option> or <option>-C</option>,
+context switches will occur as often as possible (at every heap block
+allocation). By default, context switches occur every 20ms
+milliseconds. Note that GHC's internal timer ticks every 20ms, and
+the context switch timer is always a multiple of this timer, so 20ms
+is the maximum granularity available for timed context switches.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><option>-q[v]</option>:</term>
+<listitem>
+<para>
+<indexterm><primary>-q RTS option</primary></indexterm>
+(PARALLEL ONLY) Produce a quasi-parallel profile of thread activity,
+in the file <FIlename><program>.qp</FIlename>. In the style of <command>hbcpp</command>, this profile
+records the movement of threads between the green (runnable) and red
+(blocked) queues. If you specify the verbose suboption (<option>-qv</option>), the
+green queue is split into green (for the currently running thread
+only) and amber (for other runnable threads). We do not recommend
+that you use the verbose suboption if you are planning to use the
+<command>hbcpp</command> profiling tools or if you are context switching at every heap
+check (with <option>-C</option>).
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><option>-t<num></option>:</term>
+<listitem>
+<para>
+<indexterm><primary>-t<num> RTS option</primary></indexterm>
+(PARALLEL ONLY) Limit the number of concurrent threads per processor
+to <literal><num></literal>. The default is 32. Each thread requires slightly over 1K
+<emphasis>words</emphasis> in the heap for thread state and stack objects. (For
+32-bit machines, this translates to 4K bytes, and for 64-bit machines,
+8K bytes.)
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><option>-d</option>:</term>
+<listitem>
+<para>
+<indexterm><primary>-d RTS option (parallel)</primary></indexterm>
+(PARALLEL ONLY) Turn on debugging. It pops up one xterm (or GDB, or
+something…) per PVM processor. We use the standard <command>debugger</command>
+script that comes with PVM3, but we sometimes meddle with the
+<command>debugger2</command> script. We include ours in the GHC distribution,
+in <filename>ghc/utils/pvm/</filename>.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><option>-e<num></option>:</term>
+<listitem>
+<para>
+<indexterm><primary>-e<num> RTS option (parallel)</primary></indexterm>
+(PARALLEL ONLY) Limit the number of pending sparks per processor to
+<literal><num></literal>. The default is 100. A larger number may be appropriate if
+your program generates large amounts of parallelism initially.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><option>-Q<num></option>:</term>
+<listitem>
+<para>
+<indexterm><primary>-Q<num> RTS option (parallel)</primary></indexterm>
+(PARALLEL ONLY) Set the size of packets transmitted between processors
+to <literal><num></literal>. The default is 1024 words. A larger number may be
+appropriate if your machine has a high communication cost relative to
+computation speed.
+</para>
+</listitem>
+</varlistentry>
+</VariableList>
+</para>
-</Para>
-
-<Para>
-The syntax is essentially the same as a normal <Literal>.hi</Literal> file
-(unfortunately), but you can usually tailor an existing <Literal>.hi</Literal> file to
-make a <Literal>.hi-boot</Literal> file.
-</Para>
-
-<Para>
-Notice that we only put the declaration for the newtype <Literal>TA</Literal> in the
-<Literal>hi-boot</Literal> file, not the signature for <Literal>f</Literal>, since <Literal>f</Literal> isn't used by
-<Literal>B</Literal>.
-</Para>
-
-<Para>
-The number ``1'' after ``__interface A'' gives the version number of module A;
-it is incremented whenever anything in A's interface file changes. The ``404'' is
-the version number of the interface file <Emphasis>syntax</Emphasis>; we change it when
-we change the syntax of interface files so that you get a better error message when
-you try to read an old-format file with a new-format compiler.
-</Para>
-
-<Para>
-The number ``1'' at the beginning of a declaration is the <Emphasis>version
-number</Emphasis> of that declaration: for the purposes of <Literal>.hi-boot</Literal> files
-these can all be set to 1. All names must be fully qualified with the
-<Emphasis>original</Emphasis> module that an object comes from: for example, the
-reference to <Literal>Int</Literal> in the interface for <Literal>A</Literal> comes from <Literal>PrelBase</Literal>,
-which is a module internal to GHC's prelude. It's a pain, but that's
-the way it is.
-</Para>
-
-<Para>
-If you want an hi-boot file to export a data type, but you don't want to give its constructors
-(because the constructors aren't used by the SOURCE-importing module), you can write simply:
-</Para>
-
-<Para>
+</sect2>
-<ProgramListing>
-__interface A 1 404 where
-__export A TA;
-1 data TA
-</ProgramListing>
+</Sect1>
-</Para>
+ <sect1 id="options-platform">
+ <title>Platform-specific Flags</title>
+
+ <indexterm><primary>-m* options</primary></indexterm>
+ <indexterm><primary>platform-specific options</primary></indexterm>
+ <indexterm><primary>machine-specific options</primary></indexterm>
+
+ <para>Some flags only make sense for particular target
+ platforms.</para>
+
+ <variablelist>
+
+ <varlistentry>
+ <term><option>-mv8</option>:</term>
+ <listitem>
+ <para>(SPARC machines)<indexterm><primary>-mv8 option (SPARC
+ only)</primary></indexterm> Means to pass the like-named
+ option to GCC; it says to use the Version 8 SPARC
+ instructions, notably integer multiply and divide. The
+ similiar <option>-m*</option> GCC options for SPARC also
+ work, actually.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-mlong-calls</option>:</term>
+ <listitem>
+ <para>(HPPA machines)<indexterm><primary>-mlong-calls option
+ (HPPA only)</primary></indexterm> Means to pass the
+ like-named option to GCC. Required for Very Big modules,
+ maybe. (Probably means you're in trouble…)</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-monly-[32]-regs</option>:</term>
+ <listitem>
+ <para>(iX86 machines)<indexterm><primary>-monly-N-regs
+ option (iX86 only)</primary></indexterm> GHC tries to
+ “steal” four registers from GCC, for performance
+ reasons; it almost always works. However, when GCC is
+ compiling some modules with four stolen registers, it will
+ crash, probably saying:
-<Para>
-(You must write all the type parameters, but leave out the '=' and everything that follows it.)
-</Para>
+<Screen>
+Foo.hc:533: fixed or forbidden register was spilled.
+This may be due to a compiler bug or to impossible asm
+statements or clauses.
+</Screen>
-<Para>
-<Emphasis>Note:</Emphasis> This is all a temporary solution, a version of the
-compiler that handles mutually recursive modules properly without the manual
-construction of interface files, is (allegedly) in the works.
-</Para>
+ Just give some registers back with
+ <option>-monly-N-regs</option>. Try `3' first, then `2'.
+ If `2' doesn't work, please report the bug to us.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
-</Sect2>
+ </sect1>
-</Sect1>
+&runtime
+&debug
+&flags
-<Sect1 id="options-optimise">
-<Title>Optimisation (code improvement)
-</Title>
-
-<Para>
-<IndexTerm><Primary>optimisation (GHC)</Primary></IndexTerm>
-<IndexTerm><Primary>improvement, code (GHC)</Primary></IndexTerm>
-</Para>
-
-<Para>
-The <Literal>-O*</Literal> options specify convenient ``packages'' of optimisation
-flags; the <Literal>-f*</Literal> options described later on specify
-<Emphasis>individual</Emphasis> optimisations to be turned on/off; the <Literal>-m*</Literal>
-options specify <Emphasis>machine-specific</Emphasis> optimisations to be turned
-on/off.
-</Para>
-
-<Sect2 id="optimise-pkgs">
-<Title><Literal>-O*</Literal>: convenient ``packages'' of optimisation flags.
-</Title>
-
-<Para>
-<IndexTerm><Primary>-O options</Primary></IndexTerm>
-</Para>
-
-<Para>
-There are <Emphasis>many</Emphasis> options that affect the quality of code
-produced by GHC. Most people only have a general goal, something like
-``Compile quickly'' or ``Make my program run like greased lightning.''
-The following ``packages'' of optimisations (or lack thereof) should
-suffice.
-</Para>
-
-<Para>
-Once you choose a <Literal>-O*</Literal> ``package,'' stick with it—don't chop and
-change. Modules' interfaces <Emphasis>will</Emphasis> change with a shift to a new
-<Literal>-O*</Literal> option, and you may have to recompile a large chunk of all
-importing modules before your program can again be run
-safely (see <XRef LinkEnd="recomp">).
-</Para>
-
-<Para>
-<VariableList>
+</Chapter>
-<VarListEntry>
-<Term>No <Literal>-O*</Literal>-type option specified:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-O* not specified</Primary></IndexTerm>
-This is taken to mean: ``Please compile quickly; I'm not over-bothered
-about compiled-code quality.'' So, for example: <Literal>ghc -c Foo.hs</Literal>
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Literal>-O</Literal> or <Literal>-O1</Literal>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-O option</Primary></IndexTerm>
-<IndexTerm><Primary>-O1 option</Primary></IndexTerm>
-<IndexTerm><Primary>optimise normally</Primary></IndexTerm>
-Means: ``Generate good-quality code without taking too long about it.''
-Thus, for example: <Literal>ghc -c -O Main.lhs</Literal>
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Literal>-O2</Literal>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-O2 option</Primary></IndexTerm>
-<IndexTerm><Primary>optimise aggressively</Primary></IndexTerm>
-Means: ``Apply every non-dangerous optimisation, even if it means
-significantly longer compile times.''
-</Para>
-
-<Para>
-The avoided ``dangerous'' optimisations are those that can make
-runtime or space <Emphasis>worse</Emphasis> if you're unlucky. They are
-normally turned on or off individually.
-</Para>
-
-<Para>
-At the moment, <Literal>-O2</Literal> is <Emphasis>unlikely</Emphasis> to produce
-better code than <Literal>-O</Literal>.
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Literal>-O2-for-C</Literal>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-O2-for-C option</Primary></IndexTerm>
-<IndexTerm><Primary>gcc, invoking with -O2</Primary></IndexTerm>
-</Para>
-
-<Para>
-Says to run GCC with <Literal>-O2</Literal>, which may be worth a few percent in
-execution speed. Don't forget <Literal>-fvia-C</Literal>, lest you use the native-code
-generator and bypass GCC altogether!
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Literal>-Onot</Literal>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-Onot option</Primary></IndexTerm>
-<IndexTerm><Primary>optimising, reset</Primary></IndexTerm>
-</Para>
-
-<Para>
-This option will make GHC ``forget'' any <Literal>-O</Literal>ish options it has seen so
-far. Sometimes useful; for example: <Literal>make all EXTRA_HC_OPTS=-Onot</Literal>.
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Literal>-Ofile <file></Literal>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-Ofile <file> option</Primary></IndexTerm>
-<IndexTerm><Primary>optimising, customised</Primary></IndexTerm>
-</Para>
-
-<Para>
-For those who need <Emphasis>absolute</Emphasis> control over <Emphasis>exactly</Emphasis>
-what options are used (e.g., compiler writers, sometimes :-), a list
-of options can be put in a file and then slurped in with <Literal>-Ofile</Literal>.
-</Para>
-
-<Para>
-In that file, comments are of the <Literal>#</Literal>-to-end-of-line variety; blank
-lines and most whitespace is ignored.
-</Para>
-
-<Para>
-Please ask if you are baffled and would like an example of <Literal>-Ofile</Literal>!
-</Para>
-</ListItem>
-</VarListEntry>
-</VariableList>
-</Para>
-
-<Para>
-At Glasgow, we don't use a <Literal>-O*</Literal> flag for day-to-day work. We use
-<Literal>-O</Literal> to get respectable speed; e.g., when we want to measure
-something. When we want to go for broke, we tend to use <Literal>-O -fvia-C
--O2-for-C</Literal> (and we go for lots of coffee breaks).
-</Para>
-
-<Para>
-The easiest way to see what <Literal>-O</Literal> (etc.) ``really mean'' is to run with
-<Literal>-v</Literal>, then stand back in amazement. Alternatively, just look at the
-<Literal>HsC_minus<blah></Literal> lists in the <Literal>ghc</Literal> driver script.
-</Para>
-
-</Sect2>
-
-<Sect2>
-<Title><Literal>-f*</Literal>: platform-independent flags</Title>
-
-<Para>
-<IndexTerm><Primary>-f* options (GHC)</Primary></IndexTerm>
-<IndexTerm><Primary>-fno-* options (GHC)</Primary></IndexTerm>
-</Para>
-
-<Para>
-Flags can be turned <Emphasis>off</Emphasis> individually. (NB: I hope you have a
-good reason for doing this…) To turn off the <Literal>-ffoo</Literal> flag, just use
-the <Literal>-fno-foo</Literal> flag.<IndexTerm><Primary>-fno-<opt> anti-option</Primary></IndexTerm> So, for
-example, you can say <Literal>-O2 -fno-strictness</Literal>, which will then drop out
-any running of the strictness analyser.
-</Para>
-
-<Para>
-The options you are most likely to want to turn off are:
-
-<ItemizedList>
-<ListItem>
-
-<Para>
-<Literal>-fno-strictness</Literal><IndexTerm><Primary>-fno-strictness option</Primary></IndexTerm> (strictness
-analyser, because it is sometimes slow),
-</Para>
-</ListItem>
-<ListItem>
-
-<Para>
-<Literal>-fno-specialise</Literal><IndexTerm><Primary>-fno-specialise option</Primary></IndexTerm> (automatic
-specialisation of overloaded functions, because it can make your code
-bigger) (US spelling also accepted), and
-</Para>
-</ListItem>
-<ListItem>
-
-<Para>
-<Literal>-fno-cpr-analyse</Literal><IndexTerm><Primary>-fno-cpr-analyse option</Primary></IndexTerm> switches off the CPR (constructed product
-result) analyser.
-</Para>
-</ListItem>
-
-</ItemizedList>
-
-</Para>
-
-<Para>
-Should you wish to turn individual flags <Emphasis>on</Emphasis>, you are advised
-to use the <Literal>-Ofile</Literal> option, described above. Because the order in
-which optimisation passes are run is sometimes crucial, it's quite
-hard to do with command-line options.
-</Para>
-
-<Para>
-Here are some ``dangerous'' optimisations you <Emphasis>might</Emphasis> want to try:
-<VariableList>
-
-<VarListEntry>
-<Term><Literal>-fvia-C</Literal>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-fvia-C option</Primary></IndexTerm>
-<IndexTerm><Primary>native code generator, turning off</Primary></IndexTerm>
-</Para>
-
-<Para>
-Compile via C, and don't use the native-code generator. (There are
-many cases when GHC does this on its own.) You might pick up a little
-bit of speed by compiling via C. If you use <Literal>_ccall_gc_</Literal>s or
-<Literal>_casm_</Literal>s, you probably <Emphasis>have</Emphasis> to use <Literal>-fvia-C</Literal>.
-</Para>
-
-<Para>
-The lower-case incantation, <Literal>-fvia-c</Literal>, is synonymous.
-</Para>
-
-<Para>
-Compiling via C will probably be slower (in compilation time) than
-using GHC's native code generator.
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Literal>-funfolding-interface-threshold<n></Literal>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-funfolding-interface-threshold option</Primary></IndexTerm>
-<IndexTerm><Primary>inlining, controlling</Primary></IndexTerm>
-<IndexTerm><Primary>unfolding, controlling</Primary></IndexTerm>
-(Default: 30) By raising or lowering this number, you can raise or
-lower the amount of pragmatic junk that gets spewed into interface
-files. (An unfolding has a ``size'' that reflects the cost in terms
-of ``code bloat'' of expanding that unfolding in another module. A
-bigger function would be assigned a bigger cost.)
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Literal>-funfolding-creation-threshold<n></Literal>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-funfolding-creation-threshold option</Primary></IndexTerm>
-<IndexTerm><Primary>inlining, controlling</Primary></IndexTerm>
-<IndexTerm><Primary>unfolding, controlling</Primary></IndexTerm>
-(Default: 30) This option is similar to
-<Literal>-funfolding-interface-threshold</Literal>, except that it governs unfoldings
-within a single module. Increasing this figure is more likely to
-result in longer compile times than faster code. The next option is
-more useful:
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Literal>-funfolding-use-threshold<n></Literal>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-funfolding-use-threshold option</Primary></IndexTerm>
-<IndexTerm><Primary>inlining, controlling</Primary></IndexTerm>
-<IndexTerm><Primary>unfolding, controlling</Primary></IndexTerm>
-(Default: 8) This is the magic cut-off figure for unfolding: below
-this size, a function definition will be unfolded at the call-site,
-any bigger and it won't. The size computed for a function depends on
-two things: the actual size of the expression minus any discounts that
-apply (see <Literal>-funfolding-con-discount</Literal>).
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Literal>-funfolding-con-discount<n></Literal>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-funfolding-con-discount option</Primary></IndexTerm>
-<IndexTerm><Primary>inlining, controlling</Primary></IndexTerm>
-<IndexTerm><Primary>unfolding, controlling</Primary></IndexTerm>
-(Default: 2) If the compiler decides that it can eliminate some
-computation by performing an unfolding, then this is a discount factor
-that it applies to the funciton size before deciding whether to unfold
-it or not.
-</Para>
-
-<Para>
-OK, folks, these magic numbers `30', `8', and '2' are mildly
-arbitrary; they are of the ``seem to be OK'' variety. The `8' is the
-more critical one; it's what determines how eager GHC is about
-expanding unfoldings.
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Literal>-funbox-strict-fields</Literal>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-funbox-strict-fields option</Primary></IndexTerm>
-<IndexTerm><Primary>strict constructor fields</Primary></IndexTerm>
-<IndexTerm><Primary>constructor fields, strict</Primary></IndexTerm>
-</Para>
-
-<Para>
-This option causes all constructor fields which are marked strict
-(i.e. ``!'') to be unboxed or unpacked if possible. For example:
-</Para>
-
-<Para>
-
-<ProgramListing>
-data T = T !Float !Float
-</ProgramListing>
-
-</Para>
-
-<Para>
-will create a constructor <Literal>T</Literal> containing two unboxed floats if the
-<Literal>-funbox-strict-fields</Literal> flag is given. This may not always be an
-optimisation: if the <Literal>T</Literal> constructor is scrutinised and the floats
-passed to a non-strict function for example, they will have to be
-reboxed (this is done automatically by the compiler).
-</Para>
-
-<Para>
-This option should only be used in conjunction with <Literal>-O</Literal>, in order to
-expose unfoldings to the compiler so the reboxing can be removed as
-often as possible. For example:
-</Para>
-
-<Para>
-
-<ProgramListing>
-f :: T -> Float
-f (T f1 f2) = f1 + f2
-</ProgramListing>
-
-</Para>
-
-<Para>
-The compiler will avoid reboxing <Literal>f1</Literal> and <Literal>f2</Literal> by inlining <Literal>+</Literal> on
-floats, but only when <Literal>-O</Literal> is on.
-</Para>
-
-<Para>
-Any single-constructor data is eligible for unpacking; for example
-</Para>
-
-<Para>
-
-<ProgramListing>
-data T = T !(Int,Int)
-</ProgramListing>
-
-</Para>
-
-<Para>
-will store the two <Literal>Int</Literal>s directly in the <Literal>T</Literal> constructor, by flattening
-the pair. Multi-level unpacking is also supported:
-</Para>
-
-<Para>
-
-<ProgramListing>
-data T = T !S
-data S = S !Int !Int
-</ProgramListing>
-
-</Para>
-
-<Para>
-will store two unboxed <Literal>Int#</Literal>s directly in the <Literal>T</Literal> constructor.
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Literal>-fsemi-tagging</Literal>:</Term>
-<ListItem>
-<Para>
-This option (which <Emphasis>does not work</Emphasis> with the native-code generator)
-tells the compiler to add extra code to test for already-evaluated
-values. You win if you have lots of such values during a run of your
-program, you lose otherwise. (And you pay in extra code space.)
-</Para>
-
-<Para>
-We have not played with <Literal>-fsemi-tagging</Literal> enough to recommend it.
-(For all we know, it doesn't even work anymore… Sigh.)
-</Para>
-</ListItem>
-</VarListEntry>
-</VariableList>
-</Para>
-
-</Sect2>
-
-<Sect2>
-<Title><Literal>-m*</Literal>: platform-specific flags</Title>
-
-<Para>
-<IndexTerm><Primary>-m* options (GHC)</Primary></IndexTerm>
-<IndexTerm><Primary>platform-specific options</Primary></IndexTerm>
-<IndexTerm><Primary>machine-specific options</Primary></IndexTerm>
-</Para>
-
-<Para>
-Some flags only make sense for particular target platforms.
-</Para>
-
-<Para>
-<VariableList>
-
-<VarListEntry>
-<Term><Literal>-mv8</Literal>:</Term>
-<ListItem>
-<Para>
-(SPARC machines)<IndexTerm><Primary>-mv8 option (SPARC only)</Primary></IndexTerm>
-Means to pass the like-named option to GCC; it says to use the
-Version 8 SPARC instructions, notably integer multiply and divide.
-The similiar <Literal>-m*</Literal> GCC options for SPARC also work, actually.
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Literal>-mlong-calls</Literal>:</Term>
-<ListItem>
-<Para>
-(HPPA machines)<IndexTerm><Primary>-mlong-calls option (HPPA only)</Primary></IndexTerm>
-Means to pass the like-named option to GCC. Required for Very Big
-modules, maybe. (Probably means you're in trouble…)
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Literal>-monly-[32]-regs</Literal>:</Term>
-<ListItem>
-<Para>
-(iX86 machines)<IndexTerm><Primary>-monly-N-regs option (iX86 only)</Primary></IndexTerm>
-GHC tries to ``steal'' four registers from GCC, for performance
-reasons; it almost always works. However, when GCC is compiling some
-modules with four stolen registers, it will crash, probably saying:
-
-<Screen>
-Foo.hc:533: fixed or forbidden register was spilled.
-This may be due to a compiler bug or to impossible asm
-statements or clauses.
-</Screen>
-
-Just give some registers back with <Literal>-monly-N-regs</Literal>. Try `3' first,
-then `2'. If `2' doesn't work, please report the bug to us.
-</Para>
-</ListItem>
-</VarListEntry>
-</VariableList>
-</Para>
-
-</Sect2>
-
-<Sect2 id="optimise-C-compiler">
-<Title>Code improvement by the C compiler.
-</Title>
-
-<Para>
-<IndexTerm><Primary>optimisation by GCC</Primary></IndexTerm>
-<IndexTerm><Primary>GCC optimisation</Primary></IndexTerm>
-</Para>
-
-<Para>
-The C compiler (GCC) is run with <Literal>-O</Literal> turned on. (It has
-to be, actually).
-</Para>
-
-<Para>
-If you want to run GCC with <Literal>-O2</Literal>—which may be worth a few
-percent in execution speed—you can give a
-<Literal>-O2-for-C</Literal><IndexTerm><Primary>-O2-for-C option</Primary></IndexTerm> option.
-</Para>
-
-</Sect2>
-
-</Sect1>
-
-<Sect1 id="options-phases">
-<Title>Options related to a particular phase
-</Title>
-
-<Sect2 id="c-pre-processor">
-<Title>The C pre-processor
-</Title>
-
-<Para>
-<IndexTerm><Primary>pre-processing: cpp</Primary></IndexTerm>
-<IndexTerm><Primary>C pre-processor options</Primary></IndexTerm>
-<IndexTerm><Primary>cpp, pre-processing with</Primary></IndexTerm>
-</Para>
-
-<Para>
-The C pre-processor <Literal>cpp</Literal> is run over your Haskell code only if the
-<Literal>-cpp</Literal> option <IndexTerm><Primary>-cpp option</Primary></IndexTerm> is given. Unless you are
-building a large system with significant doses of conditional
-compilation, you really shouldn't need it.
-<VariableList>
-
-<VarListEntry>
-<Term><Literal>-D<foo></Literal>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-D<name> option</Primary></IndexTerm>
-Define macro <Literal><foo></Literal> in the usual way. NB: does <Emphasis>not</Emphasis> affect
-<Literal>-D</Literal> macros passed to the C compiler when compiling via C! For those,
-use the <Literal>-optc-Dfoo</Literal> hack… (see <XRef LinkEnd="forcing-options-through">).
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Literal>-U<foo></Literal>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-U<name> option</Primary></IndexTerm>
-Undefine macro <Literal><foo></Literal> in the usual way.
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Literal>-I<dir></Literal>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-I<dir> option</Primary></IndexTerm>
-Specify a directory in which to look for <Literal>#include</Literal> files, in
-the usual C way.
-</Para>
-</ListItem>
-</VarListEntry>
-</VariableList>
-</Para>
-
-<Para>
-The <Literal>ghc</Literal> driver pre-defines several macros when processing Haskell
-source code (<Literal>.hs</Literal> or <Literal>.lhs</Literal> files):
-</Para>
-
-<Para>
-<VariableList>
-
-<VarListEntry>
-<Term><Literal>__HASKELL98__</Literal>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>__HASKELL98__</Primary></IndexTerm>
-If defined, this means that GHC supports the language defined by the
-Haskell 98 report.
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Literal>__HASKELL__=98</Literal>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>__HASKELL__</Primary></IndexTerm>
-In GHC 4.04 and later, the <Literal>__HASKELL__</Literal> macro is defined as having
-the value <Literal>98</Literal>.
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Literal>__HASKELL1__</Literal>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>__HASKELL1__ macro</Primary></IndexTerm>
-If defined to <Emphasis>n</Emphasis>, that means GHC supports the Haskell language
-defined in the Haskell report version <Emphasis>1.n</Emphasis>. Currently 5. This
-macro is deprecated, and will probably disappear in future versions.
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Literal>__GLASGOW_HASKELL__</Literal>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>__GLASGOW_HASKELL__ macro</Primary></IndexTerm>
-For version <Emphasis>n</Emphasis> of the GHC system, this will be <Literal>#define</Literal>d to
-<Emphasis>100n</Emphasis>. So, for version 4.00, it is 400.
-</Para>
-
-<Para>
-With any luck, <Literal>__GLASGOW_HASKELL__</Literal> will be undefined in all other
-implementations that support C-style pre-processing.
-</Para>
-
-<Para>
-(For reference: the comparable symbols for other systems are:
-<Literal>__HUGS__</Literal> for Hugs and <Literal>__HBC__</Literal> for Chalmers.)
-</Para>
-
-<Para>
-NB. This macro is set when pre-processing both Haskell source and C
-source, including the C source generated from a Haskell module
-(ie. <Literal>.hs</Literal>, <Literal>.lhs</Literal>, <Literal>.c</Literal> and <Literal>.hc</Literal> files).
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Literal>__CONCURRENT_HASKELL__</Literal>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>__CONCURRENT_HASKELL__ macro</Primary></IndexTerm>
-This symbol is defined when pre-processing Haskell (input) and
-pre-processing C (GHC output). Since GHC from verion 4.00 now
-supports concurrent haskell by default, this symbol is always defined.
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Literal>__PARALLEL_HASKELL__</Literal>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>__PARALLEL_HASKELL__ macro</Primary></IndexTerm>
-Only defined when <Literal>-parallel</Literal> is in use! This symbol is defined when
-pre-processing Haskell (input) and pre-processing C (GHC output).
-</Para>
-</ListItem>
-</VarListEntry>
-</VariableList>
-</Para>
-
-<Para>
-Options other than the above can be forced through to the C
-pre-processor with the <Literal>-opt</Literal> flags (see
-<XRef LinkEnd="forcing-options-through">).
-</Para>
-
-<Para>
-A small word of warning: <Literal>-cpp</Literal> is not friendly to ``string
-gaps''.<IndexTerm><Primary>-cpp vs string gaps</Primary></IndexTerm><IndexTerm><Primary>string gaps vs
--cpp</Primary></IndexTerm>. In other words, strings such as the following:
-</Para>
-
-<Para>
-
-<ProgramListing>
-strmod = "\
-\ p \
-\ "
-</ProgramListing>
-
-</Para>
-
-<Para>
-don't work with <Literal>-cpp</Literal>; <Literal>/usr/bin/cpp</Literal> elides the
-backslash-newline pairs.
-</Para>
-
-<Para>
-However, it appears that if you add a space at the end of the line,
-then <Literal>cpp</Literal> (at least GNU <Literal>cpp</Literal> and possibly other <Literal>cpp</Literal>s)
-leaves the backslash-space pairs alone and the string gap works as
-expected.
-</Para>
-
-</Sect2>
-
-<Sect2 id="options-C-compiler">
-<Title>Options affecting the C compiler (if applicable)
-</Title>
-
-<Para>
-<IndexTerm><Primary>include-file options</Primary></IndexTerm>
-<IndexTerm><Primary>C compiler options</Primary></IndexTerm>
-<IndexTerm><Primary>GCC options</Primary></IndexTerm>
-</Para>
-
-<Para>
-At the moment, quite a few common C-compiler options are passed on
-quietly to the C compilation of Haskell-compiler-generated C files.
-THIS MAY CHANGE. Meanwhile, options so sent are:
-</Para>
-
-<Para>
-
-<InformalTable>
-<TGroup Cols="2">
-<ColSpec Align="Left" Colsep="0">
-<ColSpec Align="Left" Colsep="0">
-<TBody>
-<Row>
-<Entry><Literal>-ansi</Literal> </Entry>
-<Entry> do ANSI C (not K&R) </Entry>
-</Row>
-<Row>
-<Entry>
-<Literal>-pedantic</Literal> </Entry>
-<Entry> be so</Entry>
-</Row>
-<Row>
-<Entry>
-<Literal>-dgcc-lint</Literal> </Entry>
-<Entry> (hack) short for ``make GCC very paranoid''</Entry>
-</Row>
-
-</TBody>
-
-</TGroup>
-</InformalTable>
-
-<IndexTerm><Primary>-ansi option (for GCC)</Primary></IndexTerm>
-<IndexTerm><Primary>-pedantic option (for GCC)</Primary></IndexTerm>
-<IndexTerm><Primary>-dgcc-lint option (GCC paranoia)</Primary></IndexTerm>
-</Para>
-
-<Para>
-If you are compiling with lots of <Literal>ccalls</Literal>, etc., you may need to
-tell the C compiler about some <Literal>#include</Literal> files. There is no real
-pretty way to do this, but you can use this hack from the
-command-line:
-</Para>
-
-<Para>
-
-<Screen>
-% ghc -c '-#include <X/Xlib.h>' Xstuff.lhs
-</Screen>
-
-</Para>
-
-</Sect2>
-
-<Sect2 id="options-linker">
-<Title>Linking and consistency-checking
-</Title>
-
-<Para>
-<IndexTerm><Primary>linker options</Primary></IndexTerm>
-<IndexTerm><Primary>ld options</Primary></IndexTerm>
-</Para>
-
-<Para>
-GHC has to link your code with various libraries, possibly including:
-user-supplied, GHC-supplied, and system-supplied (<Literal>-lm</Literal> math
-library, for example).
-</Para>
-
-<Para>
-<VariableList>
-
-<VarListEntry>
-<Term><Literal>-l<FOO></Literal>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-l<lib> option</Primary></IndexTerm>
-Link in a library named <Literal>lib<FOO>.a</Literal> which resides somewhere on the
-library directories path.
-</Para>
-
-<Para>
-Because of the sad state of most UNIX linkers, the order of such
-options does matter. Thus: <Literal>ghc -lbar *.o</Literal> is almost certainly
-wrong, because it will search <Literal>libbar.a</Literal> <Emphasis>before</Emphasis> it has
-collected unresolved symbols from the <Literal>*.o</Literal> files.
-<Literal>ghc *.o -lbar</Literal> is probably better.
-</Para>
-
-<Para>
-The linker will of course be informed about some GHC-supplied
-libraries automatically; these are:
-</Para>
-
-<Para>
-
-<InformalTable>
-<TGroup Cols="2">
-<ColSpec Align="Left" Colsep="0">
-<ColSpec Align="Left" Colsep="0">
-<TBody>
-<Row>
-<Entry><Emphasis>-l equivalent</Emphasis> </Entry>
-<Entry> <Emphasis>description</Emphasis> </Entry>
-</Row>
-
-<Row>
-<Entry>
-<Literal>-lHSrts,-lHSclib</Literal> </Entry>
-<Entry> basic runtime libraries </Entry>
-</Row>
-<Row>
-<Entry>
-<Literal>-lHS</Literal> </Entry>
-<Entry> standard Prelude library </Entry>
-</Row>
-<Row>
-<Entry>
-<Literal>-lHS_cbits</Literal> </Entry>
-<Entry> C support code for standard Prelude library </Entry>
-</Row>
-<Row>
-<Entry>
-<Literal>-lgmp</Literal> </Entry>
-<Entry> GNU multi-precision library (for Integers)</Entry>
-</Row>
-
-</TBody>
-
-</TGroup>
-</InformalTable>
-
-</Para>
-
-<Para>
-<IndexTerm><Primary>-lHS library</Primary></IndexTerm>
-<IndexTerm><Primary>-lHS_cbits library</Primary></IndexTerm>
-<IndexTerm><Primary>-lHSrts library</Primary></IndexTerm>
-<IndexTerm><Primary>-lgmp library</Primary></IndexTerm>
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Literal>-syslib <name></Literal>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-syslib <name> option</Primary></IndexTerm>
-</Para>
-
-<Para>
-If you are using a Haskell ``system library'' (e.g., the POSIX
-library), just use the <Literal>-syslib posix</Literal> option, and the correct code
-should be linked in.
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Literal>-L<dir></Literal>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-L<dir> option</Primary></IndexTerm>
-Where to find user-supplied libraries… Prepend the directory
-<Literal><dir></Literal> to the library directories path.
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Literal>-static</Literal>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-static option</Primary></IndexTerm>
-Tell the linker to avoid shared libraries.
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Literal>-no-link-chk</Literal> and <Literal>-link-chk</Literal>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-no-link-chk option</Primary></IndexTerm>
-<IndexTerm><Primary>-link-chk option</Primary></IndexTerm>
-<IndexTerm><Primary>consistency checking of executables</Primary></IndexTerm>
-By default, immediately after linking an executable, GHC verifies that
-the pieces that went into it were compiled with compatible flags; a
-``consistency check''.
-(This is to avoid mysterious failures caused by non-meshing of
-incompatibly-compiled programs; e.g., if one <Literal>.o</Literal> file was compiled
-for a parallel machine and the others weren't.) You may turn off this
-check with <Literal>-no-link-chk</Literal>. You can turn it (back) on with
-<Literal>-link-chk</Literal> (the default).
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Literal>-no-hs-main</Literal>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-no-hs-main option</Primary></IndexTerm>
-<IndexTerm><Primary>linking Haskell libraries with foreign code</Primary></IndexTerm>
-</Para>
-
-<Para>
-In the event you want to include ghc-compiled code as part of another
-(non-Haskell) program, the RTS will not be supplying its definition of
-<Literal>main()</Literal> at link-time, you will have to. To signal that to the
-driver script when linking, use <Literal>-no-hs-main</Literal>.
-</Para>
-
-<Para>
-Notice that since the command-line passed to the linker is rather
-involved, you probably want to use the ghc driver script to do the
-final link of your `mixed-language' application. This is not a
-requirement though, just try linking once with <Literal>-v</Literal> on to see what
-options the driver passes through to the linker.
-</Para>
-</ListItem>
-</VarListEntry>
-</VariableList>
-</Para>
-
-</Sect2>
-
-</Sect1>
-
-<Sect1>
-<Title>Using Concurrent Haskell</Title>
-
-<Para>
-<IndexTerm><Primary>Concurrent Haskell—use</Primary></IndexTerm>
-</Para>
-
-<Para>
-GHC (as of version 4.00) supports Concurrent Haskell by default,
-without requiring a special option or libraries compiled in a certain
-way. To get access to the support libraries for Concurrent Haskell
-(ie. <Literal>Concurrent</Literal> and friends), use the <Literal>-syslib concurrent</Literal> option.
-</Para>
-
-<Para>
-Three RTS options are provided for modifying the behaviour of the
-threaded runtime system. See the descriptions of <Literal>-C[<us>]</Literal>, <Literal>-q</Literal>,
-and <Literal>-t<num></Literal> in <XRef LinkEnd="parallel-rts-opts">.
-</Para>
-
-<Para>
-Concurrent Haskell is described in more detail in <XRef LinkEnd="concurrent-and-parallel">.
-</Para>
-
-</Sect1>
-
-<Sect1>
-<Title>Using Parallel Haskell</Title>
-
-<Para>
-<IndexTerm><Primary>Parallel Haskell—use</Primary></IndexTerm>
-</Para>
-
-<Para>
-[You won't be able to execute parallel Haskell programs unless PVM3
-(Parallel Virtual Machine, version 3) is installed at your site.]
-</Para>
-
-<Para>
-To compile a Haskell program for parallel execution under PVM, use the
-<Literal>-parallel</Literal> option,<IndexTerm><Primary>-parallel option</Primary></IndexTerm> both when compiling
-<Emphasis>and linking</Emphasis>. You will probably want to <Literal>import Parallel</Literal>
-into your Haskell modules.
-</Para>
-
-<Para>
-To run your parallel program, once PVM is going, just invoke it ``as
-normal''. The main extra RTS option is <Literal>-N<n></Literal>, to say how many
-PVM ``processors'' your program to run on. (For more details of
-all relevant RTS options, please see <XRef LinkEnd="parallel-rts-opts">.)
-</Para>
-
-<Para>
-In truth, running Parallel Haskell programs and getting information
-out of them (e.g., parallelism profiles) is a battle with the vagaries of
-PVM, detailed in the following sections.
-</Para>
-
-<Sect2>
-<Title>Dummy's guide to using PVM</Title>
-
-<Para>
-<IndexTerm><Primary>PVM, how to use</Primary></IndexTerm>
-<IndexTerm><Primary>Parallel Haskell—PVM use</Primary></IndexTerm>
-Before you can run a parallel program under PVM, you must set the
-required environment variables (PVM's idea, not ours); something like,
-probably in your <Literal>.cshrc</Literal> or equivalent:
-
-<ProgramListing>
-setenv PVM_ROOT /wherever/you/put/it
-setenv PVM_ARCH `$PVM_ROOT/lib/pvmgetarch`
-setenv PVM_DPATH $PVM_ROOT/lib/pvmd
-</ProgramListing>
-
-</Para>
-
-<Para>
-Creating and/or controlling your ``parallel machine'' is a purely-PVM
-business; nothing specific to Parallel Haskell.
-</Para>
-
-<Para>
-You use the <Literal>pvm</Literal><IndexTerm><Primary>pvm command</Primary></IndexTerm> command to start PVM on your
-machine. You can then do various things to control/monitor your
-``parallel machine;'' the most useful being:
-</Para>
-
-<Para>
-<InformalTable>
-<TGroup Cols=2>
-<ColSpec Align="Left">
-<TBody>
-
-<Row>
-<Entry><Literal>Control-D</Literal></Entry>
-<Entry>exit <Literal>pvm</Literal>, leaving it running</Entry>
-</Row>
-
-<Row>
-<Entry><Literal>halt</Literal></Entry>
-<Entry>kill off this ``parallel machine'' & exit</Entry>
-</Row>
-
-<Row>
-<Entry><Literal>add <host></Literal></Entry>
-<Entry>add <Literal><host></Literal> as a processor</Entry>
-</Row>
-
-<Row>
-<Entry><Literal>delete <host></Literal></Entry>
-<Entry>delete <Literal><host></Literal></Entry>
-</Row>
-
-<Row>
-<Entry><Literal>reset</Literal></Entry>
-<Entry>kill what's going, but leave PVM up</Entry>
-</Row>
-
-<Row>
-<Entry><Literal>conf</Literal></Entry>
-<Entry>list the current configuration</Entry>
-</Row>
-
-<Row>
-<Entry><Literal>ps</Literal></Entry>
-<Entry>report processes' status</Entry>
-</Row>
-
-<Row>
-<Entry><Literal>pstat <pid></Literal></Entry>
-<Entry>status of a particular process</Entry>
-</Row>
-
-</TBody>
-</TGroup>
-</InformalTable>
-</Para>
-
-<Para>
-The PVM documentation can tell you much, much more about <Literal>pvm</Literal>!
-</Para>
-
-</Sect2>
-
-<Sect2>
-<Title>Parallelism profiles</Title>
-
-<Para>
-<IndexTerm><Primary>parallelism profiles</Primary></IndexTerm>
-<IndexTerm><Primary>profiles, parallelism</Primary></IndexTerm>
-<IndexTerm><Primary>visualisation tools</Primary></IndexTerm>
-</Para>
-
-<Para>
-With Parallel Haskell programs, we usually don't care about the
-results—only with ``how parallel'' it was! We want pretty pictures.
-</Para>
-
-<Para>
-Parallelism profiles (à la <Literal>hbcpp</Literal>) can be generated with the
-<Literal>-q</Literal><IndexTerm><Primary>-q RTS option (concurrent, parallel)</Primary></IndexTerm> RTS option. The
-per-processor profiling info is dumped into files named
-<Literal><full-path><program>.gr</Literal>. These are then munged into a PostScript picture,
-which you can then display. For example, to run your program
-<Literal>a.out</Literal> on 8 processors, then view the parallelism profile, do:
-</Para>
-
-<Para>
-
-<Screen>
-% ./a.out +RTS -N8 -q
-% grs2gr *.???.gr > temp.gr # combine the 8 .gr files into one
-% gr2ps -O temp.gr # cvt to .ps; output in temp.ps
-% ghostview -seascape temp.ps # look at it!
-</Screen>
-
-</Para>
-
-<Para>
-The scripts for processing the parallelism profiles are distributed
-in <Literal>ghc/utils/parallel/</Literal>.
-</Para>
-
-</Sect2>
-
-<Sect2>
-<Title>Other useful info about running parallel programs</Title>
-
-<Para>
-The ``garbage-collection statistics'' RTS options can be useful for
-seeing what parallel programs are doing. If you do either
-<Literal>+RTS -Sstderr</Literal><IndexTerm><Primary>-Sstderr RTS option</Primary></IndexTerm> or <Literal>+RTS -sstderr</Literal>, then
-you'll get mutator, garbage-collection, etc., times on standard
-error. The standard error of all PE's other than the `main thread'
-appears in <Literal>/tmp/pvml.nnn</Literal>, courtesy of PVM.
-</Para>
-
-<Para>
-Whether doing <Literal>+RTS -Sstderr</Literal> or not, a handy way to watch
-what's happening overall is: <Literal>tail -f /tmp/pvml.nnn</Literal>.
-</Para>
-
-</Sect2>
-
-<Sect2 id="parallel-rts-opts">
-<Title>RTS options for Concurrent/Parallel Haskell
-</Title>
-
-<Para>
-<IndexTerm><Primary>RTS options, concurrent</Primary></IndexTerm>
-<IndexTerm><Primary>RTS options, parallel</Primary></IndexTerm>
-<IndexTerm><Primary>Concurrent Haskell—RTS options</Primary></IndexTerm>
-<IndexTerm><Primary>Parallel Haskell—RTS options</Primary></IndexTerm>
-</Para>
-
-<Para>
-Besides the usual runtime system (RTS) options
-(<XRef LinkEnd="runtime-control">), there are a few options particularly
-for concurrent/parallel execution.
-</Para>
-
-<Para>
-<VariableList>
-
-<VarListEntry>
-<Term><Literal>-N<N></Literal>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-N<N> RTS option (parallel)</Primary></IndexTerm>
-(PARALLEL ONLY) Use <Literal><N></Literal> PVM processors to run this program;
-the default is 2.
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Literal>-C[<us>]</Literal>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-C<us> RTS option</Primary></IndexTerm>
-Sets the context switch interval to <Literal><us></Literal> microseconds. A context
-switch will occur at the next heap allocation after the timer expires.
-With <Literal>-C0</Literal> or <Literal>-C</Literal>, context switches will occur as often as
-possible (at every heap allocation). By default, context switches
-occur every 10 milliseconds. Note that many interval timers are only
-capable of 10 millisecond granularity, so the default setting may be
-the finest granularity possible, short of a context switch at every
-heap allocation.
-</Para>
-
-<Para>
-[NOTE: this option currently has no effect (version 4.00). Context
-switches happen when the current heap block is full, i.e. every 4k of
-allocation].
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Literal>-q[v]</Literal>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-q RTS option</Primary></IndexTerm>
-(PARALLEL ONLY) Produce a quasi-parallel profile of thread activity,
-in the file <Literal><program>.qp</Literal>. In the style of <Literal>hbcpp</Literal>, this profile
-records the movement of threads between the green (runnable) and red
-(blocked) queues. If you specify the verbose suboption (<Literal>-qv</Literal>), the
-green queue is split into green (for the currently running thread
-only) and amber (for other runnable threads). We do not recommend
-that you use the verbose suboption if you are planning to use the
-<Literal>hbcpp</Literal> profiling tools or if you are context switching at every heap
-check (with <Literal>-C</Literal>).
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Literal>-t<num></Literal>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-t<num> RTS option</Primary></IndexTerm>
-(PARALLEL ONLY) Limit the number of concurrent threads per processor
-to <Literal><num></Literal>. The default is 32. Each thread requires slightly over 1K
-<Emphasis>words</Emphasis> in the heap for thread state and stack objects. (For
-32-bit machines, this translates to 4K bytes, and for 64-bit machines,
-8K bytes.)
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Literal>-d</Literal>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-d RTS option (parallel)</Primary></IndexTerm>
-(PARALLEL ONLY) Turn on debugging. It pops up one xterm (or GDB, or
-something…) per PVM processor. We use the standard <Literal>debugger</Literal>
-script that comes with PVM3, but we sometimes meddle with the
-<Literal>debugger2</Literal> script. We include ours in the GHC distribution,
-in <Literal>ghc/utils/pvm/</Literal>.
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Literal>-e<num></Literal>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-e<num> RTS option (parallel)</Primary></IndexTerm>
-(PARALLEL ONLY) Limit the number of pending sparks per processor to
-<Literal><num></Literal>. The default is 100. A larger number may be appropriate if
-your program generates large amounts of parallelism initially.
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Literal>-Q<num></Literal>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-Q<num> RTS option (parallel)</Primary></IndexTerm>
-(PARALLEL ONLY) Set the size of packets transmitted between processors
-to <Literal><num></Literal>. The default is 1024 words. A larger number may be
-appropriate if your machine has a high communication cost relative to
-computation speed.
-</Para>
-</ListItem>
-</VarListEntry>
-</VariableList>
-</Para>
-
-</Sect2>
-
-</Sect1>
-
-&runtime
-&debug
-
-</Chapter>
+<!-- Emacs stuff:
+ ;;; Local Variables: ***
+ ;;; mode: sgml ***
+ ;;; sgml-parent-document: ("users_guide.sgml" "book" "chapter") ***
+ ;;; End: ***
+ -->
projects / ghc-hetmet.git / blobdiff