<Command>make</Command> rule for GHC compiling…
</Para>
-<Para>
-FURTHER EXOTICA: If you are doing a normal <Filename>.hs</Filename>-to-<Filename>.o</Filename> compilation
-but would like to hang onto the intermediate <Filename>.hc</Filename> C file, just
-throw in a <Option>-keep-hc-file-too</Option> option<IndexTerm><Primary>-keep-hc-file-too option</Primary></IndexTerm>.
-If you would like to look at the assembler output, toss in a
-<Option>-keep-s-file-too</Option>,<IndexTerm><Primary>-keep-s-file-too option</Primary></IndexTerm> too.
-</Para>
+ <sect2 id="keeping-intermediates">
+ <title>Keeping Intermediate Files</title>
+ <indexterm><primary>intermediate files, saving</primary>
+ </indexterm>
+ <indexterm><primary><literal>.hc</literal> files, saving</primary>
+ </indexterm>
+ <indexterm><primary><literal>.s</literal> files, saving</primary>
+ </indexterm>
+
+ <para>The following options are useful for keeping certain
+ intermediate files around, when normally GHC would throw these
+ away after compilation:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><literal>-keep-hc-files</literal></term>
+ <indexterm>
+ <primary><literal>-keep-hc-files</literal></primary>
+ </indexterm>
+ <listitem>
+ <para>Keep intermediate <literal>.hc</literal> files when
+ doing <literal>.hs</literal>-to-<literal>.o</literal>
+ compilations via C (NOTE: <literal>.hc</literal> files
+ aren't generated when using the native code generator, you
+ may need to use <literal>-fvia-C</literal> to force them
+ to be produced).</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>-keep-s-files</literal></term>
+ <indexterm>
+ <primary><literal>-keep-s-files</literal></primary>
+ </indexterm>
+ <listitem>
+ <para>Keep intermediate <literal>.s</literal> files.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>-keep-raw-s-files</literal></term>
+ <indexterm>
+ <primary><literal>-keep-raw-s-files</literal></primary>
+ </indexterm>
+ <listitem>
+ <para>Keep intermediate <literal>.raw-s</literal> files.
+ These are the direct output from the C compiler, before
+ GHC does “assembly mangling” to produce the
+ <literal>.s</literal> file. Again, these are not produced
+ when using the native code generator.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>-keep-tmp-files</literal></term>
+ <indexterm>
+ <primary><literal>-keep-tmp-files</literal></primary>
+ </indexterm>
+ <indexterm>
+ <primary>temporary files</primary>
+ <secondary>keeping</secondary>
+ </indexterm>
+ <listitem>
+ <para>Instructs the GHC driver not to delete any of its
+ temporary files, which it normally keeps in
+ <literal>/tmp</literal> (or possibly elsewhere; see <xref
+ linkend="temp-files">). Running GHC with
+ <literal>-v</literal> will show you what temporary files
+ were generated along the way.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sect2>
<Sect2 id="saving-ghc-stderr">
<Title>Saving GHC's standard error output
<Title>Redirecting temporary files
</Title>
-<Para>
-<IndexTerm><Primary>temporary files, redirecting</Primary></IndexTerm>
-</Para>
+ <indexterm>
+ <primary>temporary files</primary>
+ <secondary>redirecting</secondary>
+ </indexterm>
<Para>
-If you have trouble because of running out of space in <Filename>/tmp</Filename> (or
-wherever your installation thinks temporary files should go), you may
-use the <Option>-tmpdir <dir></Option><IndexTerm><Primary>-tmpdir <dir> option</Primary></IndexTerm> option
-to specify an alternate directory. For example, <Option>-tmpdir .</Option> says to
-put temporary files in the current working directory.
+If you have trouble because of running out of space in
+<Filename>/tmp</Filename> (or wherever your installation thinks
+temporary files should go), you may use the <Option>-tmpdir
+<dir></Option><IndexTerm><Primary>-tmpdir <dir>
+option</Primary></IndexTerm> option to specify an alternate directory.
+For example, <Option>-tmpdir .</Option> says to put temporary files in
+the current working directory.
</Para>
<Para>
-Alternatively, use your <Constant>TMPDIR</Constant> environment variable.<IndexTerm><Primary>TMPDIR
-environment variable</Primary></IndexTerm> Set it to the name of the directory where
-temporary files should be put. GCC and other programs will honour the
-<Constant>TMPDIR</Constant> variable as well.
+Alternatively, use your <Constant>TMPDIR</Constant> environment
+variable.<IndexTerm><Primary>TMPDIR environment
+variable</Primary></IndexTerm> Set it to the name of the directory
+where temporary files should be put. GCC and other programs will
+honour the <Constant>TMPDIR</Constant> variable as well.
</Para>
<Para>
<IndexTerm><Primary>separate compilation</Primary></IndexTerm>
<IndexTerm><Primary>recompilation checker</Primary></IndexTerm>
<IndexTerm><Primary>make and recompilation</Primary></IndexTerm>
-</Para>
-
-<Para>
This section describes how GHC supports separate compilation.
</Para>
</VarListEntry>
<VarListEntry>
-<Term><Option>-syslib <lib></Option></Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-syslib <lib> option</Primary></IndexTerm>
-If you are using a system-supplied non-Prelude library (e.g., the
-POSIX library), just use a <Option>-syslib posix</Option> option (for example). The
-right interface files should then be available. <XRef LinkEnd="ghc-prelude"> lists the
-libraries available by this mechanism.
-</Para>
-</ListItem>
-</VarListEntry>
-
-<VarListEntry>
<Term><Option>-I<dir></Option></Term>
<ListItem>
<Para>
<Title>The recompilation checker
</Title>
-<Para>
<IndexTerm><Primary>recompilation checker</Primary></IndexTerm>
-</Para>
<Para>
-In the olden days, GHC compared the newly-generated <Filename>.hi</Filename> file with
-the previous version; if they were identical, it left the old one
-alone and didn't change its modification date. In consequence,
-importers of a module with an unchanged output <Filename>.hi</Filename> file were not
+<variablelist>
+<VarListEntry>
+<Term><Option>-recomp</Option></Term>
+<IndexTerm><Primary><option>-recomp</option> option</Primary></IndexTerm>
+<ListItem>
+<Para>
+(On by default) Turn on recompilation checking. This will stop
+compilation early, leaving an existing <filename>.o</filename> file in
+place, if it can be determined that the module does not need to be
recompiled.
</Para>
-
+</ListItem>
+</VarListEntry>
+<VarListEntry>
+<Term><Option>-no-recomp</Option></Term>
+<IndexTerm><Primary><option>-recomp</option> option</Primary></IndexTerm>
+<ListItem>
<Para>
-This doesn't work any more. In our earlier example, module <Literal>C</Literal> does
-not import module <Literal>A</Literal> directly, yet changes to <Filename>A.hi</Filename> should force a
-recompilation of <Literal>C</Literal>. And some changes to <Literal>A</Literal> (changing the
-definition of a function that appears in an inlining of a function
-exported by <Literal>B</Literal>, say) may conceivably not change <Filename>B.hi</Filename> one jot. So
-now…
+Turn off recompilation checking.
+</Para>
+</ListItem>
+</VarListEntry>
+</VariableList>
</Para>
<Para>
-GHC keeps a version number on each interface file, and on each type
-signature within the interface file. It also keeps in every interface
-file a list of the version numbers of everything it used when it last
-compiled the file. If the source file's modification date is earlier
-than the <Filename>.o</Filename> file's date (i.e. the source hasn't changed since the
-file was last compiled), GHC will be clever. It compares the version
-numbers on the things it needs this time with the version numbers on
-the things it needed last time (gleaned from the interface file of the
-module being compiled); if they are all the same it stops compiling
-rather early in the process saying “Compilation IS NOT required”.
-What a beautiful sight!
+In the olden days, GHC compared the newly-generated
+<Filename>.hi</Filename> file with the previous version; if they were
+identical, it left the old one alone and didn't change its
+modification date. In consequence, importers of a module with an
+unchanged output <Filename>.hi</Filename> file were not recompiled.
</Para>
<Para>
-GHC <Emphasis>only</Emphasis> keeps detailed dependency information for “user” modules,
-not for “library” modules. It distinguishes the two by a hack: a module
-whose <Filename>.hi</Filename> file has an absolute path name is considered a library module,
-while a relative path name indicates a user module. So if you have a
-multi-directory application, use <Emphasis>relative</Emphasis> path names in your
-<Option>-i</Option> path, to force GHC to record detailed dependency information.
-Use absolute path names only for directories containing slowly-changing
-library modules.
+This doesn't work any more. In our earlier example, module
+<Literal>C</Literal> does not import module <Literal>A</Literal>
+directly, yet changes to <Filename>A.hi</Filename> should force a
+recompilation of <Literal>C</Literal>. And some changes to
+<Literal>A</Literal> (changing the definition of a function that
+appears in an inlining of a function exported by <Literal>B</Literal>,
+say) may conceivably not change <Filename>B.hi</Filename> one jot. So
+now…
</Para>
<Para>
-A path is considered “absolute” if it starts with “<Filename>/</Filename>”, or
-“<Filename>A:/</Filename>”, or “<Filename>A:\</Filename>” (or “<Filename>B:/</Filename>”, “<Filename>B:\</Filename>” etc).
+GHC keeps a version number on each interface file, and on each type
+signature within the interface file. It also keeps in every interface
+file a list of the version numbers of everything it used when it last
+compiled the file. If the source file's modification date is earlier
+than the <Filename>.o</Filename> file's date (i.e. the source hasn't
+changed since the file was last compiled), and the
+<option>-recomp</option> is given on the command line, GHC will be
+clever. It compares the version numbers on the things it needs this
+time with the version numbers on the things it needed last time
+(gleaned from the interface file of the module being compiled); if
+they are all the same it stops compiling rather early in the process
+saying “Compilation IS NOT required”. What a beautiful
+sight!
</Para>
<Para>
Patrick Sansom had a workshop paper about how all this is done (though
-the details have changed quite a bit). <ULink URL="mailto:sansom@dcs.gla.ac.uk">Ask him</ULink>) if you want a copy.
+the details have changed quite a bit). <ULink URL="mailto:sansom@dcs.gla.ac.uk">Ask him</ULink> if you want a copy.
</Para>
</Sect2>
+
<Sect2 id="using-make">
<Title>Using <Command>make</Command>
</Title>
</Para>
<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.
+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>
SRCS = Main.lhs Foo.lhs Bar.lhs
OBJS = Main.o Foo.o Bar.o
-.SUFFIXES : .o .hi .lhs .hc .s
+.SUFFIXES : .o .hs .hi .lhs .hc .s
cool_pgm : $(OBJS)
rm $@
nicely.
</Para>
-<Para>
-Putting inter-dependencies of the form <Literal>Foo.o : Bar.hi</Literal> into your
-<Filename>Makefile</Filename> by hand is rather error-prone. Don't worry—never fear,
-<Command>mkdependHS</Command> is here! (and is distributed as part of GHC) Add the
-following to your <Filename>Makefile</Filename>:
-</Para>
+ </sect2>
-<Para>
+ <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 :
- mkdependHS -- $(HC_OPTS) -- $(SRCS)
+ ghc -M $(HC_OPTS) $(SRCS)
</ProgramListing>
-</Para>
-
-<Para>
-Now, before you start compiling, and any time you change the <Literal>imports</Literal>
-in your program, do <Command>make depend</Command> before you do <Command>make cool_pgm</Command>.
-<Command>mkdependHS</Command> will append the needed dependencies to your <Filename>Makefile</Filename>.
-<Command>mkdependHS</Command> is fully described in <XRef LinkEnd="mkdependHS">.
-</Para>
-
-<Para>
-A few caveats about this simple scheme:
-</Para>
-
-<Para>
-
-<ItemizedList>
-<ListItem>
-
-<Para>
- You may need to compile some modules explicitly to create their
-interfaces in the first place (e.g., <Command>make Bar.o</Command> to create <Filename>Bar.hi</Filename>).
-
-</Para>
-</ListItem>
-<ListItem>
-
-<Para>
- You may have to type <Command>make</Command> more than once for the dependencies
-to have full effect. However, a <Command>make</Command> run that does nothing
-<Emphasis>does</Emphasis> mean “everything's up-to-date.”
-
-</Para>
-</ListItem>
-<ListItem>
-
-<Para>
- This scheme will work with mutually-recursive modules but,
-again, it may take multiple iterations to “settle.”
-
-</Para>
-</ListItem>
-
-</ItemizedList>
-
-</Para>
+ <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>
</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>
<VarListEntry>
<Term>No <Option>-O*</Option>-type option specified:</Term>
+<IndexTerm><Primary>-O* not specified</Primary></IndexTerm>
<ListItem>
<Para>
-<IndexTerm><Primary>-O* not specified</Primary></IndexTerm>
This is taken to mean: “Please compile quickly; I'm not over-bothered
about compiled-code quality.” So, for example: <Command>ghc -c Foo.hs</Command>
</Para>
</VarListEntry>
<VarListEntry>
<Term><Option>-O</Option> or <Option>-O1</Option>:</Term>
-<ListItem>
-<Para>
<IndexTerm><Primary>-O option</Primary></IndexTerm>
<IndexTerm><Primary>-O1 option</Primary></IndexTerm>
-<IndexTerm><Primary>optimise normally</Primary></IndexTerm>
-Means: “Generate good-quality code without taking too long about it.”
-Thus, for example: <Command>ghc -c -O Main.lhs</Command>
+<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>
-<IndexTerm><Primary>-O2 option</Primary></IndexTerm>
-<IndexTerm><Primary>optimise aggressively</Primary></IndexTerm>
Means: “Apply every non-dangerous optimisation, even if it means
significantly longer compile times.”
</Para>
</VarListEntry>
<VarListEntry>
<Term><Option>-O2-for-C</Option>:</Term>
-<ListItem>
-<Para>
<IndexTerm><Primary>-O2-for-C option</Primary></IndexTerm>
<IndexTerm><Primary>gcc, invoking with -O2</Primary></IndexTerm>
-</Para>
-
+<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
</VarListEntry>
<VarListEntry>
<Term><Option>-Onot</Option>:</Term>
-<ListItem>
-<Para>
<IndexTerm><Primary>-Onot option</Primary></IndexTerm>
<IndexTerm><Primary>optimising, reset</Primary></IndexTerm>
-</Para>
-
+<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>.
+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>
-<ListItem>
-<Para>
<IndexTerm><Primary>-Ofile <file> option</Primary></IndexTerm>
<IndexTerm><Primary>optimising, customised</Primary></IndexTerm>
-</Para>
-
+<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>.
+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.
+In that file, comments are of the
+<Literal>#</Literal>-to-end-of-line variety; blank lines and most
+whitespace is ignored.
</Para>
<Para>
</Para>
<Para>
-Compile via C, and don't use the native-code generator. (There are
-many cases when GHC does this on its own.) You might pick up a little
-bit of speed by compiling via C. If you use <Function>_ccall_gc_</Function>s or
-<Function>_casm_</Function>s, you probably <Emphasis>have</Emphasis> to use <Option>-fvia-C</Option>.
+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>
</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>
</Para>
<Para>
-If you are compiling with lots of <Literal>ccalls</Literal>, etc., you may need to
+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:
</ListItem>
</VarListEntry>
<VarListEntry>
-<Term><Option>-syslib <name></Option>:</Term>
+<Term><Option>-package <name></Option>:</Term>
<ListItem>
<Para>
-<IndexTerm><Primary>-syslib <name> option</Primary></IndexTerm>
+<IndexTerm><Primary>-package <name> option</Primary></IndexTerm>
</Para>
<Para>
-If you are using a Haskell “system library” (e.g., the POSIX
-library), just use the <Option>-syslib posix</Option> option, and the correct code
-should be linked in.
+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>
</Sect1>
-<Sect1>
+<Sect1 id="sec-using-concurrent">
<Title>Using Concurrent Haskell</Title>
<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>-syslib concurrent</Option> option.
+(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">.
+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="concurrent-and-parallel">.
+Concurrent Haskell is described in more detail in <XRef
+LinkEnd="sec-Concurrent">.
</Para>
</Sect1>
-<Sect1>
+<Sect1 id="sec-using-parallel">
<Title>Using Parallel Haskell</Title>
<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.
+<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">.)
+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>
<Term><Option>-C[<us>]</Option>:</Term>
<ListItem>
<Para>
-<IndexTerm><Primary>-C<us> RTS option</Primary></IndexTerm>
-Sets the context switch interval to <Literal><us></Literal> microseconds. A context
-switch will occur at the next heap allocation after the timer expires.
-With <Option>-C0</Option> or <Option>-C</Option>, context switches will occur as often as
-possible (at every heap allocation). By default, context switches
-occur every 10 milliseconds. Note that many interval timers are only
-capable of 10 millisecond granularity, so the default setting may be
-the finest granularity possible, short of a context switch at every
-heap allocation.
-</Para>
-
-<Para>
-[NOTE: this option currently has no effect (version 4.00). Context
-switches happen when the current heap block is full, i.e. every 4k of
-allocation].
+<IndexTerm><Primary>-C<us> RTS option</Primary></IndexTerm> Sets
+the context switch interval to <Literal><s></Literal> seconds.
+A context switch will occur at the next heap block allocation after
+the timer expires (a heap block allocation occurs every 4k of
+allocation). With <Option>-C0</Option> or <Option>-C</Option>,
+context switches will occur as often as possible (at every heap block
+allocation). By default, context switches occur every 20ms
+milliseconds. Note that GHC's internal timer ticks every 20ms, and
+the context switch timer is always a multiple of this timer, so 20ms
+is the maximum granularity available for timed context switches.
</Para>
</ListItem>
</VarListEntry>
&debug
</Chapter>
+
+<!-- Emacs stuff:
+ ;;; Local Variables: ***
+ ;;; mode: sgml ***
+ ;;; sgml-parent-document: ("users_guide.sgml" "book" "chapter") ***
+ ;;; End: ***
+ -->