Remove an incorrect claim that [t| ... |] isn't implemented yet

[ghc-hetmet.git] / docs / users_guide / packages.xml

diff --git a/docs/users_guide/packages.xml b/docs/users_guide/packages.xml
index 4d0cac7..621747f 100644 (file)
--- a/docs/users_guide/packages.xml
+++ b/docs/users_guide/packages.xml
@@ -5,9 +5,12 @@ Packages
  </title>
   <indexterm><primary>packages</primary></indexterm>
   
  </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
 
   <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>
     
     <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
 
 <screen>
 $ ghc-pkg list

@@ -44,19 +48,16 @@ $ ghc-pkg list
     (hssource-1.0), rts-1.0
       </screen>
 
     (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>
 
       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
     
 <screen>
 $ ghc-pkg field network exposed-modules

@@ -67,12 +68,6 @@ exposed-modules: Network.BSD,
                  Network
 </screen>
 
                  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>
     <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>
          <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
            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>
            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>
 
     </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>
 
   <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> 
 
       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>
       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,
     </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
       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