-%.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>
- Package {
- name = "mypkg",
- 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>Components of a package specification may be specified in
- any order, and are:</para>
-
- <variablelist>
- <varlistentry>
- <term><literal>name</literal></term>
- <indexterm><primary><literal>name</literal></primary>
- <secondary>package specification</secondary></indexterm>
- <listitem>
- <para>The package's name, for use with
- the <literal>-package</literal> flag and as listed in the
- <literal>--list-packages</literal> list.
- </para>
- </listitem>
- </varlistentry>
-
- <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-update-in-place<n></option>:</term>
-<listitem>
-<para>
-Switches on an experimental "optimisation". Switching it on makes the compiler
-a little keener to inline a function that returns a constructor, if the context is
-that of a thunk.
-<ProgramListing>
- x = plusInt a b
-</ProgramListing>
-If we inlined plusInt we might get an opportunity to use update-in-place for
-the thunk 'x'.
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term><option>-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>
-
-</TBody>
-
-</TGroup>
-</InformalTable>
-
-<indexterm><primary>-ansi option (for GCC)</primary></indexterm>
-<indexterm><primary>-pedantic option (for GCC)</primary></indexterm>
-<indexterm><primary>-dgcc-lint option (GCC paranoia)</primary></indexterm>
-</para>
-
-<para>
-If you are compiling with lots of foreign calls, you may need to
-tell the C compiler about some <literal>#include</literal> files. There is no real
-pretty way to do this, but you can use this hack from the
-command-line:
-</para>
-
-<para>
-
-<Screen>
-% ghc -c '-#include <X/Xlib.h>' Xstuff.lhs
-</Screen>
-
-</para>
-
-</sect2>
-
-<Sect2 id="options-linker">
-<Title>Linking and consistency-checking
-</Title>
-
-<para>
-<indexterm><primary>linker options</primary></indexterm>
-<indexterm><primary>ld options</primary></indexterm>
-</para>
-
-<para>
-GHC has to link your code with various libraries, possibly including:
-user-supplied, GHC-supplied, and system-supplied (<option>-lm</option> math
-library, for example).
-</para>
-
-<para>
-<VariableList>
-
-<varlistentry>
-<term><option>-l<FOO></option>:</term>
-<listitem>
-<para>
-<indexterm><primary>-l<lib> option</primary></indexterm>
-Link in a library named <Filename>lib<FOO>.a</Filename> which resides somewhere on the
-library directories path.
-</para>
-
-<para>
-Because of the sad state of most UNIX linkers, the order of such
-options does matter. Thus: <Command>ghc -lbar *.o</Command> is almost certainly
-wrong, because it will search <Filename>libbar.a</Filename> <Emphasis>before</Emphasis> it has
-collected unresolved symbols from the <Filename>*.o</Filename> files.
-<Command>ghc *.o -lbar</Command> is probably better.
-</para>
-
-<para>
-The linker will of course be informed about some GHC-supplied
-libraries automatically; these are:
-</para>
-
-<para>
-
-<InformalTable>
-<TGroup Cols="2">
-<ColSpec Align="Left" Colsep="0">
-<ColSpec Align="Left" Colsep="0">
-<TBody>
-<Row>
-<Entry><Emphasis>-l equivalent</Emphasis> </Entry>
-<Entry> <Emphasis>description</Emphasis> </Entry>
-</Row>
-
-<Row>
-<Entry>
-<option>-lHSrts,-lHSclib</option> </Entry>
-<Entry> basic runtime libraries </Entry>
-</Row>
-<Row>
-<Entry>
-<option>-lHS</option> </Entry>
-<Entry> standard Prelude library </Entry>
-</Row>
-<Row>
-<Entry>
-<option>-lHS_cbits</option> </Entry>
-<Entry> C support code for standard Prelude library </Entry>
-</Row>
-<Row>
-<Entry>
-<option>-lgmp</option> </Entry>
-<Entry> GNU multi-precision library (for Integers)</Entry>
-</Row>
-
-</TBody>
-
-</TGroup>
-</InformalTable>
-
-</para>
-
-<para>
-<indexterm><primary>-lHS library</primary></indexterm>
-<indexterm><primary>-lHS_cbits library</primary></indexterm>
-<indexterm><primary>-lHSrts library</primary></indexterm>
-<indexterm><primary>-lgmp library</primary></indexterm>
-</para>
-</listitem>
-</varlistentry>
-<varlistentry>
-<term><option>-package <name></option>:</term>
-<listitem>
-<para>
-<indexterm><primary>-package <name> option</primary></indexterm>
-</para>
-
-<para>
-If you are using a Haskell “package” (e.g., the POSIX
-library), just use the <option>-package posix</option> option, and the
-correct code should be linked in. See <xref linkend="packages"> for
-more details.
-</para>
-</listitem>
-</varlistentry>
-<varlistentry>
-<term><option>-L<dir></option>:</term>
-<listitem>
-<para>
-<indexterm><primary>-L<dir> option</primary></indexterm>
-Where to find user-supplied libraries… Prepend the directory
-<Filename><dir></Filename> to the library directories path.
-</para>
-</listitem>
-</varlistentry>
-<varlistentry>
-<term><option>-static</option>:</term>
-<listitem>
-<para>
-<indexterm><primary>-static option</primary></indexterm>
-Tell the linker to avoid shared libraries.
-</para>
-</listitem>
-</varlistentry>
-<varlistentry>
-<term><option>-no-link-chk</option> and <option>-link-chk</option>:</term>
-<listitem>
-<para>
-<indexterm><primary>-no-link-chk option</primary></indexterm>
-<indexterm><primary>-link-chk option</primary></indexterm>
-<indexterm><primary>consistency checking of executables</primary></indexterm>
-By default, immediately after linking an executable, GHC verifies that
-the pieces that went into it were compiled with compatible flags; a
-“consistency check”.
-(This is to avoid mysterious failures caused by non-meshing of
-incompatibly-compiled programs; e.g., if one <Filename>.o</Filename> file was compiled
-for a parallel machine and the others weren't.) You may turn off this
-check with <option>-no-link-chk</option>. You can turn it (back) on with
-<option>-link-chk</option> (the default).
-</para>
-</listitem>
-</varlistentry>
-<varlistentry>
-<term><option>-no-hs-main</option>:</term>
-<listitem>
-<para>
-<indexterm><primary>-no-hs-main option</primary></indexterm>
-<indexterm><primary>linking Haskell libraries with foreign code</primary></indexterm>
-</para>
-
-<para>
-In the event you want to include ghc-compiled code as part of another
-(non-Haskell) program, the RTS will not be supplying its definition of
-<Function>main()</Function> at link-time, you will have to. To signal that to the
-driver script when linking, use <option>-no-hs-main</option>.
-</para>
-
-<para>
-Notice that since the command-line passed to the linker is rather
-involved, you probably want to use the ghc driver script to do the
-final link of your `mixed-language' application. This is not a
-requirement though, just try linking once with <option>-v</option> on to see what
-options the driver passes through to the linker.
-</para>
-</listitem>
-</varlistentry>
-</VariableList>
-</para>
-
-</sect2>
-
-</Sect1>
-
-<Sect1 id="sec-using-concurrent">
-<Title>Using Concurrent Haskell</Title>
-
-<para>
-<indexterm><primary>Concurrent Haskell—use</primary></indexterm>
-</para>
-
-<para>
-GHC (as of version 4.00) supports Concurrent Haskell by default,
-without requiring a special option or libraries compiled in a certain
-way. To get access to the support libraries for Concurrent Haskell
-(i.e. <literal>Concurrent</literal> and friends), use the
-<option>-package concurrent</option> option.
-</para>
-
-<para>
-Three RTS options are provided for modifying the behaviour of the
-threaded runtime system. See the descriptions of
-<option>-C[<us>]</option>, <option>-q</option>, and
-<option>-t<num></option> in <XRef LinkEnd="parallel-rts-opts">.
-</para>
-
-<para>
-Concurrent Haskell is described in more detail in <XRef
-LinkEnd="sec-Concurrent">.
-</para>
-
-</Sect1>
-
-<Sect1 id="sec-using-parallel">
-<Title>Using Parallel Haskell</Title>
-
-<para>
-<indexterm><primary>Parallel Haskell—use</primary></indexterm>
-</para>
-
-<para>
-[You won't be able to execute parallel Haskell programs unless PVM3
-(Parallel Virtual Machine, version 3) is installed at your site.]
-</para>
-
-<para>
-To compile a Haskell program for parallel execution under PVM, use the
-<option>-parallel</option> option,<indexterm><primary>-parallel
-option</primary></indexterm> both when compiling <Emphasis>and
-linking</Emphasis>. You will probably want to <literal>import
-Parallel</literal> into your Haskell modules.
-</para>
-
-<para>
-To run your parallel program, once PVM is going, just invoke it
-“as normal”. The main extra RTS option is
-<option>-N<n></option>, to say how many PVM
-“processors” your program to run on. (For more details of
-all relevant RTS options, please see <XRef
-LinkEnd="parallel-rts-opts">.)
-</para>
-
-<para>
-In truth, running Parallel Haskell programs and getting information
-out of them (e.g., parallelism profiles) is a battle with the vagaries of
-PVM, detailed in the following sections.
-</para>
-
-<sect2>
-<Title>Dummy's guide to using PVM</Title>
-
-<para>
-<indexterm><primary>PVM, how to use</primary></indexterm>
-<indexterm><primary>Parallel Haskell—PVM use</primary></indexterm>
-Before you can run a parallel program under PVM, you must set the
-required environment variables (PVM's idea, not ours); something like,
-probably in your <Filename>.cshrc</Filename> or equivalent:
-
-<ProgramListing>
-setenv PVM_ROOT /wherever/you/put/it
-setenv PVM_ARCH `$PVM_ROOT/lib/pvmgetarch`
-setenv PVM_DPATH $PVM_ROOT/lib/pvmd