PackagespackagesPackages 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 ), and packages can be added to or removed
from an existing GHC installation, using the supplied
ghc-pkgghc-pkg tool, described in .Using a packagepackagesusingTo use a package, add the -package flag
to the GHC command line:-package lib optionThis 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.Maintaining a local set of packagesWhen 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 option: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 .Building a package from Haskell sourcepackagesbuildingIt takes some special considerations to build a new
package: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 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-nameoptionThis 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.Package managementpackagesmanagementThe 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
option. An empty package configuration file consists of the
string [].The ghc-pkg program accepts the
following options: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.Use file instead of the
default package configuration file. This, in conjunction
with GHC's option, allows
a user to have a local set of packages in addition to the
system-wide installed set.This option displays the list of currently installed
packages.
$ ghc-pkg --list-packages
gmp, rts, std, lang, concurrent, data, net, posix, text, util
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.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.A package specification looks like this:
Package {
name = "mypkg",
import_dirs = ["/usr/local/lib/imports/mypkg"],
source_dirs = [],
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"]
}
Components of a package specification may be specified in
any order, and are:namenamepackage specificationThe package's name, for use with
the -package flag and as listed in the
--list-packages list.
import_dirsimport_dirspackage specificationA list of directories containing interface files
(.hi files) for this package.source_dirssource_dirspackage specificationA 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_dirslibrary_dirspackage specificationA list of directories containing libraries for this
package.hs_librarieshs_librariespackage specificationA 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.aThe name of the library on Unix
systems.HSfoo.dllThe name of the dynamic library on Windows
systems.HSfoo.oHSfoo.objThe object version of the library used by
GHCi.extra_librariesextra_librariespackage specificationA 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_dirsinclude_dirspackage specificationA list of directories containing C includes for this
package (maybe the empty list).c_includesc_includespackage specificationA 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_depspackage_depspackage specificationA list of packages which this package depends
on.extra_ghc_optsextra_ghc_optspackage specificationExtra arguments to be added to the GHC command line
when this package is being used.extra_cc_optsextra_cc_optspackage specificationExtra arguments to be added to the gcc command line
when this package is being used (only for via-C
compilations).extra_ld_optsextra_ld_optspackage specificationExtra 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.