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>
<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 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>
</varlistentry>
</variablelist>
+ <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<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:</para>
+
+<screen>$ ghc -o myprog Foo.o Main.o -package network</screen>
+
<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
automatically get <literal>-package lang</literal> too.</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">
<title>Building a package from Haskell source</title>
<indexterm><primary>packages</primary>
<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> (the object suffix
- varies between platforms, as usual) and load that. An
- object file can be built from a <literal>.a</literal>
- archive as follows (using GNU <command>ld</command> on
- Unix):</para>
-
-<screen>
-ld -r --whole-archive -o HSfoo.o libHSfoo.a
-</screen>
+ 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>
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-packages-local</option></term>
+ <term><option>-L</option></term>
+ <indexterm><primary><option>––list-packages-local</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
<varlistentry>
<term><filename>libHSfoo.a</filename></term>
<listitem>
- <para>The name of the library on Unix
+ <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>
<term><filename>HSfoo.dll</filename></term>
<listitem>
<para>The name of the dynamic library on Windows
- systems.</para>
+ systems (optional).</para>
</listitem>
</varlistentry>
<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 after the
<literal>hs_libraries</literal> for the same package. If
<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