-<Para>
-<IndexTerm><Primary>GHC, using</Primary></IndexTerm>
-<IndexTerm><Primary>using GHC</Primary></IndexTerm>
-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 <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>
-
-<Sect1 id="command-line-structure">
-<Title>Overall command-line structure
-</Title>
-
-<Para>
-<IndexTerm><Primary>structure, command-line</Primary></IndexTerm>
-<IndexTerm><Primary>command-line structure</Primary></IndexTerm>
-</Para>
-
-<Para>
-An invocation of GHC takes the following form:
-</Para>
-
-<Para>
-
-<Screen>
-ghc [argument...]
-</Screen>
-
-</Para>
-
-<Para>
-Command-line arguments are either options or file names.
-</Para>
-
-<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
-<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>
-
-</Sect1>
-
-<Sect1 id="file-suffixes">
-<Title>Meaningful file suffixes
-</Title>
-
-<Para>
-<IndexTerm><Primary>suffixes, file</Primary></IndexTerm>
-<IndexTerm><Primary>file suffixes for GHC</Primary></IndexTerm>
-</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>
-<VariableList>
-
-<VarListEntry>
-<Term><Filename>.lhs</Filename>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>lhs suffix</Primary></IndexTerm>
-A “literate Haskell” module.
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Filename>.hs</Filename>:</Term>
-<ListItem>
-<Para>
-A not-so-literate Haskell module.
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Filename>.hi</Filename>:</Term>
-<ListItem>
-<Para>
-A Haskell interface file, probably compiler-generated.
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Filename>.hc</Filename>:</Term>
-<ListItem>
-<Para>
-Intermediate C file produced by the Haskell compiler.
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Filename>.c</Filename>:</Term>
-<ListItem>
-<Para>
-A C file not produced by the Haskell compiler.
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Filename>.s</Filename>:</Term>
-<ListItem>
-<Para>
-An assembly-language source file, usually
-produced by the compiler.
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Filename>.o</Filename>:</Term>
-<ListItem>
-<Para>
-An object file, produced by an assembler.
-</Para>
-</ListItem>
-</VarListEntry>
-</VariableList>
-</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 <Option>-help</Option> (or <Option>-?</Option>) 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 <Option>-v</Option><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 <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>
-
-<Para>
-If you're just interested in the compiler version number, the
-<Option>--version</Option><IndexTerm><Primary>--version option</Primary></IndexTerm> option prints out a
-one-line string containing the requested info.
-</Para>
-
-</Sect1>
-
-<Sect1 id="options-order">
-<Title>Running the right phases in the right order
-</Title>
-
-<Para>
-<IndexTerm><Primary>order of passes in GHC</Primary></IndexTerm>
-<IndexTerm><Primary>pass ordering in GHC</Primary></IndexTerm>
-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>
-<InformalTable>
-<TGroup Cols="4">
-<ColSpec Align="Left">
-<ColSpec Align="Left">
-<ColSpec Align="Left">
-<ColSpec Align="Left">
-<TBody>
-
-<Row>
-<Entry>Phase of the compilation system</Entry>
-<Entry>Suffix saying “start here”</Entry>
-<Entry>Flag saying “stop after”</Entry>
-<Entry>(suffix of) output file</Entry>
-</Row>
-
-<Row>
-<Entry>
-literate pre-processor </Entry>
-<Entry> .lhs </Entry>
-<Entry> - </Entry>
-<Entry> - </Entry>
-</Row>
-<Row>
-<Entry>
-C pre-processor (opt.) </Entry>
-<Entry> - </Entry>
-<Entry> - </Entry>
-<Entry> - </Entry>
-</Row>
-<Row>
-<Entry>
-Haskell compiler </Entry>
-<Entry> .hs </Entry>
-<Entry> -C, -S </Entry>
-<Entry> .hc, .s </Entry>
-</Row>
-<Row>
-<Entry>
-C compiler (opt.) </Entry>
-<Entry> .hc or .c </Entry>
-<Entry> -S </Entry>
-<Entry> .s </Entry>
-</Row>
-<Row>
-<Entry>
-assembler </Entry>
-<Entry> .s </Entry>
-<Entry> -c </Entry>
-<Entry> .o </Entry>
-</Row>
-<Row>
-<Entry>
-linker </Entry>
-<Entry> other </Entry>
-<Entry> - </Entry>
-<Entry> a.out </Entry>
-</Row>
-</TBody>
-</TGroup>
-</InformalTable>
-
-<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: <Command>ghc -c Foo.hs</Command>
-</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 <Option>-cpp</Option><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 <Option>-E</Option><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 <Option>-cpp</Option>, the
-output is the de-litted version of the original source.
-</Para>
-
-<Para>
-The option <Option>-optcpp-E</Option><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 <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>
-
-<Para>
-EXOTICA: But 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>
-
-<Para>
-
-<Screen>
-% ghc -c parse/Foo.hs parse/Bar.hs gurgle/Bumble.hs -odir `arch`
-</Screen>
-
-</Para>
-
-<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>
-
-<Para>
-MORE 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.).
-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>
-
-<Para>
-FURTHER EXOTICA: If you are doing a normal <Filename>.hs</Filename>-to-<Filename>.o</Filename> compilation
-but would like to hang onto the intermediate <Filename>.hc</Filename> C file, just
-throw in a <Option>-keep-hc-file-too</Option> option<IndexTerm><Primary>-keep-hc-file-too option</Primary></IndexTerm>.
-If you would like to look at the assembler output, toss in a
-<Option>-keep-s-file-too</Option>,<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 <Option>-v</Option>, for example. You can instruct GHC to <Emphasis>append</Emphasis> this
-output to a particular log file with a <Option>-odump <blah></Option><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 <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>TMPDIR</Constant> variable when building GHC, and
-never worry about <Constant>TMPDIR</Constant> 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:
-<Option>-fwarn-overlpapping-patterns</Option>, <Option>-fwarn-duplicate-exports</Option>, and
-<Option>-fwarn-missing-methods</Option>. The following flags are simple ways to
-select standard “packages” of warnings:
-</Para>
-
-<Para>
-<VariableList>
-
-<VarListEntry>
-<Term><Option>-Wnot</Option>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-Wnot option</Primary></IndexTerm>
-Turns off all warnings, including the standard ones.
-</Para>
-</ListItem>
-</VarListEntry>
-
-<VarListEntry>
-<Term><Option>-w</Option>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-w option</Primary></IndexTerm>
-Synonym for <Option>-Wnot</Option>.
-</Para>
-</ListItem>
-</VarListEntry>
-
-<VarListEntry>
-<Term><Option>-W</Option>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-W option</Primary></IndexTerm>
-Provides the standard warnings plus <Option>-fwarn-incomplete-patterns</Option>,
-<Option>-fwarn-unused-imports</Option> and <Option>-fwarn-unused-binds</Option>.
-</Para>
-</ListItem>
-</VarListEntry>
-
-<VarListEntry>
-<Term><Option>-Wall</Option>:</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 <Option>-fno-warn-...</Option> option on
-the command line.
-</Para>
-
-<Para>
-<VariableList>
-
-<VarListEntry>
-<Term><Option>-fwarn-name-shadowing</Option>:</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><Option>-fwarn-overlapping-patterns</Option>:</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>
-f :: String -> Int
-f [] = 0
-f (_:xs) = 1
-f "2" = 2
-</ProgramListing>
-</Para>
-
-<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-incomplete-patterns</Option>:</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 <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>
-
-<Para>
-<ProgramListing>
-g [] = 2
-</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><Option>-fwarn-missing-methods</Option>:</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><Option>-fwarn-missing-fields</Option>:</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><Option>-fwarn-unused-imports</Option>:</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><Option>-fwarn-unused-binds</Option>:</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><Option>-fwarn-unused-matches</Option>:</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 <VarName>x</VarName> and <VarName>y</VarName> as unused. To eliminate the warning,
-all unused variables can be replaced with wildcards.
-</Para>
-</ListItem>
-</VarListEntry>
-
-<VarListEntry>
-<Term><Option>-fwarn-duplicate-exports</Option>:</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><Option>-fwarn-type-defaults</Option>:</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 <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-missing-signatures</Option>:</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 <Option>-fwarn-missing-signatures</Option> option. This
-option is off by default.
-</Para>
-</ListItem>
-</VarListEntry>
-</VariableList>
-</Para>
-
-<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>
-
-<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 <Filename>F</Filename> which contains a module <Literal>A</Literal>, say,
-it generates an object <Filename>F.o</Filename>, <Emphasis>and</Emphasis> a companion <Emphasis>interface
-file</Emphasis> <Filename>A.hi</Filename>. 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 <Command>make</Command>
-become harder. <Command>make</Command> 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 <Filename>A.hi</Filename> 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 <Command>A.hi</Command> 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, <Filename>A.hi</Filename> will contain the
-full data type definition. For small function definitions, <Filename>A.hi</Filename>
-will contain the complete definition of the function. For bigger
-functions, <Filename>A.hi</Filename> will contain strictness information about the
-function. And so on. GHC puts much more information into <Filename>.hi</Filename> files
-when optimisation is turned on with the <Option>-O</Option> flag. Without <Option>-O</Option> it
-puts in just the minimum; with <Option>-O</Option> it lobs in a whole pile of stuff.
-<IndexTerm><Primary>optimsation, effect on .hi files</Primary></IndexTerm>
-</Para>
-
-<Para>
-<Filename>A.hi</Filename> should really be thought of as a compiler-readable version of
-<Filename>A.o</Filename>. If you use a <Filename>.hi</Filename> file that wasn't generated by the same
-compilation run that generates the <Filename>.o</Filename> 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, <Filename>Foo.hi</Filename>.
-It has a builtin list of directories (notably including <Filename>.</Filename>) where
-it looks.
-</Para>
-
-<Para>
-<VariableList>
-
-<VarListEntry>
-<Term><Option>-i<dirs></Option></Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-i<dirs> option</Primary></IndexTerm>This flag
-prepends a colon-separated list of <Filename>dirs</Filename> to the “import
-directories” list.
-See also <XRef LinkEnd="recomp"> for the significance of using
-relative and absolute pathnames in the <Option>-i</Option> list.
-</Para>
-</ListItem>
-</VarListEntry>
-
-<VarListEntry>
-<Term><Option>-i</Option></Term>
-<ListItem>
-<Para>
-resets the “import directories” list back to nothing.
-</Para>
-</ListItem>
-</VarListEntry>
-
-<VarListEntry>
-<Term><Option>-fno-implicit-prelude</Option></Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-fno-implicit-prelude option</Primary></IndexTerm>
-GHC normally imports <Filename>Prelude.hi</Filename> files for you. If you'd rather it
-didn't, then give it a <Option>-fno-implicit-prelude</Option> option. You are
-unlikely to get very far without a Prelude, but, hey, it's a free
-country.
-</Para>
-</ListItem>
-</VarListEntry>
-
-<VarListEntry>
-<Term><Option>-syslib <lib></Option></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 <Option>-syslib posix</Option> option (for
-example). The right interface files should then be available. The
-accompanying HsLibs document lists the libraries available by this
-mechanism.
-</Para>
-</ListItem>
-</VarListEntry>
-
-<VarListEntry>
-<Term><Option>-I<dir></Option></Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-I<dir> option</Primary></IndexTerm>
-Once a Haskell module has been compiled to C (<Filename>.hc</Filename> file), you may
-wish to specify where GHC tells the C compiler to look for <Filename>.h</Filename> files.
-(Or, if you are using the <Option>-cpp</Option> option<IndexTerm><Primary>-cpp option</Primary></IndexTerm>, where
-it tells the C pre-processor to look…) For this purpose, use a <Option>-I</Option>
-option in the usual C-ish way.
-</Para>
-</ListItem>
-</VarListEntry>
-
-</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
-<Filename>bar2/Wurble.iface</Filename> with the option <Option>-ohi bar2/Wurble.iface</Option><IndexTerm><Primary>-ohi
-<file> option</Primary></IndexTerm> (not recommended).
-</Para>
-
-<Para>
-To avoid generating an interface file at all, use a <Option>-nohi</Option>
-option.<IndexTerm><Primary>-nohi option</Primary></IndexTerm>
-</Para>
-
-<Para>
-The compiler does not overwrite an existing <Filename>.hi</Filename> interface file if
-the new one is byte-for-byte the same as the old one; this is friendly
-to <Command>make</Command>. When an interface does change, it is often enlightening to
-be informed. The <Option>-hi-diffs</Option><IndexTerm><Primary>-hi-diffs option</Primary></IndexTerm> option will
-make GHC run <Command>diff</Command> on the old and new <Filename>.hi</Filename> files. You can also
-record the difference in the interface file itself, the
-<Option>-keep-hi-diffs</Option><IndexTerm><Primary>-keep-hi-diffs</Primary></IndexTerm> option takes care of that.
-</Para>
-
-<Para>
-The <Filename>.hi</Filename> 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
-<Option>-hi-diffs-with-usages</Option><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
-<Option>-fignore-interface-pragmas</Option><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 <Option>-fno-prune-tydecls</Option> and <Option>-fno-prune-instdecls</Option>.
-<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>
-
-<IndexTerm><Primary>recompilation checker</Primary></IndexTerm>
-
-<Para>
-<variablelist>
-<VarListEntry>
-<Term><Option>-recomp</Option></Term>
-<IndexTerm><Primary><option>-recomp</option> option</Primary></IndexTerm>
-<ListItem>
-<Para>
-(On by default) Turn on recompilation checking. This will stop
-compilation early, leaving an existing <filename>.o</filename> file in
-place, if it can be determined that the module does not need to be
-recompiled.
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Option>-no-recomp</Option></Term>
-<IndexTerm><Primary><option>-recomp</option> option</Primary></IndexTerm>
-<ListItem>
-<Para>
-Turn off recompilation checking.
-</Para>
-</ListItem>
-</VarListEntry>
-</VariableList>
-</Para>
-
-<Para>
-In the olden days, GHC compared the newly-generated
-<Filename>.hi</Filename> 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 <Filename>.hi</Filename> 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 <Filename>A.hi</Filename> 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 <Filename>B.hi</Filename> 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 <Filename>.o</Filename> file's date (i.e. the source hasn't
-changed since the file was last compiled), and the
-<option>-recomp</option> is given on the command line, 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 “Prelude” modules.
-It distinguishes Prelude modules because their names start with
-"Prel", so don't start your modules that way!
-
-<!-- April 2000: hack disabled. Now we use a different hack!
-
-It distinguishes the two by a hack: a module whose
-<Filename>.hi</Filename> 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 <Option>-i</Option>
-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
-“<Filename>/</Filename>”, or
-“<Filename>A:/</Filename>”, or
-“<Filename>A:\</Filename>” (or
-“<Filename>B:/</Filename>”,
-“<Filename>B:\</Filename>” etc).
-</Para>
--->
-
-<Para>
-Patrick Sansom had a workshop paper about how all this is done (though
-the details have changed quite a bit). <ULink URL="mailto:sansom@dcs.gla.ac.uk">Ask him</ULink> if you want a copy.
-</Para>
-
-</Sect2>
-
-<Sect2 id="using-make">
-<Title>Using <Command>make</Command>
-</Title>
-
-<Para>
-<IndexTerm><Primary><literal>make</literal></Primary></IndexTerm>
-</Para>
-
-<Para>
-It is reasonably straightforward to set up a <Filename>Makefile</Filename> to use with
-GHC, assuming you name your source files the same as your modules.
-Thus:
-</Para>
-
-<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:
- @:
-
-.lhs.o:
- $(HC) -c $< $(HC_OPTS)
-
-.hs.o:
- $(HC) -c $< $(HC_OPTS)
-
-# 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>
-
-</Para>
-
-<Para>
-(Sophisticated <Command>make</Command> variants may achieve some of the above more
-elegantly. Notably, <Command>gmake</Command>'s pattern rules let you write the more
-comprehensible:
-</Para>
-
-<Para>
-
-<ProgramListing>
-%.o : %.lhs
- $(HC) -c $< $(HC_OPTS)
-</ProgramListing>
-
-</Para>
-
-<Para>
-What we've shown should work with any <Command>make</Command>.)
-</Para>
-
-<Para>
-Note the cheesy <Literal>.o.hi</Literal> rule: It records the dependency of the
-interface (<Filename>.hi</Filename>) file on the source. The rule says a <Filename>.hi</Filename> file can
-be made from a <Filename>.o</Filename> file by doing…nothing. Which is true.
-</Para>
-
-<Para>
-Note the inter-module dependencies at the end of the Makefile, which
-take the form
-</Para>
-
-<Para>
-
-<ProgramListing>
-Foo.o Foo.hc Foo.s : Baz.hi # Foo imports Baz
-</ProgramListing>
-
-</Para>
-
-<Para>
-They tell <Command>make</Command> 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>
-Putting inter-dependencies of the form <Literal>Foo.o : Bar.hi</Literal> into your
-<Filename>Makefile</Filename> by hand is rather error-prone. Don't worry—never fear,
-<Command>mkdependHS</Command> is here! (and is distributed as part of GHC) Add the
-following to your <Filename>Makefile</Filename>:
-</Para>
-
-<Para>
-
-<ProgramListing>
-depend :
- mkdependHS -- $(HC_OPTS) -- $(SRCS)
-</ProgramListing>
-
-</Para>
-
-<Para>
-Now, before you start compiling, and any time you change the <Literal>imports</Literal>
-in your program, do <Command>make depend</Command> before you do <Command>make cool_pgm</Command>.
-<Command>mkdependHS</Command> will append the needed dependencies to your <Filename>Makefile</Filename>.
-<Command>mkdependHS</Command> is fully described in <XRef LinkEnd="mkdependHS">.
-</Para>
-
-<Para>
-A few caveats about this simple scheme:
-</Para>
-
-<Para>
-
-<ItemizedList>
-<ListItem>
-
-<Para>
- You may need to compile some modules explicitly to create their
-interfaces in the first place (e.g., <Command>make Bar.o</Command> to create <Filename>Bar.hi</Filename>).
-
-</Para>
-</ListItem>
-<ListItem>
-
-<Para>
- You may have to type <Command>make</Command> more than once for the dependencies
-to have full effect. However, a <Command>make</Command> run that does nothing
-<Emphasis>does</Emphasis> mean “everything's up-to-date.”
-
-</Para>
-</ListItem>
-<ListItem>
-
-<Para>
- This scheme will work with mutually-recursive modules but,
-again, it may take multiple iterations to “settle.”
-
-</Para>
-</ListItem>
-
-</ItemizedList>
-
-</Para>
-
-</Sect2>
-
-<Sect2 id="mutual-recursion">
-<Title>How to compile mutually recursive modules
-</Title>
-
-<Para>
-<IndexTerm><Primary>module system, recursion</Primary></IndexTerm>
-<IndexTerm><Primary>recursion, between modules</Primary></IndexTerm>
-</Para>
-
-<Para>
-Currently, the compiler does not have proper support for dealing with
-mutually recursive modules:
-</Para>
-
-<Para>
-
-<ProgramListing>
-module A where
-
-import B
-
-newtype TA = MkTA Int
-
-f :: TB -> TA
-f (MkTB x) = MkTA x
---------
-module B where
-
-import A
-
-data TB = MkTB !Int
-
-g :: TA -> TB
-g (MkTA x) = MkTB x
-</ProgramListing>
-
-</Para>
-
-<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 <Filename><module>.hi-boot</Filename>. To import from an <Literal>hi-boot</Literal> file instead
-of the standard <Filename>.hi</Filename> 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>
-
-<ProgramListing>
-import {-# SOURCE #-} A
-</ProgramListing>
-
-</Para>
-
-<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>
-For the example at hand, the boot interface file for A would look like
-the following:
-</Para>
-
-<Para>
-
-<ProgramListing>
-__interface A 1 404 where
-__export A TA{MkTA} ;
-1 newtype TA = MkTA PrelBase.Int ;
-</ProgramListing>
-
-</Para>
-
-<Para>
-The syntax is essentially the same as a normal <Filename>.hi</Filename> file
-(unfortunately), but you can usually tailor an existing <Filename>.hi</Filename> file to
-make a <Filename>.hi-boot</Filename> 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 <Function>f</Function>, since <Function>f</Function> 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 <Filename>.hi-boot</Filename> 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>
-
-<ProgramListing>
-__interface A 1 404 where
-__export A TA;
-1 data TA
-</ProgramListing>
-
-</Para>
-
-<Para>
-(You must write all the type parameters, but leave out the '=' and everything that follows it.)
-</Para>
-
-<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>
-
-</Sect2>
-
-</Sect1>
-
-<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 <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>
-<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 <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>
-
-<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>-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>-Onot</Option>:</Term>
-<IndexTerm><Primary>-Onot option</Primary></IndexTerm>
-<IndexTerm><Primary>optimising, reset</Primary></IndexTerm>
-<ListItem>
-<Para>
-This option will make GHC “forget” any
-<Option>-O</Option>ish options it has seen so far. Sometimes useful;
-for example: <Command>make all
-EXTRA_HC_OPTS=-Onot</Command>.
-</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>
-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>
-
-<Para>
-At Glasgow, 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. Alternatively, just look at the
-<Literal>HsC_minus<blah></Literal> lists in the GHC driver script.
-</Para>
-
-</Sect2>
-
-<Sect2>
-<Title><Option>-f*</Option>: 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 <Option>-ffoo</Option> flag, just use
-the <Option>-fno-foo</Option> flag.<IndexTerm><Primary>-fno-<opt> anti-option</Primary></IndexTerm> So, for
-example, you can say <Option>-O2 -fno-strictness</Option>, 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>
-<Option>-fno-strictness</Option><IndexTerm><Primary>-fno-strictness option</Primary></IndexTerm> (strictness
-analyser, because it is sometimes slow),
-</Para>
-</ListItem>
-<ListItem>
-
-<Para>
-<Option>-fno-specialise</Option><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>
-<Option>-fno-cpr-analyse</Option><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 <Option>-Ofile</Option> 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><Option>-fvia-C</Option>:</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 <Function>_ccall_gc_</Function>s or
-<Function>_casm_</Function>s, you probably <Emphasis>have</Emphasis> to use <Option>-fvia-C</Option>.
-</Para>
-
-<Para>
-The lower-case incantation, <Option>-fvia-c</Option>, 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><Option>-funfolding-interface-threshold<n></Option>:</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><Option>-funfolding-creation-threshold<n></Option>:</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
-<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>
-<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 <Option>-funfolding-con-discount</Option>).
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Option>-funfolding-con-discount<n></Option>:</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><Option>-funbox-strict-fields</Option>:</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
-<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>
-
-<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>
-
-<Para>
-
-<ProgramListing>
-f :: T -> Float
-f (T f1 f2) = f1 + f2
-</ProgramListing>
-
-</Para>
-
-<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>
-
-<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 <Function>T</Function> 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 <Function>T</Function> constructor.
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Option>-fsemi-tagging</Option>:</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 <Option>-fsemi-tagging</Option> enough to recommend it.
-(For all we know, it doesn't even work anymore… Sigh.)
-</Para>
-</ListItem>
-</VarListEntry>
-</VariableList>
-</Para>
-
-</Sect2>
-
-<Sect2>
-<Title><Option>-m*</Option>: 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><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:
-
-<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 <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>
-</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 <Option>-O</Option> turned on. (It has
-to be, actually).
-</Para>
-
-<Para>
-If you want to run GCC with <Option>-O2</Option>—which may be worth a few
-percent in execution speed—you can give a
-<Option>-O2-for-C</Option><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 <Command>cpp</Command> is run over your Haskell code only if the
-<Option>-cpp</Option> 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><Option>-D<foo></Option>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-D<name> option</Primary></IndexTerm>
-Define macro <Constant><foo></Constant> in the usual way. NB: does <Emphasis>not</Emphasis> affect
-<Option>-D</Option> macros passed to the C compiler when compiling via C! For those,
-use the <Option>-optc-Dfoo</Option> hack… (see <XRef LinkEnd="forcing-options-through">).
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Option>-U<foo></Option>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-U<name> option</Primary></IndexTerm>
-Undefine macro <Command><foo></Command> in the usual way.
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Option>-I<dir></Option>:</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 GHC driver pre-defines several macros when processing Haskell
-source code (<Filename>.hs</Filename> or <Filename>.lhs</Filename> files):
-</Para>
-
-<Para>
-<VariableList>
-
-<VarListEntry>
-<Term><Constant>__HASKELL98__</Constant>:</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><Constant>__HASKELL__=98</Constant>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>__HASKELL__</Primary></IndexTerm>
-In GHC 4.04 and later, the <Constant>__HASKELL__</Constant> macro is defined as having
-the value <Constant>98</Constant>.
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Constant>__HASKELL1__</Constant>:</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><Constant>__GLASGOW_HASKELL__</Constant>:</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, <Constant>__GLASGOW_HASKELL__</Constant> will be undefined in all other
-implementations that support C-style pre-processing.
-</Para>
-
-<Para>
-(For reference: the comparable symbols for other systems are:
-<Constant>__HUGS__</Constant> for Hugs and <Constant>__HBC__</Constant> 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
-(i.e. <Filename>.hs</Filename>, <Filename>.lhs</Filename>, <Filename>.c</Filename> and <Filename>.hc</Filename> files).
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Constant>__CONCURRENT_HASKELL__</Constant>:</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><Constant>__PARALLEL_HASKELL__</Constant>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>__PARALLEL_HASKELL__ macro</Primary></IndexTerm>
-Only defined when <Option>-parallel</Option> 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 <Option>-opt</Option> flags (see
-<XRef LinkEnd="forcing-options-through">).
-</Para>
-
-<Para>
-A small word of warning: <Option>-cpp</Option> 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>