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 to or removed
+ <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
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>
+<screen>ld -r ––whole-archive -o HSfoo.o libHSfoo.a</screen>
</listitem>
<listitem>
<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>
+ 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>
<variablelist>
<varlistentry>
- <term><option>--add-package</option></term>
+ <term><option>––add-package</option></term>
<term><option>-a</option></term>
- <indexterm><primary><option>--add-package</option></primary>
- </indexterm>
+ <indexterm><primary><option>––add-package</option></primary></indexterm>
<listitem>
- <para>Reads a package specification (see below) on stdin,
+ <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>
</varlistentry>
<varlistentry>
- <term><option>--auto-ghci-libs</option></term>
+ <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><primary><option>––auto-ghci-libs</option></primary>
</indexterm>
<listitem>
<para>Automatically generate the GHCi
</varlistentry>
<varlistentry>
- <term><option>--config-file <replaceable>file</replaceable></option></term>
+ <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><primary><option>––config-file</option></primary>
</indexterm>
<listitem>
<para>Use <replaceable>file</replaceable> instead of the
</varlistentry>
<varlistentry>
- <term><option>--list-packages</option></term>
+ <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>
<screen>
- $ ghc-pkg --list-packages
+ $ ghc-pkg ––list-packages
gmp, rts, std, lang, concurrent, data, net, posix, text, util
</screen>
</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>When modifying the configuration file
<screen>
Package {
name = "mypkg",
- import_dirs = ["/usr/local/lib/imports/mypkg"],
+ 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>
(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