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 the accompanying
library documentation), 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. base)The Haskell code in a package may be built into one or
more archive libraries
(e.g. libHSfoo.a), or a single DLL on
Windows (e.g. HSfoo.dll). The
restriction to a single DLL on Windows is because 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.Building a static library is done by using the
ar tool, like so:ar cqs libHSfoo.a A.o B.o C.o ...where A.o,
B.o and so on are the compiled Haskell
modules, and libHSfoo.a is the library
you wish to create. The syntax may differ slightly on your
system, so check the documentation if you run into
difficulties.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 and load that. On some
systems, the ghc-pkg tool can
automatically build the GHCi version of each library, see
. To build these
libraries by hand from the .a archive, it
is possible to use GNU ld as
follows:ld -r ––whole-archive -o HSfoo.o libHSfoo.aGHC 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, updated 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 package specification from the input (see below),
and adds it to the database of installed packages. The
package specification must be a package that isn't already
installed.Read new package specifications from file
file. If a value of
"-" is given, standard input is used.
If no is present on the command-line,
an input file of "-" is assumed.
Automatically generate the GHCi
.o version of each
.a Haskell library, using GNU ld (if
that is available). Without this option,
ghc-pkg will warn if GHCi versions of
any Haskell libraries in the package don't exist.GHCi .o libraries don't
necessarily have to live in the same directory as the
corresponding .a library. However,
this option will cause the GHCi library to be created in
the same directory as the .a
library.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.Reads package specification from the input, and
adds it to the database of installed packages. If a package
with the same name is already installed, its configuration
data is replaced with the new information. If the package
doesn't already exist, it's added.
Causes ghc-pkg to ignore missing
directories and libraries when adding a package, and just
go ahead and add it anyway. This might be useful if your
package installation system needs to add the package to
GHC before building and installing the files.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 = ["${installdir}/imports/mypkg"],
source_dirs = [],
library_dirs = ["${installdir}"],
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.If the package contains profiling libraries, then
the interface files for those library modules should have
the suffix .p_hi. So the package can
contain both normal and profiling versions of the same
library without conflict (see also
library_dirs below).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 and Windows
(mingw) systems. Note that we don't support
building dynamic libraries of Haskell code on Unix
systems.HSfoo.dllThe name of the dynamic library on Windows
systems (optional).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.The libraries listed in
extra_libraries may be any libraries
supported by your system's linker, including dynamic
libraries (.so on Unix,
.DLL on Windows).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.framework_dirsframework_dirspackage specificationOn Darwin/MacOS X, a list of directories containing frameworks for this
package. This corresponds to the option.
It is ignored on all other platforms.extra_frameworksextra_frameworkspackage specificationOn Darwin/MacOS X, a list of frameworks to link to. This corresponds to the
option. Take a look at Apple's developer documentation
to find out what frameworks actually are. This entry is ignored on all other platforms.
The ghc-pkg tool performs expansion of
environment variables occurring in input package specifications.
So, if the mypkg was added to the package
database as follows:
$ installdir=/usr/local/lib ghc-pkg -a < mypkg.pkg
The occurrence of ${installdir} is replaced
with /usr/local/lib in the package data that
is added for mypkg.
This feature enables the distribution of package specification
files that can be easily configured when installing.
For examples of more package specifications, take a look
at the package.conf in your GHC
installation.