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, using the supplied
+ <para>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
<literal>ghc-pkg</literal><indexterm><primary><literal>ghc-pkg</literal></primary>
</indexterm> tool, described in <xref
- linkend="package-management">.</para>
+ linkend="package-management"/>.</para>
<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 GHC command line:</para>
+ <para>Some packages, called <emphasis>auto packages</emphasis>,
+ 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.</para>
+
+ <para>Some other packages are <emphasis>not</emphasis>
+ automatically available: those are normally the packages
+ containing old non-hierarchical libraries. To gain access to a
+ non-auto package, use the <option>-package</option> command-line
+ flag:</para>
<variablelist>
<varlistentry>
be imported in your Haskell source, however). It also
causes the relevant libraries to be linked when linking is
being done.</para>
+ <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>
</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>
+ <para>There's one case where you need to use the
+ <option>-package</option> option even for auto packages: when
+ linking a program in batch mode mode (<xref linkend="options-order"/>)
+ <footnote><para>This is because
+ GHC can't figure out from the object files which packages are
+ required; in <option>––make</option> 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.</para></footnote>. For example, to link a
+ program consisting of objects <filename>Foo.o</filename> and
+ <filename>Main.o</filename>, where we made use of the
+ <literal>network</literal> package, we need to give GHC the <literal>-package</literal> flag thus:
+
+<screen>$ ghc -o myprog Foo.o Main.o -package network</screen>
+
+ The same flag is necessary even if we compiled the modules from source, because GHC still
+ reckons it's in batch mode:
+<screen>$ ghc -o myprog Foo.hs Main.hs -package network</screen>
+In <literal>--make</literal> and <literal>--interactive</literal> modes (<xref linkend="modes"/>), however, GHC figures out
+the auto packages required for linking without further assistance.
+</para>
+
+ </sect2>
+
+
+ <sect2 id="using-local-packages">
+ <title>Maintaining a local set of packages</title>
+
+ <para>When GHC starts up, it automatically reads the default set
+ of packages from a configuration file, normally named
+ <filename>package.conf</filename> in your GHC installation
+ directory.</para>
+
+ <para>You can load in additional package configuration files
+ using the <option>-package-conf</option> option:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><option>-package-conf <replaceable>file</replaceable></option></term>
+ <indexterm><primary><option>-package-conf <replaceable>file</replaceable></option></primary>
+ </indexterm>
+ <listitem>
+ <para>Read in the package configuration file
+ <replaceable>file</replaceable> 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.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>To create your own package configuration file, just create
+ a new file and put the string
+ <quote><literal>[]</literal></quote> in it. Packages can be
+ added to the new configuration file using the
+ <literal>ghc-pkg</literal> tool, described in <xref
+ linkend="package-management"/>.</para>
</sect2>
<sect2 id="building-packages">
<listitem>
<para>A package has a name
- (e.g. <filename>std</filename>)</para>
+ (e.g. <filename>base</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>
+ more archive 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 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). <emphasis>Building packages as DLLs doesn't
+ work at the moment; see <xref linkend="win32-dlls-create"/>
+ for the gory details.</emphasis>
+ </para>
+
+ <para>Building a static library is done by using the
+ <literal>ar</literal> tool, like so:</para>
+
+<screen>ar cqs libHSfoo.a A.o B.o C.o ...</screen>
+
+ <para>where <filename>A.o</filename>,
+ <filename>B.o</filename> and so on are the compiled Haskell
+ modules, and <filename>libHSfoo.a</filename> is the library
+ you wish to create. The syntax may differ slightly on your
+ system, so check the documentation if you run into
+ difficulties.</para>
+
+ <para>Versions of the Haskell libraries for use with GHCi
+ may also be included: GHCi cannot load <literal>.a</literal>
+ files directly, instead it will look for an object file
+ called <filename>HSfoo.o</filename> and load that. On some
+ systems, the <literal>ghc-pkg</literal> tool can
+ automatically build the GHCi version of each library, see
+ <xref linkend="package-management"/>. To build these
+ libraries by hand from the <literal>.a</literal> archive, it
+ is possible to use GNU <command>ld</command> as
+ follows:</para>
+
+<screen>ld -r ––whole-archive -o HSfoo.o libHSfoo.a</screen>
</listitem>
<listitem>
+ <para>(replace
+ <literal>––--whole-archive</literal> with
+ <literal>–all_load</literal> on MacOS X)</para>
+
<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
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
+ <para>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
<filename>Main</filename> package as well.</para>
<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 packages can be added or removed using GHC's
- package management tool, <literal>ghc-pkg</literal>.</para>
+ <para>The <literal>ghc-pkg</literal> 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>––config-file</option>
+ option. An empty package configuration file consists of the
+ string <quote><literal>[]</literal></quote>.</para>
+
+ <para>The <literal>ghc-pkg</literal> program accepts the
+ following options:</para>
<variablelist>
<varlistentry>
- <term><option>--list-packages</option></term>
+ <term><option>––add-package</option></term>
+ <term><option>-a</option></term>
+ <indexterm><primary><option>––add-package</option></primary></indexterm>
+ <listitem>
+ <para>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.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>––input-file=<replaceable>file</replaceable></option></term>
+ <term><option>-i <replaceable>file</replaceable></option></term>
+ <indexterm><primary><option>––input-file</option></primary></indexterm>
+ <listitem>
+ <para>Read new package specifications from file
+ <replaceable>file</replaceable>. If a value of
+ <filename>"-"</filename> is given, standard input is used.
+ If no <option>-i</option> is present on the command-line,
+ an input file of <filename>"-"</filename> is assumed.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>––auto-ghci-libs</option></term>
+ <term><option>-g</option></term>
+ <indexterm><primary><option>––auto-ghci-libs</option></primary>
+ </indexterm>
+ <listitem>
+ <para>Automatically generate the GHCi
+ <filename>.o</filename> version of each
+ <filename>.a</filename> Haskell library, using GNU ld (if
+ that is available). Without this option,
+ <literal>ghc-pkg</literal> will warn if GHCi versions of
+ any Haskell libraries in the package don't exist.</para>
+
+ <para>GHCi <literal>.o</literal> libraries don't
+ necessarily have to live in the same directory as the
+ corresponding <literal>.a</literal> library. However,
+ this option will cause the GHCi library to be created in
+ the same directory as the <literal>.a</literal>
+ library.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>––config-file <replaceable>file</replaceable></option></term>
+ <term><option>-f <replaceable>file</replaceable></option></term>
+ <indexterm><primary><option>––config-file</option></primary>
+ </indexterm>
+ <listitem>
+ <para>Use <replaceable>file</replaceable> as an additional
+ package configuration file. This is used to modify
+ configuration files for use with GHC's
+ <option>-package-conf</option> option.</para>
+
+ <para>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
+ <emphasis>last</emphasis> configuration file mentioned on
+ the command-line is the only one that is actually modified
+ by <literal>ghc-pkg</literal>.</para>
+
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>––list-packages</option></term>
<term><option>-l</option></term>
- <indexterm><primary><option>--list-packages</option></primary></indexterm>
+ <indexterm><primary><option>––list-packages</option></primary></indexterm>
<listitem>
<para>This option displays the list of currently installed
- packages.</para>
+ packages, including those in extra configuration files
+ specified with the <option>––config-file</option>
+ option.</para>
<screen>
- $ ghc-pkg --list-packages
- gmp, rts, std, lang, concurrent, data, net, posix, text, util
+ $ 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
</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 and standard
- libraries. The rest of the packages are optional
- libraries.</para>
+ <para>The <literal>rts</literal> package is always
+ present, and represents the runtime system library. The
+ <literal>base</literal> package contains the Haskell
+ prelude and basic hierarchical libraries, and the
+ <literal>haskell98</literal> package contains the Haskell
+ 98 standard libraries. The rest of the packages are
+ optional libraries.</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><option>--add-package</option></term>
- <term><option>-a</option></term>
- <indexterm><primary><option>--add-package</option></primary>
- </indexterm>
+ <term><option>––list-local-packages</option></term>
+ <term><option>-L</option></term>
+ <indexterm><primary><option>––list-local-packages</option></primary></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>
+ <para>Displays the list of packages installed in the
+ topmost configuration file only: that will be the
+ configuration file specified using <option>-f</option> on
+ the command line, or the system configuration file
+ otherwise.</para>
+
+ <para>This option may be more convenient than
+ <option>-l</option> when the output needs to be parsed by
+ a script.</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><option>--remove-package <replaceable>foo</replaceable></option></term>
+ <term><option>––remove-package <replaceable>foo</replaceable></option></term>
<term><option>-r <replaceable>foo</replaceable></option></term>
- <indexterm><primary><option>--delete-package</option></primary>
+ <indexterm><primary><option>––delete-package</option></primary>
</indexterm>
<listitem>
<para>Removes the specified package from the installed
configuration.</para>
</listitem>
</varlistentry>
+ <varlistentry>
+ <term><option>––update-package</option></term>
+ <term><option>-u</option></term>
+ <indexterm><primary><option>––update-package</option></primary></indexterm>
+ <listitem>
+ <para>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.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>––force</option></term>
+ <indexterm><primary><option>––force</option></primary></indexterm>
+ <listitem>
+ <para>Causes <literal>ghc-pkg</literal> 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.</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>When modifying the configuration file
+ <replaceable>file</replaceable>, a copy of the original file is
+ saved in <replaceable>file</replaceable><literal>.old</literal>,
+ so in an emergency you can always restore the old settings by
+ copying the old file back again.</para>
<para>A package specification looks like this:</para>
<screen>
Package {
name = "mypkg",
- import_dirs = ["/usr/local/lib/imports/mypkg"],
+ auto = True,
+ import_dirs = ["${installdir}/imports/mypkg"],
source_dirs = [],
- library_dirs = ["/usr/local/lib"],
+ library_dirs = ["${installdir}"],
hs_libraries = ["HSmypkg" ],
extra_libraries = ["HSmypkg_cbits"],
include_dirs = [],
<listitem>
<para>The package's name, for use with
the <literal>-package</literal> flag and as listed in the
- <literal>--list-packages</literal> list.
+ <literal>––list-packages</literal> list.
</para>
</listitem>
</varlistentry>
<varlistentry>
+ <term><literal>auto</literal></term>
+ <indexterm><primary><literal>auto</literal></primary>
+ <secondary>package specification</secondary>
+ </indexterm>
+ <listitem>
+ <para>Set to <literal>True</literal> if the package should
+ be automatically available (see <xref
+ linkend="using-packages"/>). This is normally set to
+ <literal>True</literal> for packages which contain
+ hierarchical libraries, because in that case there is no
+ danger of polluting the module namespace.</para>
+ </listitem>
+ </varlistentry>
+
+ <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>
+
+ <para>If the package contains profiling libraries, then
+ the interface files for those library modules should have
+ the suffix <literal>.p_hi</literal>. So the package can
+ contain both normal and profiling versions of the same
+ library without conflict (see also
+ <literal>library_dirs</literal> below).</para>
</listitem>
</varlistentry>
<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>.dll</literal> suffix omitted. When packages are
+ built as libraries, the
<literal>lib</literal> prefix is also omitted.</para>
+
+ <para>For use with GHCi, each library should have an
+ object file too. The name of the object file does
+ <emphasis>not</emphasis> have a <literal>lib</literal>
+ prefix, and has the normal object suffix for your
+ platform.</para>
+
+ <para>For example, if we specify a Haskell library as
+ <filename>HSfoo</filename> in the package spec, then the
+ various flavours of library that GHC actually uses will be
+ called:</para>
+ <variablelist>
+ <varlistentry>
+ <term><filename>libHSfoo.a</filename></term>
+ <listitem>
+ <para>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.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><filename>HSfoo.dll</filename></term>
+ <listitem>
+ <para>The name of the dynamic library on Windows
+ systems (optional).</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><filename>HSfoo.o</filename></term>
+ <term><filename>HSfoo.obj</filename></term>
+ <listitem>
+ <para>The object version of the library used by
+ GHCi.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
</listitem>
</varlistentry>
for libraries in
<literal>extra_libraries</literal>.</para>
+ <para>The libraries listed in
+ <literal>extra_libraries</literal> may be any libraries
+ supported by your system's linker, including dynamic
+ libraries (<literal>.so</literal> on Unix,
+ <literal>.DLL</literal> on Windows).</para>
+
<para>Also, <literal>extra_libraries</literal> are placed
- on the linker command line before the
+ on the linker command line after 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>
+ your package has dependencies in the other direction (i.e.
+ <literal>extra_libraries</literal> depends on
+ <literal>hs_libraries</literal>), and the libraries are
+ static, you might need to make two separate
+ packages.</para>
</listitem>
</varlistentry>
<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>
+ <para>Extra arguments to be added to the
+ <command>gcc</command> command line (for linking) when
+ this package is being used.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>framework_dirs</literal></term>
+ <indexterm><primary><literal>framework_dirs</literal></primary>
+ <secondary>package specification</secondary></indexterm>
+ <listitem>
+ <para>On Darwin/MacOS X, a list of directories containing frameworks for this
+ package. This corresponds to the <option>-framework-path</option> option.
+ It is ignored on all other platforms.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>extra_frameworks</literal></term>
+ <indexterm><primary><literal>extra_frameworks</literal></primary>
+ <secondary>package specification</secondary></indexterm>
+ <listitem>
+ <para>On Darwin/MacOS X, a list of frameworks to link to. This corresponds to the
+ <option>-framework</option> option. Take a look at Apple's developer documentation
+ to find out what frameworks actually are. This entry is ignored on all other platforms.</para>
</listitem>
</varlistentry>
</variablelist>
+
+ <para>
+ The <literal>ghc-pkg</literal> tool performs expansion of
+ environment variables occurring in input package specifications.
+ So, if the <literal>mypkg</literal> was added to the package
+ database as follows:
+ </para>
+<screen>
+ $ installdir=/usr/local/lib ghc-pkg -a < mypkg.pkg
+</screen>
+
+ <para>
+ The occurrence of <literal>${installdir}</literal> is replaced
+ with <literal>/usr/local/lib</literal> in the package data that
+ is added for <literal>mypkg</literal>.
+ </para>
+
+ <para>
+ This feature enables the distribution of package specification
+ files that can be easily configured when installing.
+ </para>
<para>For examples of more package specifications, take a look
at the <literal>package.conf</literal> in your GHC
projects / ghc-hetmet.git / blobdiff