Commit 359313f8 authored by simonmar's avatar simonmar
Browse files

[project @ 2005-06-21 12:03:25 by simonmar]

Document changes to the package system.

A nice side effect of the relaxed restrictions is that the
-ignore-package flag is no longer required when compiling a package
(unless the package is "base", and even in that case we might be able
to get away with -hide-package base).  For now, I've removed
references that talk about using -ignore-package when compiling a
package, and simplified the documentation for -ignore-package.
parent b9a1ac09
......@@ -69,13 +69,9 @@ exposed-modules: Network.BSD,
<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 can be
exposed. This might happen if you have two versions of the same package
installed, for example. The general rule is:</para>
<blockquote><para>There must be no overlaps in the modules provided by all
of the exposed packages, and the packages they depend on, and so
on.</para></blockquote>
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>
......@@ -169,35 +165,45 @@ exposed-modules: Network.BSD,
</indexterm></term>
<listitem>
<para>Causes the compiler to behave as if package
<replaceable>P</replaceable> is not installed at all. This is not
the same as <option>-hide-package</option>, because under
<option>-hide-package</option> the package might still be present
in the program if another package depends on it.</para>
<para><option>-ignore-package</option> <replaceable>P</replaceable>
not only causes package <replaceable>P</replaceable> to be removed,
but also everything that depends on <replaceable>P</replaceable>,
and so on.</para>
<para>Why do we need <option>-ignore-package</option>? Well, it is
particularly useful when you're actually compiling package
<replaceable>P</replaceable> itself. The compiler will refuse to
compile module <replaceable>M</replaceable> if
<replaceable>M</replaceable> is already part of a package. So we
might try <option>-hide-package</option>
<replaceable>P</replaceable>; but then if
<replaceable>P</replaceable> is a dependency of another package
<replaceable>P'</replaceable> we would have to
<option>-hide-package</option> <replaceable>P'</replaceable> too;
and the author of the code can't know in advance which packages are
installed on the system and hence which
<option>-hide-package</option> flags are required. So, we provide
<option>-ignore-package</option> which does the Right Thing.</para>
<replaceable>P</replaceable>, and any packages that depend on
<literal>P</literal>, are not installed at all.</para>
<para>Saying <literal>-ignore-package P</literal> is the same as
giving <literal>-hide-package</literal> flags for
<literal>P</literal> and all the packages that depend on
<literal>P</literal>. Sometimes we don't know ahead of time which
packages will be installed that depend on <literal>P</literal>,
which is when the <literal>-ignore-package</literal> flag can be
useful.</para>
</listitem>
</varlistentry>
</variablelist>
</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>
</sect2>
<sect2 id="package-databases">
<title>Package Databases</title>
......@@ -335,12 +341,6 @@ exposed-modules: Network.BSD,
other packages the current module depends on, but not which
things within those imported things.</para>
</listitem>
<listitem>
<para>When compiling a Haskell module which is to be part of a new package
<replaceable>P</replaceable>, use
<option>-ignore-package</option>&nbsp;<replaceable>P</replaceable>.</para>
</listitem>
</itemizedlist>
<para>It is worth noting that on Windows, when each package
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment