X-Git-Url: http://git.megacz.com/?p=ghc-hetmet.git;a=blobdiff_plain;f=docs%2Fusers_guide%2Fpackages.xml;h=0d7a02f25106afb075763d0e36b598f9237f984a;hp=29b4c22444dba3ab7b339490d55e11dac9799af0;hb=432b9c9322181a3644083e3c19b7e240d90659e7;hpb=5263c9ab4408e3b62dbf7505ab40a81946d4e49b

diff --git a/docs/users_guide/packages.xml b/docs/users_guide/packages.xml
index 29b4c22..0d7a02f 100644
--- a/docs/users_guide/packages.xml
+++ b/docs/users_guide/packages.xml
@@ -469,6 +469,13 @@ $ export GHC_PACKAGE_PATH=$HOME/.my-ghc-packages.conf:</screen>
       options are given, the rightmost one is used as the database to act
       upon.</para>
 
+   <para>Commands that query the package database (list, latest,
+     describe, field) operate on the list of databases specified by
+     the flags <option>--user</option>, <option>--global</option>, and
+     <option>--package-conf</option>.  If none of these flags are
+     given, the default is <option>--global</option>
+     <option>--user</option>.</para>
+
     <para>If the environment variable <literal>GHC_PACKAGE_PATH</literal> is
       set, and its value does not end in a separator (<literal>:</literal> on
       Unix, <literal>;</literal> on Windows), then the last database is
@@ -529,6 +536,15 @@ $ export GHC_PACKAGE_PATH=$HOME/.my-ghc-packages.conf:</screen>
       </varlistentry>
 
       <varlistentry>
+	<term><literal>ghc-pkg check</literal></term>
+	<listitem>
+          <para>Check consistency of dependencies in the package
+          database, and report packages that have missing
+          dependencies.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
 	<term><literal>ghc-pkg hide <replaceable>P</replaceable></literal></term>
 	<listitem>
 	  <para>Sets the <literal>exposed</literal> flag for package
@@ -562,6 +578,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
@@ -577,18 +613,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>