X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=docs%2Fusers_guide%2Fpackages.xml;h=621747f33d0cd42fffe7ce236a8dbb43cfc5ce9b;hb=b86f04619dd4c03f6c41448162ec0e338833b514;hp=4d0cac7035d8b655d3bd95d661bca6450bd4591d;hpb=c5a9ed64dab05594bcf871716225ffcbaff6ca7f;p=ghc-hetmet.git

diff --git a/docs/users_guide/packages.xml b/docs/users_guide/packages.xml
index 4d0cac7..621747f 100644
--- a/docs/users_guide/packages.xml
+++ b/docs/users_guide/packages.xml
@@ -5,9 +5,12 @@ Packages
  </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
@@ -30,8 +33,9 @@ Packages
     <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
@@ -44,19 +48,16 @@ $ 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
@@ -67,12 +68,6 @@ exposed-modules: Network.BSD,
                  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>
@@ -82,7 +77,7 @@ exposed-modules: Network.BSD,
 	  <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
@@ -180,9 +175,42 @@ exposed-modules: Network.BSD,
 	    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>
 
@@ -243,7 +271,7 @@ exposed-modules: Network.BSD,
       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>
@@ -379,28 +407,8 @@ $ export GHC_PACKAGE_PATH=$HOME/.my-ghc-packages.conf:</screen>
     </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></term>
-	  <indexterm><primary><literal>-package-name</literal></primary>
-	    <secondary>option</secondary></indexterm>
-	  <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