</title>
<indexterm><primary>packages</primary></indexterm>
- <para>A package is a library of Haskell modules known to the compiler. GHC
- comes with several packages: see the accompanying
- <ulink url="../libraries/index.html">library documentation</ulink>.</para>
+ <para>A package is a library of Haskell modules known to the
+ compiler. GHC comes with several packages: see the accompanying
+ <ulink url="../libraries/index.html">library
+ documentation</ulink>. More packages to install can be obtained
+ from <ulink
+ url="http://hackage.haskell.org/packages/hackage.html">HackageDB</ulink>.</para>
<para>Using a package couldn't be simpler: if you're using
<option>--make</option> or GHCi, then most of the installed packages will be
<indexterm><primary><option>-package</option></primary></indexterm>
</term>
<listitem>
- <para>This option causes the installed package <replaceable>P</replaceable> to be
- exposed. The package <replaceable>P</replaceable> can be specified
- in full with its version number
- (e.g. <literal>network-1.0</literal>) or the version number can be
- omitted if there is only one version of the package
- installed.</para>
-
- <para>If there are multiple versions of <replaceable>P</replaceable>
- installed, then all other versions will become hidden.</para>
+ <para>This option causes the installed
+ package <replaceable>P</replaceable> to be exposed. The
+ package <replaceable>P</replaceable> can be specified in
+ full with its version number
+ (e.g. <literal>network-1.0</literal>) or the version
+ number can be omitted if there is only one version of the
+ package installed. If there are multiple versions
+ of <replaceable>P</replaceable> installed, then all other
+ versions will become hidden.</para>
<para>The <option>-package <replaceable>P</replaceable></option>
- option also causes package <replaceable>P</replaceable> to be
- linked into the resulting executable. In
- <option>––make</option> mode and GHCi, the compiler
- normally determines which packages are required by the current
- Haskell modules, and links only those. In batch mode however, the
- dependency information isn't available, and explicit
- <option>-package</option> options must be given when linking.</para>
+ option also causes package <replaceable>P</replaceable> to
+ be linked into the resulting executable or shared
+ object. Whether a packages' library is linked statically
+ or dynamically is controlled by the flag
+ pair <option>-static</option>/<option>-dynamic</option>.</para>
+
+ <para>In <option>––make</option> mode
+ and <option>––interactive</option> mode (see
+ <xref linkend="modes" />), the compiler normally
+ determines which packages are required by the current
+ Haskell modules, and links only those. In batch mode
+ however, the dependency information isn't available, and
+ explicit
+ <option>-package</option> options must be given when linking. The one other time you might need to use
+ <option>-package</option> to force linking a package is
+ when the package does not contain any Haskell modules (it
+ might contain a C library only, for example). In that
+ case, GHC will never discover a dependency on it, so it
+ has to be mentioned explicitly.</para>
<para>For example, to link a program consisting of objects
<filename>Foo.o</filename> and <filename>Main.o</filename>, where
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
- packages required for linking without further assistance.</para>
-
- <para>The one other time you might need to use
- <option>-package</option> to force linking a package is when the
- package does not contain any Haskell modules (it might contain a C
- library only, for example). In that case, GHC
- will never discover a dependency on it, so it has to be mentioned
- explicitly.</para>
+<screen>$ ghc -o myprog Foo.hs Main.hs -package network</screen></para>
</listitem>
</varlistentry>
lot of configuration, then you might have to fall back to the low-level
mechanisms, so a few hints for those brave souls follow.</para>
+ <para>You need to build an "installed package info" file for
+ passing to <literal>ghc-pkg</literal> when installing your
+ package. The contents of this file are described in
+ <xref linkend="installed-pkg-info" />.</para>
+
+ <para>The Haskell code in a package may be built into one or more
+ archive libraries (e.g. <filename>libHSfoo.a</filename>), or a
+ single shared object
+ (e.g. <filename>libHSfoo.dll/.so/.dylib</filename>). The
+ restriction to a single shared object is because the package
+ system is used to tell the compiler when it should make an
+ inter-shared-object call rather than an intra-shared-object-call
+ call (inter-shared-object calls require an extra
+ indirection).</para>
<itemizedlist>
- <listitem>
- <para>You need to build an "installed package info" file for
- passing to <literal>ghc-pkg</literal> when installing your
- package. The contents of this file are described in <xref
- linkend="installed-pkg-info" />.</para>
- </listitem>
-
- <listitem>
- <para>The Haskell code in a package may be built into one or
- 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
+ <listitem><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>
+<screen>ar cqs libHSfoo-1.0.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
+ <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>
+ </listitem>
+ <listitem>
+ <para>Versions of the Haskell libraries for use with GHCi may also
+ abe 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>
+ 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>
<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
- things within those imported things.</para>
+ <literal>––whole-archive</literal> with
+ <literal>–all_load</literal> on MacOS X)</para>
+ </listitem>
+ <listitem>
+ <para>When building the package as shared object, GHC wraps
+ out the underlying linker so that the user gets a common
+ interface to all shared object variants that are supported
+ by GHC (DLLs, ELF DSOs, and Mac OS dylibs). The shared
+ object must be named in specific way for two reasons: (1)
+ the name must contain the GHC compiler version, so that two
+ library variants don't collide that are compiled by
+ different versions of GHC and that therefore are most likely
+ incompatible with respect to calling conventions, (2) it
+ must be different from the static name otherwise we would
+ not be able to control the linker as precisely as necessary
+ to make
+ the <option>-static</option>/<option>-dynamic</option> flags
+ work, see <xref linkend="options-linker" />.</para>
+
+<screen>ghc -shared libHSfoo-1.0-ghc<replaceable>GHCVersion</replaceable>.so A.o B.o C.o</screen>
+ <para>Using GHC's version number in the shared object name
+ allows different library versions compiled by different GHC
+ versions to be installed in standard system locations,
+ e.g. under *nix /usr/lib. To obtain the version number of
+ GHC invoke <literal>ghc --numeric-version</literal> and use
+ its output in place
+ of <replaceable>GHCVersion</replaceable>. See also
+ <xref linkend="options-codegen" /> on how object files must
+ be prepared for shared object linking.</para>
</listitem>
</itemizedlist>
+
+ <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 things within
+ those imported things.</para>
- <para>To compile a module which is to be part of a new package,
+ <para>To compile a module which is to be part of a new package,
use the <literal>-package-name</literal> option (<xref linkend="using-packages"/>).
Failure to use the <literal>-package-name</literal> option
when compiling a package will probably result in disaster, but
same as the package name stored in the <literal>.hi</literal>
file.</para>
- <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
+ <para>It is worth noting with shared objects, when each package
+ is built as a single shared object file, since a reference to a shared object 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>
options are given, the rightmost one is used as the database to act
upon.</para>
+ <para>Commands that query the package database (list, latest,
+ describe, field) operate on the list of databases specified by
+ the flags <option>--user</option>, <option>--global</option>, and
+ <option>--package-conf</option>. If none of these flags are
+ given, the default is <option>--global</option>
+ <option>--user</option>.</para>
+
<para>If the environment variable <literal>GHC_PACKAGE_PATH</literal> is
set, and its value does not end in a separator (<literal>:</literal> on
Unix, <literal>;</literal> on Windows), then the last database is
</varlistentry>
<varlistentry>
+ <term><literal>ghc-pkg check</literal></term>
+ <listitem>
+ <para>Check consistency of dependencies in the package
+ database, and report packages that have missing
+ dependencies.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
<term><literal>ghc-pkg hide <replaceable>P</replaceable></literal></term>
<listitem>
<para>Sets the <literal>exposed</literal> flag for package
</varlistentry>
<varlistentry>
+ <term><literal>ghc-pkg find-module <replaceable>M</replaceable> [<option>--simple-output</option>]</literal></term>
+ <listitem>
+ <para>This option lists registered packages exposing module
+ <replaceable>M</replaceable>. Examples:</para>
+<screen>
+$ ghc-pkg find-module Var
+c:/fptools/validate/ghc/driver/package.conf.inplace:
+ (ghc-6.9.20080428)
+
+$ ghc-pkg find-module Data.Sequence
+c:/fptools/validate/ghc/driver/package.conf.inplace:
+ containers-0.1
+</screen>
+ <para>Otherwise, it behaves like <literal>ghc-pkg list</literal>,
+ including options.</para>
+ </listitem>
+ </varlistentry>
+
+
+ <varlistentry>
<term><literal>ghc-pkg latest <replaceable>P</replaceable></literal></term>
<listitem>
<para>Prints the latest available version of package
</varlistentry>
<varlistentry>
- <term><literal>ghc-pkg field <replaceable>P</replaceable> <replaceable>field</replaceable></literal></term>
+ <term><literal>ghc-pkg field <replaceable>P</replaceable> <replaceable>field</replaceable>[,<replaceable>field</replaceable>]*</literal></term>
<listitem>
<para>Show just a single field of the installed package description
- for <literal>P</literal>.</para>
+ for <literal>P</literal>. Multiple fields can be selected by separating
+ them with commas</para>
</listitem>
</varlistentry>
</variablelist>
+ <para>
+ Substring matching is supported for <replaceable>M</replaceable> in
+ <literal>find-module</literal> and for <replaceable>P</replaceable> in
+ <literal>list</literal>, <literal>describe</literal>, and
+ <literal>field</literal>, where a <literal>'*'</literal> indicates open
+ substring ends (<literal>prefix*</literal>, <literal>*suffix</literal>,
+ <literal>*infix*</literal>). Examples (output omitted):
+ </para>
+ <screen>
+ -- list all regex-related packages
+ ghc-pkg list '*regex*' --ignore-case
+ -- list all string-related packages
+ ghc-pkg list '*string*' --ignore-case
+ -- list OpenGL-related packages
+ ghc-pkg list '*gl*' --ignore-case
+ -- list packages exporting modules in the Data hierarchy
+ ghc-pkg find-module 'Data.*'
+ -- list packages exporting Monad modules
+ ghc-pkg find-module '*Monad*'
+ -- list names and maintainers for all packages
+ ghc-pkg field '*' name,maintainer
+ -- list location of haddock htmls for all packages
+ ghc-pkg field '*' haddock-html
+ -- dump the whole database
+ ghc-pkg describe '*'
+ </screen>
+
<para>Additionally, the following flags are accepted by
<literal>ghc-pkg</literal>:</para>
databases. Additionally, <replaceable>file</replaceable> will
also be the database modified by a <literal>register</literal>,
<literal>unregister</literal>, <literal>expose</literal> or
- <literal>hide</literal> command, unless it is overriden by a later
+ <literal>hide</literal> command, unless it is overridden by a later
<option>--package-conf</option>, <option>--user</option> or
<option>--global</option> option.</para>
</listitem>
projects / ghc-hetmet.git / blobdiff