The Glasgow Haskell Compiler User's Guide, Version 6.2
Prev | Chapter 4. Using GHC | Next

# 4.8. Packages

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 the accompanying library documentation), and packages can be added to or removed from an existing GHC installation, using the supplied `ghc-pkg` tool, described in Section 4.8.4.

## 4.8.1. Using a package

Some packages are automatically available: you don't need to specify any extra flags to use them (except in certain circumstances; see below). All the packages which contain hierarchical libraries fall into this category.

Some other packages are not automatically available: those are normally the packages containing old non-hierarchical libraries. To gain access to a non-auto package, use the `-package` command-line flag:

`-package `lib``

  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.

There's one case where you need to use the `-package` option even for auto packages: when linking a program in batch mode[1]. For example, to link a program consisting of objects `Foo.o` and `Main.o`, where we made use of the `network` package:

    $ ghc -o myprog Foo.o Main.o -package network

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.

## 4.8.2. Maintaining a local set of packages

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

## 4.8.3. Building a package from Haskell source

It 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 Section 11.5.3 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 Section 4.8.4. 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.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.

## 4.8.4. Package management

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, updated 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 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.

`––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.

`––auto-ghci-libs`, `-g`

  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.

`––config-file `file``, `-f `file``

  Use `file` as an additional package configuration file. This is used to modify configuration files for use with GHC's `-package-conf` option.

  There may be any number of configuration files named on the command line; files mentioned later on the command-line override those mentioned earlier. The last configuration file mentioned on the command-line is the only one that is actually modified by `ghc-pkg`.

`––list-packages`, `-l`

  This option displays the list of currently installed packages, including those in extra configuration files specified with the `––config-file` option.

        $ ghc-pkg ––list-packages
        /usr/local/lib/ghc-5.05/package.conf:
          hdirect, readline, lang, concurrent, posix, util, data, text, net,
          hssource, rts, haskell98, network, haskell-src, unix, base

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

  The `rts` package is always present, and represents the runtime system library. The `base` package contains the Haskell prelude and basic hierarchical libraries, and the `haskell98` package contains the Haskell 98 standard libraries. The rest of the packages are optional libraries.

`––list-local-packages`, `-L`

  Displays the list of packages installed in the topmost configuration file only: that will be the configuration file specified using `-f` on the command line, or the system configuration file otherwise.

  This option may be more convenient than `-l` when the output needs to be parsed by a script.

`––remove-package `foo``, `-r `foo``

  Removes the specified package from the installed configuration.

`––update-package`, `-u`

  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.

`––force`

  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",
         auto            = True,
         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:

`name`

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

`auto`

  Set to `True` if the package should be automatically available (see Section 4.8.1). This is normally set to `True` for packages which contain hierarchical libraries, because in that case there is no danger of polluting the module namespace.

`import_dirs`

  A 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_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 and Windows (mingw) systems. Note that we don't support building dynamic libraries of Haskell code on Unix systems.

  `HSfoo.dll`

    The name of the dynamic library on Windows systems (optional).

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

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

`framework_dirs`

  On Darwin/MacOS X, a list of directories containing frameworks for this package. This corresponds to the `-framework-path` option. It is ignored on all other platforms.

`extra_frameworks`

  On Darwin/MacOS X, a list of frameworks to link to. This corresponds to the `-framework` 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.

### Notes

[1] | This is because GHC can't figure out from the object files which packages are required; in `––make` mode and in GHCi the compiler has more information available to figure out the package dependencies. We might try to lift this restriction in the future.

Prev | Home | Next
Warnings and sanity-checking | Up | Optimisation (code improvement)