-<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>