X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=ghc%2Fdocs%2Fusers_guide%2Fpackages.sgml;h=e6f0b7b2b440109eb8a1c80bdce5e48c116bbdab;hb=af76ab6142576b7cc4af11c4883c387e96b18f73;hp=769a7cd4fa509d15104862de3318164869f13870;hpb=551edc4344bb9848e367034c44bee0646b394be2;p=ghc-hetmet.git

diff --git a/ghc/docs/users_guide/packages.sgml b/ghc/docs/users_guide/packages.sgml
index 769a7cd..e6f0b7b 100644
--- a/ghc/docs/users_guide/packages.sgml
+++ b/ghc/docs/users_guide/packages.sgml
@@ -25,8 +25,16 @@
       <indexterm><primary>packages</primary>
 	<secondary>using</secondary></indexterm>
       
-      <para>To use a package, add the <literal>-package</literal> flag
-      to the GHC command line:</para>
+      <para>Some packages 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>
+
+      <para>Some other packages are <emphasis>not</emphasis>
+      automatically available: those are normally the packages
+      containing old non-hierarchical libraries.  To gain access to a
+      non-auto package, use the <option>-package</option> command-line
+      flag:</para>
 
       <variablelist>
 	<varlistentry>
@@ -42,6 +50,20 @@
 	</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
+      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
+      the package dependencies.  We might try to lift this restriction
+      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>
+
+<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
@@ -254,11 +276,18 @@
 	  <indexterm><primary><option>&ndash;&ndash;config-file</option></primary>
 	      </indexterm>
 	  <listitem>
-	    <para>Use <replaceable>file</replaceable> instead of the
-	    default package configuration file.  This, in conjunction
-	    with GHC's <option>-package-conf</option> option, allows
-	    a user to have a local set of packages in addition to the
-	    system-wide installed set.</para>
+	    <para>Use <replaceable>file</replaceable> as an additional
+	    package configuration file. This is used to modify
+	    configuration files for use with GHC's
+	    <option>-package-conf</option> option.</para>
+
+	    <para>There may be any number of configuration files named
+            on the command line; files mentioned later on the
+            command-line override those mentioned earlier.  The
+            <emphasis>last</emphasis> configuration file mentioned on
+            the command-line is the only one that is actually modified
+            by <literal>ghc-pkg</literal>.</para>
+
 	  </listitem>
 	</varlistentry>
 
@@ -268,23 +297,44 @@
 	  <indexterm><primary><option>&ndash;&ndash;list-packages</option></primary></indexterm>
 	  <listitem>
 	    <para>This option displays the list of currently installed
-	    packages.</para>
+	    packages, including those in extra configuration files
+	    specified with the <option>&ndash;&ndash;config-file</option>
+	    option.</para>
 
 <screen>
   $ ghc-pkg &ndash;&ndash;list-packages
-  gmp, rts, std, lang, concurrent, data, net, posix, text, util
+  /usr/local/lib/ghc-5.05/package.conf:
+    hdirect, readline, lang, concurrent, posix, util, data, text, net,
+    hssource, rts, haskell98, network, haskell-src, unix, base
 </screen>
 
 	    <para>Note that your GHC installation might have a
             slightly different set of packages installed.</para>
 
-	    <para>The <literal>gmp</literal> and
-            <literal>rts</literal> packages are always present, and
-            represent the multi-precision integer and runtime system
-            libraries respectively.  The <literal>std</literal>
-            package contains the Haskell prelude and standard
-            libraries.  The rest of the packages are optional
-            libraries.</para>
+	    <para>The <literal>rts</literal> package is always
+            present, and represents the runtime system library.  The
+            <literal>base</literal> package contains the Haskell
+            prelude and basic hierarchical libraries, and the
+            <literal>haskell98</literal> package contains the Haskell
+            98 standard libraries.  The rest of the packages are
+            optional libraries.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term><option>&ndash;&ndash;list-packages-local</option></term>
+	  <term><option>-L</option></term>
+	  <indexterm><primary><option>&ndash;&ndash;list-packages-local</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>
 
@@ -335,6 +385,7 @@
 <screen>
   Package {
      name            = "mypkg",
+     auto            = True,
      import_dirs     = ["${installdir}/imports/mypkg"],
      source_dirs     = [],
      library_dirs    = ["${installdir}"],
@@ -366,12 +417,34 @@
 	</varlistentry>
 
 	<varlistentry>
+	  <term><literal>auto</literal></term>
+	  <indexterm><primary><literal>auto</literal></primary>
+	    <secondary>package specification</secondary>
+	  </indexterm>
+	  <listitem>
+	    <para>Set to <literal>True</literal> if the package should
+	    be automatically available (see <xref
+	    linkend="using-packages">).  This is normally set to
+	    <literal>True</literal> for packages which contain
+	    hierarchical libraries, because in that case there is no
+	    danger of polluting the module namespace.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
 	  <term><literal>import_dirs</literal></term>
 	  <indexterm><primary><literal>import_dirs</literal></primary>
 	    <secondary>package specification</secondary></indexterm>
 	  <listitem>
 	    <para>A list of directories containing interface files
 	    (<literal>.hi</literal> files) for this package.</para>
+
+	    <para>If the package contains profiling libraries, then
+	    the interface files for those library modules should have
+	    the suffix <literal>.p_hi</literal>.  So the package can
+	    contain both normal and profiling versions of the same
+	    library without conflict (see also
+	    <literal>library_dirs</literal> below).</para>
 	  </listitem>
 	</varlistentry>
 
@@ -545,8 +618,9 @@
 	  <indexterm><primary><literal>extra_ld_opts</literal></primary>
 	    <secondary>package specification</secondary></indexterm>
 	  <listitem>
-	    <para>Extra arguments to be added to the gcc command line
-	    (for linking) when this package is being used.</para>
+	    <para>Extra arguments to be added to the
+	    <command>gcc</command> command line (for linking) when
+	    this package is being used.</para>
 	  </listitem>
 	</varlistentry>