<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
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>Consequences of packages</title>
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>
</itemizedlist>
<para>To compile a module which is to be part of a new package,
- use the <literal>-package-name</literal> option:</para>
-
- <variablelist>
- <varlistentry>
- <term><option>-package-name <replaceable>foo</replaceable></option>
- <indexterm><primary><literal>-package-name</literal></primary>
- <secondary>option</secondary></indexterm></term>
- <listitem>
- <para>This option is added to the command line when
- compiling a module that is destined to be part of package
- <literal>foo</literal>. If this flag is omitted 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>
-
- <para>Failure to use the <literal>-package-name</literal> option
+ 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