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.</para>
-
- <sect2 id="listing-packages">
- <title>Listing the available packages</title>
- <indexterm><primary>packages</primary>
- <secondary>listing</secondary></indexterm>
-
- <para>To see what packages are currently installed, use the
- <literal>--list-packages</literal> option:</para>
- <indexterm><primary><literal>--list-packages</literal></primary>
- </indexterm>
-
-<screen>
- $ ghc --list-packages
- gmp, rts, std, lang, concurrent, data, net, posix, text, util
-</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.
- The rest of the packages are optional libraries.</para>
-
- </sect2>
+ linkend="book-hslibs">), 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>
<sect2 id="using-packages">
<title>Using a package</title>
<secondary>using</secondary></indexterm>
<para>To use a package, add the <literal>-package</literal> flag
- to the command line:</para>
+ to the GHC command line:</para>
<variablelist>
<varlistentry>
- <term><option>-package <lib></option></term>
- <indexterm><primary>-package <lib> option</primary></indexterm>
+ <term><option>-package <replaceable>lib</replaceable></option></term>
+ <indexterm><primary>-package <replaceable>lib</replaceable> option</primary></indexterm>
<listitem>
<para>This option brings into scope all the modules from
- package <literal><lib></literal> (they still have to
+ package <literal><replaceable>lib</replaceable></literal> (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.</para>
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>The Haskell code in a package may be built into one or
- more Unix libraries (e.g. <filename>libHSfoo.a</filename>),
+ 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 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>
+ 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>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. 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>
<variablelist>
<varlistentry>
- <term><option>-package-name <foo></option></term>
+ <term><option>-package-name <replaceable>foo</replaceable></option></term>
<indexterm><primary><literal>-package-name</literal></primary>
<secondary>option</secondary></indexterm>
<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>
-
</sect2>
+
<sect2 id="package-management">
<title>Package management</title>
<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 GHC provides options for adding & removing
- packages:</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 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>--add-package</option></term>
- <indexterm><primary><literal>--add-package</literal></primary>
- <secondary>option</secondary></indexterm>
+ <term><option>-a</option></term>
+ <indexterm><primary><option>--add-package</option></primary>
+ </indexterm>
<listitem>
<para>Reads a package specification (see below) on stdin,
and adds it to the database of installed packages. The
</varlistentry>
<varlistentry>
- <term><option>--delete-package <foo></option></term>
- <indexterm><primary><literal>--delete-package</literal></primary>
- <secondary>option</secondary></indexterm>
+ <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> instead of the
+ default package configuration file. This, in conjunction
+ with GHC's <option>-package-conf</option> option, allows
+ a user to have a local set of packages in addition to the
+ system-wide installed set.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--list-packages</option></term>
+ <term><option>-l</option></term>
+ <indexterm><primary><option>--list-packages</option></primary></indexterm>
+ <listitem>
+ <para>This option displays the list of currently installed
+ packages.</para>
+
+<screen>
+ $ ghc-pkg --list-packages
+ gmp, rts, std, lang, concurrent, data, net, posix, text, util
+</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>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <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>
<listitem>
<para>Removes the specified package from the installed
configuration.</para>
</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>
Package {
name = "mypkg",
import_dirs = ["/usr/local/lib/imports/mypkg"],
+ source_dirs = [],
library_dirs = ["/usr/local/lib"],
hs_libraries = ["HSmypkg" ],
extra_libraries = ["HSmypkg_cbits"],
</varlistentry>
<varlistentry>
+ <term><literal>source_dirs</literal></term>
+ <indexterm><primary><literal>source_dirs</literal></primary>
+ <secondary>package specification</secondary></indexterm>
+ <listitem>
+ <para>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.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
<term><literal>library_dirs</literal></term>
<indexterm><primary><literal>library_dirs</literal></primary>
<secondary>package specification</secondary></indexterm>
<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
+ systems.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><filename>HSfoo.dll</filename></term>
+ <listitem>
+ <para>The name of the dynamic library on Windows
+ systems.</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>
<literal>extra_libraries</literal>.</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>
projects / ghc-hetmet.git / blobdiff