X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=docs%2Fusers_guide%2Fpackages.xml;h=8d668f9b1fa27275897797bec9365b020080dc98;hb=035890658d56bc5233f73b311a1bd08c41752d33;hp=b37e266d9fe82bfc8e7f76f9ea7ea65d3918e4e4;hpb=83e0b3737f15b976fe54bd75183ec270b08d7e2f;p=ghc-hetmet.git

diff --git a/docs/users_guide/packages.xml b/docs/users_guide/packages.xml
index b37e266..8d668f9 100644
--- a/docs/users_guide/packages.xml
+++ b/docs/users_guide/packages.xml
@@ -393,8 +393,9 @@ $ export GHC_PACKAGE_PATH=$HOME/.my-ghc-packages.conf:</screen>
 	  <literal>&ndash;all_load</literal> on MacOS X)</para>
       </listitem>
       <listitem>
-	<para>When building the package as shared object, GHC wraps
-	  out the underlying linker so that the user gets a common
+	<para>When building the package as shared library, GHC can be used to
+	  perform the link step. This hides some of the details
+	  out the underlying linker and provides a common
 	  interface to all shared object variants that are supported
 	  by GHC (DLLs, ELF DSOs, and Mac OS dylibs). The shared
 	  object must be named in specific way for two reasons: (1)
@@ -578,6 +579,26 @@ $ export GHC_PACKAGE_PATH=$HOME/.my-ghc-packages.conf:</screen>
       </varlistentry>
 
       <varlistentry>
+	<term><literal>ghc-pkg find-module <replaceable>M</replaceable> [<option>--simple-output</option>]</literal></term>
+	<listitem>
+    <para>This option lists registered packages exposing module 
+      <replaceable>M</replaceable>. Examples:</para>
+<screen>
+$ ghc-pkg find-module Var
+c:/fptools/validate/ghc/driver/package.conf.inplace:
+    (ghc-6.9.20080428)
+
+$ ghc-pkg find-module Data.Sequence
+c:/fptools/validate/ghc/driver/package.conf.inplace:
+    containers-0.1
+</screen>
+  <para>Otherwise, it behaves like <literal>ghc-pkg list</literal>,
+  including options.</para>
+	</listitem>
+      </varlistentry>
+
+
+      <varlistentry>
 	<term><literal>ghc-pkg latest <replaceable>P</replaceable></literal></term>
 	<listitem>
 	  <para>Prints the latest available version of package
@@ -593,18 +614,67 @@ $ export GHC_PACKAGE_PATH=$HOME/.my-ghc-packages.conf:</screen>
 	    <literal>InstalledPackageInfo</literal>, the same as the input file
 	    format for <literal>ghc-pkg register</literal>.  See <xref
 	      linkend="installed-pkg-info" /> for details.</para>
+
+          <para>If the pattern matches multiple packages, the
+            description for each package is emitted, separated by the
+            string <literal>---</literal> on a line by itself.</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
-	<term><literal>ghc-pkg field <replaceable>P</replaceable> <replaceable>field</replaceable></literal></term>
+	<term><literal>ghc-pkg field <replaceable>P</replaceable> <replaceable>field</replaceable>[,<replaceable>field</replaceable>]*</literal></term>
 	<listitem>
 	  <para>Show just a single field of the installed package description
-	    for <literal>P</literal>.</para>
+      for <literal>P</literal>. Multiple fields can be selected by separating 
+      them with commas</para>
 	</listitem>
       </varlistentry>
+
+      <varlistentry>
+        <term><literal>ghc-pkg dump</literal></term>
+        <listitem>
+          <para>Emit the full description of every package, in the
+            form of an <literal>InstalledPackageInfo</literal>.
+            Multiple package descriptions are separated by the
+            string <literal>---</literal> on a line by itself.</para>
+
+          <para>This is almost the same as <literal>ghc-pkg describe '*'</literal>, except that <literal>ghc-pkg dump</literal>
+            is intended for use by tools that parse the results, so
+            for example where <literal>ghc-pkg describe '*'</literal>
+            will emit an error if it can't find any packages that
+            match the pattern, <literal>ghc-pkg dump</literal> will
+            simply emit nothing.</para>
+        </listitem>
+      </varlistentry>
     </variablelist>
 
+    <para>
+      Substring matching is supported for <replaceable>M</replaceable> in
+      <literal>find-module</literal> and for <replaceable>P</replaceable> in
+      <literal>list</literal>, <literal>describe</literal>, and
+      <literal>field</literal>, where a <literal>'*'</literal> indicates open
+      substring ends (<literal>prefix*</literal>, <literal>*suffix</literal>,
+      <literal>*infix*</literal>). Examples (output omitted):
+    </para>
+    <screen>
+    -- list all regex-related packages
+    ghc-pkg list '*regex*' --ignore-case
+    -- list all string-related packages
+    ghc-pkg list '*string*' --ignore-case
+    -- list OpenGL-related packages
+    ghc-pkg list '*gl*' --ignore-case
+    -- list packages exporting modules in the Data hierarchy
+    ghc-pkg find-module 'Data.*'
+    -- list packages exporting Monad modules
+    ghc-pkg find-module '*Monad*'
+    -- list names and maintainers for all packages
+    ghc-pkg field '*' name,maintainer
+    -- list location of haddock htmls for all packages
+    ghc-pkg field '*' haddock-html
+    -- dump the whole database
+    ghc-pkg describe '*'
+    </screen>
+
     <para>Additionally, the following flags are accepted by
       <literal>ghc-pkg</literal>:</para>