-<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 .hs .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>
-
- </sect2>
-
- <sect2 id="sec-makefile-dependencies">
- <title>Dependency generation</title>
- <indexterm><primary>dependencies in Makefiles</primary></indexterm>
- <indexterm><primary>Makefile dependencies</primary></indexterm>
-
- <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, GHC has support for
- automatically generating the required dependencies. Add the
- following to your <Filename>Makefile</Filename>:</para>
-
-<ProgramListing>
-depend :
- ghc -M $(HC_OPTS) $(SRCS)
-</ProgramListing>
-
- <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>ghc -M</Command> will append
- the needed dependencies to your
- <Filename>Makefile</Filename>.</Para>
-
- <para>In general, if module <Literal>A</Literal> contains the
- line
-
-<programlisting>
-import B ...blah...
-</programlisting>
-
- then <command>ghc -M</command> will generate a dependency
- line of the form:
-
-<programlisting>
-A.o : B.hi
-</programlisting>
-
- If module <literal>A</literal> contains the line
-
-<programlisting>
-import {-# SOURCE #-} B ...blah...
-</programlisting>
-
- then <command>ghc -M</command> will generate a dependency
- line of the form:
-
-<programlisting>
-A.o : B.hi-boot
-</programlisting>
-
- (See <xref linkend="hi-files"> for details of interface files.)
- If <literal>A</literal> imports multiple modules, then there
- will be multiple lines with <filename>A.o</filename> as the
- target.</para>
-
- <para>By default, <Command>ghc -M</Command> generates all the
- dependencies, and then concatenates them onto the end of
- <Filename>makefile</Filename> (or <Filename>Makefile</Filename>
- if <Filename>makefile</Filename> doesn't exist) bracketed by the
- lines "<Literal># DO NOT DELETE: Beginning of Haskell
- dependencies</Literal>" and "<Literal># DO NOT DELETE: End
- of Haskell dependencies</Literal>". If these lines already
- exist in the <Filename>makefile</Filename>, then the old
- dependencies are deleted first.</para>
-
- <para>Internally, GHC uses a script to generate the
- dependencies, called <command>mkdependHS</command>. This script
- has some options of its own, which you might find useful.
- Options can be passed directly to <command>mkdependHS</command>
- with GHC's <literal>-optdep</literal> option. For example, to
- generate the dependencies into a file called
- <literal>.depend</literal> instead of
- <literal>Makefile</literal>:</para>
-
-<screen>
-ghc -M -optdep-f optdep.depend ...
-</screen>
-
- <para>The full list of options accepted by
- <command>mkdependHS</command> is:</para>
-
- <variablelist>
-
- <varlistentry>
- <term><option>-w</option></term>
- <listitem>
- <para>Turn off warnings about interface file shadowing.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>-f blah</option></term>
- <listitem>
- <para>Use <Filename>blah</Filename> as the makefile,
- rather than <Filename>makefile</Filename> or
- <Filename>Makefile</Filename>. If
- <Filename>blah</Filename> doesn't exist,
- <Command>mkdependHS</Command> creates it. We often use
- <Option>-f .depend</Option> to put the dependencies in
- <Filename>.depend</Filename> and then
- <Command>include</Command> the file
- <Filename>.depend</Filename> into
- <Filename>Makefile</Filename>.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>-o <osuf></option></term>
- <listitem>
- <para>Use <Filename>.<osuf></Filename> as the
- "target file" suffix ( default: <Literal>o</Literal>).
- Multiple <Option>-o</Option> flags are permitted (GHC2.05
- onwards). Thus "<Option>-o hc -o o</Option>" will
- generate dependencies for <Filename>.hc</Filename> and
- <Filename>.o</Filename> files.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>-s <suf></option></term>
- <listitem>
- <para>Make extra dependencies that declare that files with
- suffix
- <Filename>.<suf>_<osuf></Filename>
- depend on interface files with suffix
- <Filename>.<suf>_hi</Filename>, or (for
- <Literal>{-# SOURCE #-}</Literal>
- imports) on <Filename>.hi-boot</Filename>. Multiple
- <Option>-s</Option> flags are permitted. For example,
- <Option>-o hc -s a -s b</Option> will make dependencies
- for <Filename>.hc</Filename> on <Filename>.hi</Filename>,
- <Filename>.a_hc</Filename> on
- <Filename>.a_hi</Filename>, and
- <Filename>.b_hc</Filename> on
- <Filename>.b_hi</Filename>. (Useful in conjunction
- with NoFib "ways".)</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--exclude-module=<file></option></term>
- <listitem>
- <para>Regard <Filename><file></Filename> as
- "stable"; i.e., exclude it from having dependencies on
- it.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>-x</option></term>
- <listitem>
- <para>same as <option>--exclude-module</option></para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--exclude-directory=<dirs></option></term>
- <listitem>
- <para>Regard the colon-separated list of directories
- <Filename><dirs></Filename> as containing stable,
- don't generate any dependencies on modules therein.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>-xdirs</option></term>
- <listitem>
- <para>same as <Option>--exclude-directory</Option>.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--include-module=<file></option></term>
- <listitem>
- <para>Regard <Filename><file></Filename> as not
- "stable"; i.e., generate dependencies on it (if any). This
- option is normally used in conjunction with the
- <Option>--exclude-directory</Option> option.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--include-prelude</option></term>
- <listitem>
- <para>Regard prelude libraries as unstable, i.e., generate
- dependencies on the prelude modules used (including
- <Literal>Prelude</Literal>). This option is normally only
- used by the various system libraries. If a
- <Option>-package</Option> option is used, dependencies will
- also be generated on the library's interfaces.</para>
- </listitem>
- </varlistentry>
- </variablelist>
-
-</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="packages">
- <title>Packages</title>
- <indexterm><primary>packages</primary></indexterm>
-
- <para>Packages are collections of libraries, conveniently grouped
- together as a single entity. The package system is flexible: a
- package may consist of Haskell code, foreign language code (eg. C
- libraries), or a mixture of the two. A package is a good way to
- group together related Haskell modules, and is essential if you
- intend to make the modules into a Windows DLL (see below).</para>
-
- <para>Because packages can contain both Haskell and C libraries, they
- are also a good way to provide convenient access to a Haskell
- layer over a C library.</para>
-
- <para>GHC comes with several packages (see <xref
- linkend="book-hslibs">), and packages can be added/removed from an
- existing GHC installation.</para>
-
- <sect2 id="listing-packages">
- <title>Listing the available packages</title>
- <indexterm><primary>packages</primary>
- <secondary>listing</secondary></indexterm>
-
- <para>To see what packages are currently installed, use the
- <literal>--list-packages</literal> option:</para>
- <indexterm><primary><literal>--list-packages</literal></primary>
- </indexterm>
-
-<screen>
- $ ghc --list-packages
- gmp, rts, std, lang, concurrent, data, net, posix, text, util
-</screen>
-
- <para>Note that your GHC installation might have a slightly
- different set of packages installed.</para>
-
- <para>The <literal>gmp</literal> and <literal>rts</literal>
- packages are always present, and represent the multi-precision
- integer and runtime system libraries respectively. The
- <literal>std</literal> package contains the Haskell prelude.
- The rest of the packages are optional libraries.</para>
-
- </sect2>
-
- <sect2 id="using-packages">
- <title>Using a package</title>
- <indexterm><primary>packages</primary>
- <secondary>using</secondary></indexterm>
-
- <para>To use a package, add the <literal>-package</literal> flag
- to the command line:</para>
-
- <variablelist>
- <varlistentry>
- <term><option>-package <lib></option></term>
- <indexterm><primary>-package <lib> option</primary></indexterm>
- <listitem>
- <para>This option brings into scope all the modules from
- package <literal><lib></literal> (they still have to
- be imported in your Haskell source, however). It also
- causes the relevant libraries to be linked when linking is
- being done.</para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <para>Some packages depend on other packages, for example the
- <literal>text</literal> package makes use of some of the modules
- in the <literal>lang</literal> package. The package system
- takes care of all these dependencies, so that when you say
- <literal>-package text</literal> on the command line, you
- automatically get <literal>-package lang</literal> too.</para>
- </sect2>
-
- <sect2 id="building-packages">
- <title>Building a package from Haskell source</title>
- <indexterm><primary>packages</primary>
- <secondary>building</secondary></indexterm>
-
- <para>It takes some special considerations to build a new
- package:</para>
-
- <itemizedlist>
- <listitem>
- <para>A package may contain several Haskell modules. A
- package may span many directories, or many packages may
- exist in a single directory. Packages may not be mutually
- recursive.</para>
- </listitem>
-
- <listitem>
- <para>A package has a name
- (e.g. <filename>std</filename>)</para>
- </listitem>
-
- <listitem>
- <para>The Haskell code in a package may be built into one or
- more Unix libraries (e.g. <Filename>libHSfoo.a</Filename>),
- or a single DLL on Windows
- (e.g. <Filename>HSfoo.dll</Filename>). The restriction to a
- single DLL on Windows is that the package system is used to
- tell the compiler when it should make an inter-DLL call
- rather than an intra-DLL call (inter-DLL calls require an
- extra indirection).</para>
- </listitem>
-
- <listitem>
- <para>GHC does not maintain detailed cross-package
- dependency information. It does remember which modules in
- other packages the current module depends on, but not which
- things within those imported things.</para>
- </listitem>
- </itemizedlist>
-
- <para>To compile a module which is to be part of a new package,
- use the <literal>-package-name</literal> option:</para>
-
- <variablelist>
- <varlistentry>
- <term><option>-package-name <foo></option></term>
- <indexterm><primary><literal>-package-name</literal></primary>
- <secondary>option</secondary></indexterm>
- <listitem>
- <para>This option is added to the command line when
- compiling a module that is destined to be part of package
- <literal>foo</literal>. If this flag is omitted then the
- default package <literal>Main</literal> is assumed.</para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <para>Failure to use the <literal>-package-name</literal> option
- when compiling a package will result in disaster on Windows, but
- is relatively harmless on Unix at the moment (it will just cause
- a few extra dependencies in some interface files). However,
- bear in mind that we might add support for Unix shared libraries
- at some point in the future.</para>
-
- <para>It is worth noting that on Windows, because each package
- is built as a DLL, and a reference to a DLL costs an extra
- indirection, intra-package references are cheaper than
- inter-package references. Of course, this applies to the
- <Filename>Main</Filename> package as well.</para>
-
- </sect2>
- <sect2 id="package-management">
- <title>Package management</title>
- <indexterm><primary>packages</primary>
- <secondary>management</secondary></indexterm>
-
- <para>GHC uses a package configuration file, called
- <literal>packages.conf</literal>, which can be found in your GHC
- install directory. This file isn't intended to be edited
- directly, instead GHC provides options for adding & removing
- packages:</para>
-
- <variablelist>
- <varlistentry>
- <term><option>--add-package</option></term>
- <indexterm><primary><literal>--add-package</literal></primary>
- <secondary>option</secondary></indexterm>
- <listitem>
- <para>Reads a package specification (see below) on stdin,
- and adds it to the database of installed packages. The
- package specification must be a package that isn't already
- installed.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--delete-package <foo></option></term>
- <indexterm><primary><literal>--delete-package</literal></primary>
- <secondary>option</secondary></indexterm>
- <listitem>
- <para>Removes the specified package from the installed
- configuration.</para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <para>In both cases, the old package configuration file is saved
- in <literal>packages.conf.old</literal> in your GHC install
- directory, so in an emergency you can always copy this file into
- <literal>package.conf</literal> to restore the old
- settings.</para>
-
- <para>A package specification looks like this:</para>
-
-<screen>
- ("mypkg",
- "4.08",
- Package
- {
- import_dirs = ["/usr/local/lib/imports/mypkg"],
- library_dirs = ["/usr/local/lib"],
- hs_libraries = ["HSmypkg" ],
- extra_libraries = ["HSmypkg_cbits"],
- include_dirs = [],
- c_includes = ["HsMyPkg.h"],
- package_deps = ["text", "data"],
- extra_ghc_opts = [],
- extra_cc_opts = [],
- extra_ld_opts = ["-lmy_clib"]
- }
- )
-</screen>
-
- <para>The first line is the name of the package, for use with
- the <literal>-package</literal> flag and as listed in the
- <literal>--list-packages</literal> list. The second line is the
- version of GHC that was used to compile any Haskell code in this
- package (GHC will refuse to add the package if its version
- number differs from this one). The rest of the components of
- the package specification may be specified in any order, and
- are:</para>
-
- <variablelist>
- <varlistentry>
- <term><literal>import_dirs</literal></term>
- <indexterm><primary><literal>import_dirs</literal></primary>
- <secondary>package specification</secondary></indexterm>
- <listitem>
- <para>A list of directories containing interface files
- (<literal>.hi</literal> files) for this package.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>library_dirs</literal></term>
- <indexterm><primary><literal>library_dirs</literal></primary>
- <secondary>package specification</secondary></indexterm>
- <listitem>
- <para>A list of directories containing libraries for this
- package.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>hs_libraries</literal></term>
- <indexterm><primary><literal>hs_libraries</literal></primary>
- <secondary>package specification</secondary></indexterm>
- <listitem>
- <para>A list of libraries containing Haskell code for this
- package, with the <literal>.a</literal> or
- <literal>.dll</literal> suffix omitted. On Unix, the
- <literal>lib</literal> prefix is also omitted.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>extra_libraries</literal></term>
- <indexterm><primary><literal>extra_libraries</literal></primary>
- <secondary>package specification</secondary></indexterm>
- <listitem>
- <para>A list of extra libraries for this package. The
- difference between <literal>hs_libraries</literal> and
- <literal>extra_libraries</literal> is that
- <literal>hs_libraries</literal> normally have several
- versions, to support profiling, parallel and other build
- options. The various versions are given different
- suffixes to distinguish them, for example the profiling
- version of the standard prelude library is named
- <filename>libHSstd_p.a</filename>, with the
- <literal>_p</literal> indicating that this is a profiling
- version. The suffix is added automatically by GHC for
- <literal>hs_libraries</literal> only, no suffix is added
- for libraries in
- <literal>extra_libraries</literal>.</para>
-
- <para>Also, <literal>extra_libraries</literal> are placed
- on the linker command line before the
- <literal>hs_libraries</literal> for the same package. If
- your package has dependencies in the other direction, you
- might need to make two separate packages.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>include_dirs</literal></term>
- <indexterm><primary><literal>include_dirs</literal></primary>
- <secondary>package specification</secondary></indexterm>
- <listitem>
- <para>A list of directories containing C includes for this
- package (maybe the empty list).</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>c_includes</literal></term>
- <indexterm><primary><literal>c_includes</literal></primary>
- <secondary>package specification</secondary></indexterm>
- <listitem>
- <para>A list of files to include for via-C compilations
- using this package. Typically this include file will
- contain function prototypes for any C functions used in
- the package, in case they end up being called as a result
- of Haskell functions from the package being
- inlined.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>package_deps</literal></term>
- <indexterm><primary><literal>package_deps</literal></primary>
- <secondary>package specification</secondary></indexterm>
- <listitem>
- <para>A list of packages which this package depends
- on.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>extra_ghc_opts</literal></term>
- <indexterm><primary><literal>extra_ghc_opts</literal></primary>
- <secondary>package specification</secondary></indexterm>
- <listitem>
- <para>Extra arguments to be added to the GHC command line
- when this package is being used.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>extra_cc_opts</literal></term>
- <indexterm><primary><literal>extra_cc_opts</literal></primary>
- <secondary>package specification</secondary></indexterm>
- <listitem>
- <para>Extra arguments to be added to the gcc command line
- when this package is being used (only for via-C
- compilations).</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>extra_ld_opts</literal></term>
- <indexterm><primary><literal>extra_ld_opts</literal></primary>
- <secondary>package specification</secondary></indexterm>
- <listitem>
- <para>Extra arguments to be added to the gcc command line
- (for linking) when this package is being used.</para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <para>For examples of more package specifications, take a look
- at the <literal>package.conf</literal> in your GHC
- installation.</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 (e.g. for floating-point intensive code on Intel).
-If you use <Function>_casm_</Function>s (which are utterly
-deprecated), 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>
-<VarListEntry>
-<Term><Option>-fexcess-precision</Option>:</Term>
-<ListItem>
-<Para>
-When this option is given, intermediate floating point values can have
-a <Emphasis>greater</Emphasis> precision/range than the final type.
-Generally this is a good thing, but some programs may rely on the
-exact precision/range of <Literal>Float</Literal>/<Literal>Double</Literal>
-values and should not use this option for their compilation.
-</Para>
-</ListItem>
-</VarListEntry>
-</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>
-
-<Para>
-
-<ProgramListing>
-strmod = "\
-\ p \
-\ "
-</ProgramListing>
-
-</Para>
-
-<Para>
-don't work with <Option>-cpp</Option>; <Filename>/usr/bin/cpp</Filename> elides the
-backslash-newline pairs.
-</Para>
-
-<Para>
-However, it appears that if you add a space at the end of the line,
-then <Command>cpp</Command> (at least GNU <Command>cpp</Command> and possibly other <Command>cpp</Command>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><Option>-ansi</Option> </Entry>
-<Entry> do ANSI C (not K&R) </Entry>
-</Row>
-<Row>
-<Entry>
-<Option>-pedantic</Option> </Entry>
-<Entry> be so</Entry>
-</Row>
-<Row>
-<Entry>
-<Option>-dgcc-lint</Option> </Entry>
-<Entry> (hack) short for “make GCC very paranoid”</Entry>
-</Row>