[project @ 2004-06-22 13:47:27 by simonpj]

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

diff --git a/ghc/docs/users_guide/packages.sgml b/ghc/docs/users_guide/packages.sgml
index fe54098..0852ec7 100644 (file)
--- a/ghc/docs/users_guide/packages.sgml
+++ b/ghc/docs/users_guide/packages.sgml
@@ -25,7 +25,8 @@
       <indexterm><primary>packages</primary>
        <secondary>using</secondary></indexterm>
       
-      <para>Some packages are automatically available: you don't need
+      <para>Some packages,  called <emphasis>auto packages</emphasis>, 
+      are automatically available: you don't need
       to specify any extra flags to use them (except in certain
       circumstances; see below).  All the packages which contain
       hierarchical libraries fall into this category.</para>
@@ -46,13 +47,20 @@
            be imported in your Haskell source, however).  It also
            causes the relevant libraries to be linked when linking is
            being done.</para>
+           <para>Some packages depend on other packages, for example the
+           <literal>text</literal> package makes use of some of the modules
+           in the <literal>lang</literal> package.  The package system
+           takes care of all these dependencies, so that when you say
+           <literal>-package text</literal> on the command line, you
+           automatically get <literal>-package lang</literal> too.</para>
          </listitem>
        </varlistentry>
       </variablelist>
 
       <para>There's one case where you need to use the
       <option>-package</option> option even for auto packages: when
-      linking a program in batch mode<footnote><para>This is because
+      linking a program in batch mode mode (<xref linkend="options-order">) 
+      <footnote><para>This is because
       GHC can't figure out from the object files which packages are
       required; in <option>&ndash;&ndash;make</option> mode and in
       GHCi the compiler has more information available to figure out
@@ -60,18 +68,20 @@
       in the future.</para></footnote>.  For example, to link a
       program consisting of objects <filename>Foo.o</filename> and
       <filename>Main.o</filename>, where we made use of the
-      <literal>network</literal> package:</para>
+      <literal>network</literal> package, we need to give GHC the <literal>-package</literal> flag thus: 
 
 <screen>$ ghc -o myprog Foo.o Main.o -package network</screen>
 
-      <para>Some packages depend on other packages, for example the
-      <literal>text</literal> package makes use of some of the modules
-      in the <literal>lang</literal> package.  The package system
-      takes care of all these dependencies, so that when you say
-      <literal>-package text</literal> on the command line, you
-      automatically get <literal>-package lang</literal> too.</para>
+    The same flag is necessary even if we compiled the modules from source, because GHC still
+    reckons it's in batch mode:
+<screen>$ ghc -o myprog Foo.hs Main.hs -package network</screen>
+In <literal>--make</literal> and <literal>--interactive</literal> modes (<xref linkend="modes">), however, GHC figures out 
+the auto packages required for linking without further assistance.
+</para>
+
     </sect2>
 
+
     <sect2 id="using-local-packages">
       <title>Maintaining a local set of packages</title>
       
@@ -167,6 +177,10 @@
        </listitem>
 
        <listitem>
+         <para>(replace
+          <literal>&ndash;&ndash;--whole-archive</literal> with
+          <literal>&ndash;all_load</literal> on MacOS X)</para>
+
          <para>GHC does not maintain detailed cross-package
           dependency information.  It does remember which modules in
           other packages the current module depends on, but not which
@@ -322,6 +336,23 @@
        </varlistentry>
 
        <varlistentry>
+         <term><option>&ndash;&ndash;list-local-packages</option></term>
+         <term><option>-L</option></term>
+         <indexterm><primary><option>&ndash;&ndash;list-local-packages</option></primary></indexterm>
+         <listitem>
+           <para>Displays the list of packages installed in the
+           topmost configuration file only: that will be the
+           configuration file specified using <option>-f</option> on
+           the command line, or the system configuration file
+           otherwise.</para>
+           
+           <para>This option may be more convenient than
+           <option>-l</option> when the output needs to be parsed by
+           a script.</para>
+         </listitem>
+       </varlistentry>
+
+       <varlistentry>
          <term><option>&ndash;&ndash;remove-package <replaceable>foo</replaceable></option></term>
          <term><option>-r <replaceable>foo</replaceable></option></term>
          <indexterm><primary><option>&ndash;&ndash;delete-package</option></primary>