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>
<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>
+ linkend="package-management"/>.</para>
</sect2>
<sect2 id="building-packages">
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">
+ work at the moment; see <xref linkend="win32-dlls-create"/>
for the gory details.</emphasis>
</para>
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
+ <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>
</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
<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>
+ <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>
<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
+ /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>––list-local-packages</option></term>
+ <term><option>-L</option></term>
+ <indexterm><primary><option>––list-local-packages</option></primary></indexterm>
+ <listitem>
+ <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>
<screen>
Package {
name = "mypkg",
+ auto = True,
import_dirs = ["${installdir}/imports/mypkg"],
source_dirs = [],
library_dirs = ["${installdir}"],
</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>
database as follows:
</para>
<screen>
- $ installdir=/usr/local/lib ghc-pkg -a < mypkg.pkg
+ $ installdir=/usr/local/lib ghc-pkg -a < mypkg.pkg
</screen>
<para>
projects / ghc-hetmet.git / blobdiff