+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <option>-f</option> <replaceable>file</replaceable>
+ <indexterm><primary><option>-f</option></primary>
+ </indexterm>
+ </term>
+ <term>
+ <option>-package-conf</option> <replaceable>file</replaceable>
+ <indexterm><primary><option>-package-conf</option></primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>Operate on the package database in
+ <replaceable>file</replaceable>.
+ This flag affects the <literal>register</literal>,
+ <literal>update</literal>, <literal>unregister</literal>,
+ <literal>expose</literal>, and <literal>hide</literal>
+ commands.</para>
+
+ <para>When multiple <option>-f</option> options are given, or
+ <option>-f</option> is used in conjunction with
+ <option>--user</option> or <option>--global</option>, the last
+ one on the command-line takes precedence. When listing packages
+ with <literal>ghc-pkg list</literal>, the contents of all the
+ databases specified on the command-line are listed.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <option>––force</option>
+ <indexterm><primary>
+ <option>––force</option>
+ </primary></indexterm>
+ </term>
+ <listitem>
+ <para>Causes <literal>ghc-pkg</literal> to ignore missing
+ dependencies, directories and libraries when registering a package,
+ and just go ahead and add it anyway. This might be useful if your
+ package installation system needs to add the package to
+ GHC before building and installing the files.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <option>––global</option><indexterm><primary><option>––user</option></primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>Operate on the global package database (this is the default).
+ This flag affects the <literal>register</literal>,
+ <literal>update</literal>, <literal>unregister</literal>,
+ <literal>expose</literal>, and <literal>hide</literal>
+ commands.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <option>––help</option><indexterm><primary><option>––user</option></primary>
+ </indexterm>
+ </term>
+ <term>
+ <option>-?</option><indexterm><primary><option>-?</option></primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>Outputs the command-line syntax.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <option>––user</option><indexterm><primary><option>––user</option></primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>Operate on the current user's local package database.
+ This flag affects the <literal>register</literal>,
+ <literal>update</literal>, <literal>unregister</literal>,
+ <literal>expose</literal>, and <literal>hide</literal>
+ commands.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <option>-V</option><indexterm><primary><option>-V</option></primary>
+ </indexterm>
+ </term>
+ <term>
+ <option>––version</option><indexterm><primary><option>––user</option></primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>Output the <literal>ghc-pkg</literal> version number.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>When modifying the package database
+ <replaceable>file</replaceable>, a copy of the original file is
+ saved in <replaceable>file</replaceable><literal>.old</literal>,
+ so in an emergency you can always restore the old settings by
+ copying the old file back again.</para>
+
+ </sect2>
+
+ <sect2 id="installed-pkg-info">
+ <title>
+ <literal>InstalledPackageInfo</literal>: a package specification
+ </title>
+
+ <para>A package specification is a Haskell record; in particular, it is the
+ record <ulink
+ url="../libraries/Cabal/Distribution.InstalledPackageInfo#%tInstalledPackageInfo">InstalledPackageInfo</ulink> in the module Distribution.InstalledPackageInfo, which is part of the Cabal package distributed with GHC.</para>
+
+ <para>An <literal>InstalledPackageInfo</literal> has a human
+ readable/writable syntax. The functions
+ <literal>parseInstalledPackageInfo</literal> and
+ <literal>showInstalledPackageInfo</literal> read and write this syntax
+ respectively. Here's an example of the
+ <literal>InstalledPackageInfo</literal> for the <literal>unix</literal> package:</para>
+
+<screen>
+$ ghc-pkg describe unix
+name: unix
+version: 1.0
+license: BSD3
+copyright:
+maintainer: libraries@haskell.org
+stability:
+homepage:
+package-url:
+description:
+category:
+author:
+exposed: True
+exposed-modules: System.Posix,
+ System.Posix.DynamicLinker.Module,
+ System.Posix.DynamicLinker.Prim,
+ System.Posix.Directory,
+ System.Posix.DynamicLinker,
+ System.Posix.Env,
+ System.Posix.Error,
+ System.Posix.Files,
+ System.Posix.IO,
+ System.Posix.Process,
+ System.Posix.Resource,
+ System.Posix.Temp,
+ System.Posix.Terminal,
+ System.Posix.Time,
+ System.Posix.Unistd,
+ System.Posix.User,
+ System.Posix.Signals.Exts
+import-dirs: /usr/lib/ghc-6.4/libraries/unix
+library-dirs: /usr/lib/ghc-6.4/libraries/unix
+hs-libraries: HSunix
+extra-libs: HSunix_cbits, dl
+include-dirs: /usr/lib/ghc-6.4/libraries/unix/include
+includes: HsUnix.h
+depends: base-1.0
+</screen>
+
+ <para>The full Cabal documentation is still in preparation (at time of
+ writing), so in the meantime here is a brief description of the syntax of
+ this file:</para>
+
+ <para>A package description consists of a number of field/value pairs. A
+ field starts with the field name in the left-hand column followed by a
+ “<literal>:</literal>”, and the value continues until the next line that begins in the
+ left-hand column, or the end of file.</para>
+
+ <para>The syntax of the value depends on the field. The various field
+ types are:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>freeform</term>
+ <listitem>
+ <para>Any arbitrary string, no interpretation or parsing is
+ done.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>string</term>
+ <listitem>
+ <para>A sequence of non-space characters, or a sequence of arbitrary
+ characters surrounded by quotes <literal>"...."</literal>.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>string list</term>
+ <listitem>
+ <para>A sequence of strings, separated by commas. The sequence may
+ be empty.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>In addition, there are some fields with special syntax (e.g. package
+ names, version, dependencies).</para>
+
+ <para>The allowed fields, with their types, are:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>
+ <literal>name</literal>
+ <indexterm><primary><literal>name</literal></primary><secondary>package specification</secondary></indexterm>
+ </term>
+ <listitem>
+ <para>The package's name (without the version).</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <literal>version</literal>
+ <indexterm><primary><literal>version</literal></primary><secondary>package specification</secondary></indexterm>
+ </term>
+ <listitem>
+ <para>The package's version, usually in the form
+ <literal>A.B</literal> (any number of components are allowed).</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <literal>license</literal>
+ <indexterm><primary><literal>auto</literal></primary><secondary>package specification</secondary></indexterm>
+ </term>
+ <listitem>
+ <para>(string) The type of license under which this package is distributed.
+ This field is a value of the <ulink
+ url="../libraries/Cabal/Distribution.License.html#t:License"><literal>License</literal></ulink> type.</para>
+ </listitem>
+ </varlistentry>