From: simonmar <unknown>
Date: Tue, 21 Jun 2005 12:03:25 +0000 (+0000)
Subject: [project @ 2005-06-21 12:03:25 by simonmar]
X-Git-Tag: Initial_conversion_from_CVS_complete~416
X-Git-Url: http://git.megacz.com/?a=commitdiff_plain;h=359313f8d5c2e93f4725c9779a2914f11e184db0;p=ghc-hetmet.git

[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.
---

diff --git a/ghc/docs/users_guide/packages.xml b/ghc/docs/users_guide/packages.xml
index 50df575..ec02935 100644
--- a/ghc/docs/users_guide/packages.xml
+++ b/ghc/docs/users_guide/packages.xml
@@ -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