</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>packages</primary>
<secondary>using</secondary></indexterm>
- <para>To see which packages are installed, use the
- <literal>ghc-pkg</literal> command:</para>
+ <para>GHC only knows about packages that are
+ <emphasis>installed</emphasis>. To see which packages are installed, use
+ the <literal>ghc-pkg</literal> command:</para>
<screen>
$ ghc-pkg list
(hssource-1.0), rts-1.0
</screen>
- <para>Packages are either exposed or hidden. Only
- modules from exposed packages may be imported by your Haskell code; if
+ <para>An installed package is either <emphasis>exposed</emphasis> or <emphasis>hidden</emphasis>
+ by default. Packages hidden by default are listed in
+ parentheses (eg. <literal>(lang-1.0)</literal>) in the output above. Command-line flags, described below, allow you to expose a hidden package
+ or hide an exposed one.
+ Only modules from exposed packages may be imported by your Haskell code; if
you try to import a module from a hidden package, GHC will emit an error
message.</para>
- <para>Each package has an exposed flag, which says whether it is exposed by
- default or not. Packages hidden by default are listed in
- parentheses (eg. <literal>(lang-1.0)</literal>) in the output from
- <literal>ghc-pkg list</literal>. To expose a package which is hidden by
- default, use the <option>-package</option>
- flag (see below).</para>
-
- <para>To see which modules are exposed by a package:</para>
+ <para>To see which modules are provided by a package use the
+ <literal>ghc-pkg</literal> command (see <xref linkend="package-management"/>):</para>
<screen>
$ ghc-pkg field network exposed-modules
Network
</screen>
- <para>In general, packages containing hierarchical modules are usually
- exposed by default. However, it is possible for two packages to contain
- the same module: in this case, only one of the packages should be
- exposed. It is an error to import a module that belongs to more than one
- exposed package.</para>
-
<para>The GHC command line options that control packages are:</para>
<variablelist>
<indexterm><primary><option>-package</option></primary></indexterm>
</term>
<listitem>
- <para>This option causes 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>
<literal>base</literal>) need to be explicitly exposed using
<option>-package</option> options.</para>
- <para>This is a good way to insulate your program from differences
- in the globally exposed packages, and being explicit about package
- dependencies is a Good Thing.</para>
+ <para>This is a good way to insulate your program from
+ differences in the globally exposed packages, and being
+ explicit about package dependencies is a Good Thing.
+ Cabal always passes the
+ <option>-hide-all-packages</option> flag to GHC, for
+ exactly this reason.</para>
</listitem>
</varlistentry>
useful.</para>
</listitem>
</varlistentry>
+
+ <varlistentry>
+ <term><option>-package-name</option> <replaceable>foo</replaceable>
+ <indexterm><primary><option>-package-name</option></primary>
+ </indexterm></term>
+ <listitem>
+ <para>Tells GHC the the module being compiled forms part of
+ package <replaceable>foo</replaceable>.
+ If this flag is omitted (a very common case) then the
+ default package <literal>main</literal> is assumed.</para>
+ <para>Note: the argument to <option>-package-name</option>
+ should be the full package identifier for the package,
+ that is it should include the version number. For example:
+ <literal>-package mypkg-1.2</literal>.</para>
+ </listitem>
+ </varlistentry>
</variablelist>
</sect2>
+ <sect2 id="package-main">
+ <title>The main package</title>
+
+ <para>Every complete Haskell program must define <literal>main</literal> in
+ module <literal>Main</literal>
+ in package <literal>main</literal>. (Omitting the <option>-package-name</option> flag compiles
+ code for package <literal>main</literal>.) Failure to do so leads to a somewhat obscure
+ link-time error of the form:
+<programlisting>
+/usr/bin/ld: Undefined symbols:
+_ZCMain_main_closure
+___stginit_ZCMain
+</programlisting>
+</para>
+
+ </sect2>
+
<sect2 id="package-overlaps">
- <title>The module overlap restriction</title>
-
- <para>The module names in a Haskell program must be distinct.
- This doesn't sound like a severe restriction, but in a Haskell program
- using multiple packages with interdependencies, difficulties can start to
- arise. You should be aware of what the module overlap
- restriction means, and how to avoid it.</para>
-
- <para>GHC knows which packages are <emphasis>in use</emphasis> by your
- program: a package is in use if you imported something from it, or if it
- is a dependency of some other package in use. There must be no conflicts
- between the packages in use; a conflict is when two packages contain
- a module with the same name. If
- GHC detects a conflict, it will issue a message stating which packages
- are in conflict, and which modules are overlapping.</para>
-
- <para>For example, a conflict might arise if you use two packages, say P
- and Q, which respectively depend on two different versions of another
- package, say <literal>R-1.0</literal> and <literal>R-2.0</literal>. The
- two versions of <literal>R</literal> are likely to contain at least some
- of the same modules, so this situation would be a conflict.</para>
+ <title>Consequences of packages</title>
+
+ <para>It is possible that by using packages you might end up with
+ a program that contains two modules with the same name: perhaps
+ you used a package P that has a <emphasis>hidden</emphasis> module
+ M, and there is also a module M in your program. Or perhaps the
+ dependencies of packages that you used contain some overlapping
+ modules. Perhaps the program even contains multiple versions of a
+ certain package, due to dependencies from other packages.</para>
+
+ <para>None of these scenarios gives rise to an error on its
+ own<footnote><para>it used to in GHC 6.4, but not since
+ 6.6</para></footnote>, but they may have some interesting
+ consequences. For instance, if you have a type
+ <literal>M.T</literal> from version 1 of package
+ <literal>P</literal>, then this is <emphasis>not</emphasis> the
+ same as the type <literal>M.T</literal> from version 2 of package
+ <literal>P</literal>, and GHC will report an error if you try to
+ use one where the other is expected.</para>
+
+ <para>Formally speaking, in Haskell 98, an entity (function, type
+ or class) in a program is uniquely identified by the pair of the
+ module name in which it is defined and its name. In GHC, an
+ entity is uniquely defined by a triple: package, module, and
+ name.</para>
</sect2>
<sect2 id="package-databases">
database will override those of the same name in the global
database.</para>
- <para>You can control the loading of package databses using the following
+ <para>You can control the loading of package databases using the following
GHC options:</para>
<variablelist>
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>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>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
+ you will only discover later when you attempt to import modules
+ from the package. At this point GHC will complain that the
+ package name it was expecting the module to come from is not the
+ same as the package name stored in the <literal>.hi</literal>
+ file.</para>
+
+ <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>
+ <filename>main</filename> package as well.</para>
</sect2>
<sect2 id="package-management">
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