</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
+ <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
<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>
</listitem>
</itemizedlist>
+ <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 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>
+ <filename>main</filename> package as well.</para>
</sect2>
<sect2 id="package-management">
projects / ghc-hetmet.git / blobdiff