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

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.

GHC comes with several packages (see Haskell Libraries), and packages can be added to or removed
from an existing GHC installation, using the supplied
ghc-pkg tool, described in Section 4.10.4.

This option brings into scope all the modules from
package lib (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.

Some packages depend on other packages, for example the
text package makes use of some of the modules
in the lang package. The package system
takes care of all these dependencies, so that when you say
-package text on the command line, you
automatically get -package lang too.

When GHC starts up, it automatically reads the default set
of packages from a configuration file, normally named
package.conf in your GHC installation
directory.

You can load in additional package configuration files
using the -package-conf option:

-package-conf file

Read in the package configuration file
file in addition to the system
default file. This allows the user to have a local set of
packages in addition to the system-wide ones.

To create your own package configuration file, just create
a new file and put the string
"[]" in it. Packages can be
added to the new configuration file using the
ghc-pkg tool, described in Section 4.10.4.

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.

A package has a name
(e.g. std)

The Haskell code in a package may be built into one or
more Unix libraries (e.g. libHSfoo.a),
or a single DLL on Windows
(e.g. HSfoo.dll). 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). Building packages as DLLs
doesn't work at the moment; see Section 11.3 for the gory details.

Versions of the Haskell libraries for use with GHCi
may also be included: GHCi cannot load .a
files directly, instead it will look for an object file
called HSfoo.o (the object suffix
varies between platforms, as usual) and load that. An
object file can be built from a .a
archive as follows (using GNU ld on
Unix):

ld -r ––whole-archive -o HSfoo.o libHSfoo.a

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.

To compile a module which is to be part of a new package,
use the -package-name option:

-package-name foo

This option is added to the command line when
compiling a module that is destined to be part of package
foo. If this flag is omitted then the
default package Main is assumed.

Failure to use the -package-name 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.

It is worth noting that on Windows, when each package
is built as a DLL, since a reference to a DLL costs an extra
indirection, intra-package references are cheaper than
inter-package references. Of course, this applies to the
Main package as well.

The ghc-pkg tool allows packages to be
added or removed from a package configuration file. By default,
the system-wide configuration file is used, but alternatively
packages can be added or removed from a user-specified
configuration file using the ––config-file
option. An empty package configuration file consists of the
string "[]".

The ghc-pkg program accepts the
following options:

––add-package, -a

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.

––input-file=file, -i file

Read new package specifications from file
file. If a value of
"-" is given, standard input is used.
If no -i is present on the command-line,
an input file of "-" is assumed.

––config-file file, -f file

Use file instead of the
default package configuration file. This, in conjunction
with GHC's -package-conf option, allows
a user to have a local set of packages in addition to the
system-wide installed set.

Note that your GHC installation might have a
slightly different set of packages installed.

The gmp and
rts packages are always present, and
represent the multi-precision integer and runtime system
libraries respectively. The std
package contains the Haskell prelude and standard
libraries. The rest of the packages are optional
libraries.

––remove-package foo, -r foo

Removes the specified package from the installed
configuration.

When modifying the configuration file
file, a copy of the original file is
saved in file.old,
so in an emergency you can always restore the old settings by
copying the old file back again.

Components of a package specification may be specified in
any order, and are:

name

The package's name, for use with
the -package flag and as listed in the
––list-packages list.

import_dirs

A list of directories containing interface files
(.hi files) for this package.

source_dirs

A list of directories containing Haskell source
files for this package. This field isn't used by GHC, but
could potentially be used by an all-interpreted system
like Hugs.

library_dirs

A list of directories containing libraries for this
package.

hs_libraries

A list of libraries containing Haskell code for this
package, with the .a or
.dll suffix omitted. When packages are
built as libraries, the
lib prefix is also omitted.

For use with GHCi, each library should have an
object file too. The name of the object file does
not have a lib
prefix, and has the normal object suffix for your
platform.

For example, if we specify a Haskell library as
HSfoo in the package spec, then the
various flavours of library that GHC actually uses will be
called:

libHSfoo.a

The name of the library on Unix
systems.

HSfoo.dll

The name of the dynamic library on Windows
systems.

HSfoo.o, HSfoo.obj

The object version of the library used by
GHCi.

extra_libraries

A list of extra libraries for this package. The
difference between hs_libraries and
extra_libraries is that
hs_libraries 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
libHSstd_p.a, with the
_p indicating that this is a profiling
version. The suffix is added automatically by GHC for
hs_libraries only, no suffix is added
for libraries in
extra_libraries.

Also, extra_libraries are placed
on the linker command line after the
hs_libraries for the same package. If
your package has dependencies in the other direction (i.e.
extra_libraries depends on
hs_libraries), and the libraries are
static, you might need to make two separate
packages.

include_dirs

A list of directories containing C includes for this
package (maybe the empty list).

c_includes

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.

package_deps

A list of packages which this package depends
on.

extra_ghc_opts

Extra arguments to be added to the GHC command line
when this package is being used.

extra_cc_opts

Extra arguments to be added to the gcc command line
when this package is being used (only for via-C
compilations).

extra_ld_opts

Extra arguments to be added to the gcc command line
(for linking) when this package is being used.

For examples of more package specifications, take a look
at the package.conf in your GHC
installation.