docs/users_guide/packages.xml

   1 <?xml version="1.0" encoding="iso-8859-1"?>
   2   <sect1 id="packages">
   3  <title>
   4 Packages
   5  </title>
   6   <indexterm><primary>packages</primary></indexterm>
   7
   8   <para>A package is a library of Haskell modules known to the
   9     compiler.  GHC comes with several packages: see the accompanying
  10     <ulink url="../libraries/index.html">library
  11     documentation</ulink>.  More packages to install can be obtained
  12     from <ulink
  13     url="http://hackage.haskell.org/packages/hackage.html">HackageDB</ulink>.</para>
  14
  15   <para>Using a package couldn't be simpler: if you're using
  16     <option>&ndash;&ndash;make</option> or GHCi, then most of the installed packages will be
  17     automatically available to your program without any further options.  The
  18     exceptions to this rule are covered below in <xref
  19       linkend="using-packages" />.</para>
  20
  21   <para>Building your own packages is also quite straightforward: we provide
  22     the <ulink url="http://www.haskell.org/cabal/">Cabal</ulink> infrastructure which
  23     automates the process of configuring, building, installing and distributing
  24     a package.  All you need to do is write a simple configuration file, put a
  25     few files in the right places, and you have a package.  See the
  26     <ulink url="../Cabal/index.html">Cabal documentation</ulink>
  27     for details, and also the Cabal libraries (<ulink url="../libraries/Cabal/Distribution-Simple.html">Distribution.Simple</ulink>,
  28     for example).</para>
  29
  30   <sect2 id="using-packages">
  31   <title>Using Packages
  32   </title>
  33     <indexterm><primary>packages</primary>
  34       <secondary>using</secondary></indexterm>
  35
  36     <para>GHC only knows about packages that are
  37       <emphasis>installed</emphasis>. To see which packages are installed, use
  38       the <literal>ghc-pkg list</literal> command:</para>
  39
  40 <screen>
  41 $ ghc-pkg list
  42 /usr/lib/ghc-6.12.1/package.conf.d:
  43     Cabal-1.7.4
  44     array-0.2.0.1
  45     base-3.0.3.0
  46     base-4.2.0.0
  47     bin-package-db-0.0.0.0
  48     binary-0.5.0.1
  49     bytestring-0.9.1.4
  50     containers-0.2.0.1
  51     directory-1.0.0.2
  52     (dph-base-0.4.0)
  53     (dph-par-0.4.0)
  54     (dph-prim-interface-0.4.0)
  55     (dph-prim-par-0.4.0)
  56     (dph-prim-seq-0.4.0)
  57     (dph-seq-0.4.0)
  58     extensible-exceptions-0.1.1.0
  59     ffi-1.0
  60     filepath-1.1.0.1
  61     (ghc-6.12.1)
  62     ghc-prim-0.1.0.0
  63     haskeline-0.6.2
  64     haskell98-1.0.1.0
  65     hpc-0.5.0.2
  66     integer-gmp-0.1.0.0
  67     mtl-1.1.0.2
  68     old-locale-1.0.0.1
  69     old-time-1.0.0.1
  70     pretty-1.0.1.0
  71     process-1.0.1.1
  72     random-1.0.0.1
  73     rts-1.0
  74     syb-0.1.0.0
  75     template-haskell-2.4.0.0
  76     terminfo-0.3.1
  77     time-1.1.4
  78     unix-2.3.1.0
  79     utf8-string-0.3.4
  80 </screen>
  81
  82     <para>An installed package is either <emphasis>exposed</emphasis>
  83       or <emphasis>hidden</emphasis> by default.  Packages hidden by
  84       default are listed in parentheses
  85       (eg. <literal>(lang-1.0)</literal>), or possibly in blue if your
  86       terminal supports colour, in the output of <literal>ghc-pkg
  87       list</literal>.  Command-line flags, described below, allow you
  88       to expose a hidden package or hide an exposed one.  Only modules
  89       from exposed packages may be imported by your Haskell code; if
  90       you try to import a module from a hidden package, GHC will emit
  91       an error message.
  92     </para>
  93
  94     <para>
  95       Note: if you're using Cabal, then the exposed or hidden status
  96       of a package is irrelevant: the available packages are instead
  97       determined by the dependencies listed in
  98       your <literal>.cabal</literal> specification.  The
  99       exposed/hidden status of packages is only relevant when
 100       using <literal>ghc</literal> or <literal>ghci</literal>
 101       directly.
 102     </para>
 103
 104     <para>To see which modules are provided by a package use the
 105       <literal>ghc-pkg</literal> command (see <xref linkend="package-management"/>):</para>
 106
 107 <screen>
 108 $ ghc-pkg field network exposed-modules
 109 exposed-modules: Network.BSD,
 110                  Network.CGI,
 111                  Network.Socket,
 112                  Network.URI,
 113                  Network
 114 </screen>
 115
 116     <para>The GHC command line options that control packages are:</para>
 117
 118     <variablelist>
 119       <varlistentry>
 120         <term>
 121           <option>-package <replaceable>P</replaceable></option>
 122           <indexterm><primary><option>-package</option></primary></indexterm>
 123         </term>
 124         <listitem>
 125           <para>This option causes the installed
 126             package <replaceable>P</replaceable> to be exposed.  The
 127             package <replaceable>P</replaceable> can be specified in
 128             full with its version number
 129             (e.g. <literal>network-1.0</literal>) or the version
 130             number can be omitted if there is only one version of the
 131             package installed. If there are multiple versions
 132             of <replaceable>P</replaceable> installed, then all other
 133             versions will become hidden.</para>
 134
 135           <para>The <option>-package <replaceable>P</replaceable></option>
 136             option also causes package <replaceable>P</replaceable> to
 137             be linked into the resulting executable or shared
 138             object. Whether a packages' library is linked statically
 139             or dynamically is controlled by the flag
 140             pair <option>-static</option>/<option>-dynamic</option>.</para>
 141
 142           <para>In <option>&ndash;&ndash;make</option> mode
 143             and <option>&ndash;&ndash;interactive</option> mode (see
 144             <xref linkend="modes" />), the compiler normally
 145             determines which packages are required by the current
 146             Haskell modules, and links only those.  In batch mode
 147             however, the dependency information isn't available, and
 148             explicit
 149             <option>-package</option> options must be given when linking. The one other time you might need to use
 150             <option>-package</option> to force linking a package is
 151             when the package does not contain any Haskell modules (it
 152             might contain a C library only, for example).  In that
 153             case, GHC will never discover a dependency on it, so it
 154             has to be mentioned explicitly.</para>
 155
 156           <para>For example, to link a program consisting of objects
 157             <filename>Foo.o</filename> and <filename>Main.o</filename>, where
 158             we made use of the <literal>network</literal> package, we need to
 159             give GHC the <literal>-package</literal> flag thus:
 160
 161 <screen>$ ghc -o myprog Foo.o Main.o -package network</screen>
 162
 163             The same flag is necessary even if we compiled the modules from
 164             source, because GHC still reckons it's in batch mode:
 165
 166 <screen>$ ghc -o myprog Foo.hs Main.hs -package network</screen></para>
 167         </listitem>
 168       </varlistentry>
 169
 170       <varlistentry>
 171         <term><option>-hide-all-packages</option>
 172         <indexterm><primary><option>-hide-package</option></primary>
 173           </indexterm></term>
 174         <listitem>
 175           <para>Ignore the exposed flag on installed packages, and hide them
 176             all by default.  If you use
 177             this flag, then any packages you require (including
 178             <literal>base</literal>) need to be explicitly exposed using
 179             <option>-package</option> options.</para>
 180
 181           <para>This is a good way to insulate your program from
 182             differences in the globally exposed packages, and being
 183             explicit about package dependencies is a Good Thing.
 184             Cabal always passes the
 185             <option>-hide-all-packages</option> flag to GHC, for
 186             exactly this reason.</para>
 187         </listitem>
 188       </varlistentry>
 189
 190       <varlistentry>
 191         <term><option>-hide-package</option> <replaceable>P</replaceable>
 192         <indexterm><primary><option>-hide-package</option></primary>
 193           </indexterm></term>
 194         <listitem>
 195           <para>This option does the opposite of <option>-package</option>: it
 196             causes the specified package to be <firstterm>hidden</firstterm>,
 197             which means that none of its modules will be available for import
 198             by Haskell <literal>import</literal> directives.</para>
 199
 200           <para>Note that the package might still end up being linked into the
 201             final program, if it is a dependency (direct or indirect) of
 202             another exposed package.</para>
 203         </listitem>
 204       </varlistentry>
 205
 206       <varlistentry>
 207         <term><option>-ignore-package</option> <replaceable>P</replaceable>
 208         <indexterm><primary><option>-ignore-package</option></primary>
 209           </indexterm></term>
 210         <listitem>
 211           <para>Causes the compiler to behave as if package
 212             <replaceable>P</replaceable>, and any packages that depend on
 213             <literal>P</literal>, are not installed at all.</para>
 214
 215           <para>Saying <literal>-ignore-package P</literal> is the same as
 216             giving <literal>-hide-package</literal> flags for
 217             <literal>P</literal> and all the packages that depend on
 218             <literal>P</literal>.  Sometimes we don't know ahead of time which
 219             packages will be installed that depend on <literal>P</literal>,
 220             which is when the <literal>-ignore-package</literal> flag can be
 221             useful.</para>
 222         </listitem>
 223       </varlistentry>
 224
 225       <varlistentry>
 226         <term><option>-package-name</option> <replaceable>foo</replaceable>
 227         <indexterm><primary><option>-package-name</option></primary>
 228           </indexterm></term>
 229         <listitem>
 230           <para>Tells GHC the the module being compiled forms part of
 231             package <replaceable>foo</replaceable>.
 232             If this flag is omitted (a very common case) then the
 233             default package <literal>main</literal> is assumed.</para>
 234             <para>Note: the argument to <option>-package-name</option>
 235             should be the full package identifier for the package,
 236             that is it should include the version number.  For example:
 237             <literal>-package mypkg-1.2</literal>.</para>
 238         </listitem>
 239       </varlistentry>
 240     </variablelist>
 241   </sect2>
 242
 243   <sect2 id="package-main">
 244     <title>The main package</title>
 245
 246   <para>Every complete Haskell program must define <literal>main</literal> in
 247    module <literal>Main</literal>
 248    in package <literal>main</literal>.   (Omitting the <option>-package-name</option> flag compiles
 249    code for package <literal>main</literal>.) Failure to do so leads to a somewhat obscure
 250    link-time error of the form:
 251 <programlisting>
 252 /usr/bin/ld: Undefined symbols:
 253 _ZCMain_main_closure
 254 ___stginit_ZCMain
 255 </programlisting>
 256 </para>
 257
 258   </sect2>
 259
 260   <sect2 id="package-overlaps">
 261     <title>Consequences of packages for the Haskell language</title>
 262
 263     <para>It is possible that by using packages you might end up with
 264     a program that contains two modules with the same name: perhaps
 265     you used a package P that has a <emphasis>hidden</emphasis> module
 266     M, and there is also a module M in your program.  Or perhaps the
 267     dependencies of packages that you used contain some overlapping
 268     modules.  Perhaps the program even contains multiple versions of a
 269     certain package, due to dependencies from other packages.</para>
 270
 271     <para>None of these scenarios gives rise to an error on its
 272     own<footnote><para>it used to in GHC 6.4, but not since
 273     6.6</para></footnote>, but they may have some interesting
 274     consequences.  For instance, if you have a type
 275     <literal>M.T</literal> from version 1 of package
 276     <literal>P</literal>, then this is <emphasis>not</emphasis> the
 277     same as the type <literal>M.T</literal> from version 2 of package
 278     <literal>P</literal>, and GHC will report an error if you try to
 279     use one where the other is expected.</para>
 280
 281     <para>Formally speaking, in Haskell 98, an entity (function, type
 282     or class) in a program is uniquely identified by the pair of the
 283     module name in which it is defined and its name.  In GHC, an
 284     entity is uniquely defined by a triple: package, module, and
 285     name.</para>
 286   </sect2>
 287
 288   <sect2 id="package-databases">
 289     <title>Package Databases</title>
 290
 291     <para>
 292       A package database is where the details about installed packages
 293       are stored.  It is a directory, usually
 294       called <literal>package.conf.d</literal>, that contains a file
 295       for each package, together with a binary cache of the package
 296       data in the file <literal>package.cache</literal>.  Normally
 297       you won't need to look at or modify the contents of a package
 298       database directly; all management of package databases can be
 299       done through the <literal>ghc-pkg</literal> tool (see
 300       <xref linkend="package-management" />).
 301     </para>
 302
 303     <para>
 304       GHC knows about two package databases in particular:
 305     </para>
 306
 307     <itemizedlist>
 308       <listitem>
 309         <para>The global package database, which comes with your GHC
 310           installation,
 311           e.g. <filename>/usr/lib/ghc-6.12.1/package.conf.d</filename>.</para>
 312       </listitem>
 313       <listitem>
 314         <para>A package database private to each user.  On Unix
 315           systems this will be
 316           <filename>$HOME/.ghc/<replaceable>arch</replaceable>-<replaceable>os</replaceable>-<replaceable>version</replaceable>/package.conf.d</filename>, and on
 317           Windows it will be something like
 318           <filename>C:\Documents&nbsp;And&nbsp;Settings\<replaceable>user</replaceable>\ghc\package.conf.d</filename>.
 319           The <literal>ghc-pkg</literal> tool knows where this file should be
 320           located, and will create it if it doesn't exist (see <xref linkend="package-management" />).</para>
 321       </listitem>
 322     </itemizedlist>
 323
 324     <para>When GHC starts up, it reads the contents of these two package
 325       databases, and builds up a list of the packages it knows about.  You can
 326       see GHC's package table by running GHC with the <option>-v</option>
 327       flag.</para>
 328
 329     <para>Package databases may overlap: for example, packages in the
 330       user database will override (<emphasis>shadow</emphasis>) those
 331       of the same name and version in the global database.</para>
 332
 333     <para>You can control the loading of package databases using the following
 334       GHC options:</para>
 335
 336     <variablelist>
 337       <varlistentry>
 338         <term>
 339           <option>-package-conf <replaceable>file</replaceable></option>
 340           <indexterm><primary><option>-package-conf</option></primary></indexterm>
 341         </term>
 342         <listitem>
 343           <para>Read in the package configuration file
 344             <replaceable>file</replaceable> in addition to the system
 345             default file and the user's local file.  Packages in additional
 346             files read this way will override those in the global and user
 347             databases.</para>
 348         </listitem>
 349       </varlistentry>
 350
 351       <varlistentry>
 352         <term><option>-no-user-package-conf</option>
 353           <indexterm><primary><option>-no-user-package-conf</option></primary>
 354           </indexterm>
 355         </term>
 356         <listitem>
 357           <para>Prevent loading of the user's local package database.</para>
 358         </listitem>
 359       </varlistentry>
 360     </variablelist>
 361
 362     <sect3 id="ghc-package-path">
 363       <title>The <literal>GHC_PACKAGE_PATH</literal> environment variable</title>
 364       <indexterm><primary>Environment variable</primary><secondary><literal>GHC_PACKAGE_PATH</literal></secondary>
 365       </indexterm>
 366       <indexterm><primary><literal>GHC_PACKAGE_PATH</literal></primary></indexterm>
 367       <para>The <literal>GHC_PACKAGE_PATH</literal> environment variable may be
 368         set to a <literal>:</literal>-separated (<literal>;</literal>-separated
 369         on Windows) list of files containing package databases.  This list of
 370         package databases is used by GHC and ghc-pkg, with earlier databases in
 371         the list overriding later ones.  This order was chosen to match the
 372         behaviour of the <literal>PATH</literal> environment variable; think of
 373         it as a list of package databases that are searched left-to-right for
 374         packages.</para>
 375
 376       <para>If <literal>GHC_PACKAGE_PATH</literal> ends in a separator, then
 377         the default user and system package databases are appended, in that
 378         order. e.g. to augment the usual set of packages with a database of
 379         your own, you could say (on Unix):
 380 <screen>
 381 $ export GHC_PACKAGE_PATH=$HOME/.my-ghc-packages.conf:</screen>
 382         (use <literal>;</literal> instead of <literal>:</literal> on
 383         Windows).</para>
 384
 385       <para>To check whether your <literal>GHC_PACKAGE_PATH</literal> setting
 386         is doing the right thing, <literal>ghc-pkg list</literal> will list all
 387         the databases in use, in the reverse order they are searched.</para>
 388
 389     </sect3>
 390   </sect2>
 391
 392   <sect2 id="broken-packages">
 393     <title>Dependencies and broken packages</title>
 394
 395     <para>Each installed package has a unique identifier, which
 396       distinguishes it from all other installed packages on the
 397       system.  To see the identifiers associated with each installed
 398       package, use <literal>ghc-pkg list -v</literal>:</para>
 399
 400     <screen>
 401 $ ghc-pkg list -v
 402 using cache: /usr/lib/ghc-6.12.1/package.conf.d/package.cache
 403 /usr/lib/ghc-6.12.1/package.conf.d
 404    Cabal-1.7.4 (Cabal-1.7.4-48f5247e06853af93593883240e11238)
 405    array-0.2.0.1 (array-0.2.0.1-9cbf76a576b6ee9c1f880cf171a0928d)
 406    base-3.0.3.0 (base-3.0.3.0-6cbb157b9ae852096266e113b8fac4a2)
 407    base-4.2.0.0 (base-4.2.0.0-247bb20cde37c3ef4093ee124e04bc1c)
 408    ...
 409 </screen>
 410
 411     <para>
 412       The string in parentheses after the package name is the unique
 413       identifier: it normally begins with the package name and
 414       version, and ends in a hash string derived from the compiled
 415       package.  Dependencies between packages are expressed in terms
 416       of these unique identifiers, rather than just packages and
 417       versions.  For example, take a look at the dependencies of
 418       the <literal>haskell98</literal> package:
 419     </para>
 420
 421     <screen>
 422 $ ghc-pkg field haskell98 depends
 423 depends: array-0.2.0.1-9cbf76a576b6ee9c1f880cf171a0928d
 424          base-4.2.0.0-247bb20cde37c3ef4093ee124e04bc1c
 425          directory-1.0.0.2-f51711bc872c35ce4a453aa19c799008
 426          old-locale-1.0.0.1-d17c9777c8ee53a0d459734e27f2b8e9
 427          old-time-1.0.0.1-1c0d8ea38056e5087ef1e75cb0d139d1
 428          process-1.0.1.1-d8fc6d3baf44678a29b9d59ca0ad5780
 429          random-1.0.0.1-423d08c90f004795fd10e60384ce6561
 430 </screen>
 431
 432     <para>
 433       The purpose of the unique package identifier is to detect
 434       problems caused by re-installing a package without also
 435       recompiling the packages that depend on it.  Recompiling
 436       dependencies is necessary, because the newly compiled package
 437       may have a differnt ABI (Application Binary Interface) than the
 438       previous version, even if both packages were built from the same
 439       source code using the same compiler.  With unique package
 440       identifiers, a recompiled package will have a different unique
 441       identifer from the previous version, so packages that depended
 442       on the previous version are now orphaned - one of their
 443       dependencies is not satisfied.  Packages that are broken in this
 444       way are shown in the <literal>ghc-pkg list</literal> output
 445       either in red (if possible) or otherwise surrounded by
 446       braces.  In the following example, we have recompiled and
 447       reinstalled the <literal>filepath</literal> package, and this
 448       has caused various dependencies
 449       including <literal>Cabal</literal> to break:</para>
 450
 451     <screen>
 452 $ ghc-pkg list
 453 WARNING: there are broken packages.  Run 'ghc-pkg check' for more details.
 454 /usr/lib/ghc-6.12.1/package.conf.d:
 455     {Cabal-1.7.4}
 456     array-0.2.0.1
 457     base-3.0.3.0
 458     ... etc ...
 459 </screen>
 460
 461     <para>
 462       Additionally, <literal>ghc-pkg list</literal> reminds you that
 463       there are broken packages and suggests <literal>ghc-pkg
 464       check</literal>, which displays more information about the
 465       nature of the failure:
 466     </para>
 467
 468     <screen>
 469 $ ghc-pkg check
 470 There are problems in package ghc-6.12.1:
 471   dependency "filepath-1.1.0.1-87511764eb0af2bce4db05e702750e63" doesn't exist
 472 There are problems in package haskeline-0.6.2:
 473   dependency "filepath-1.1.0.1-87511764eb0af2bce4db05e702750e63" doesn't exist
 474 There are problems in package Cabal-1.7.4:
 475   dependency "filepath-1.1.0.1-87511764eb0af2bce4db05e702750e63" doesn't exist
 476 There are problems in package process-1.0.1.1:
 477   dependency "filepath-1.1.0.1-87511764eb0af2bce4db05e702750e63" doesn't exist
 478 There are problems in package directory-1.0.0.2:
 479   dependency "filepath-1.1.0.1-87511764eb0af2bce4db05e702750e63" doesn't exist
 480
 481 The following packages are broken, either because they have a problem
 482 listed above, or because they depend on a broken package.
 483 ghc-6.12.1
 484 haskeline-0.6.2
 485 Cabal-1.7.4
 486 process-1.0.1.1
 487 directory-1.0.0.2
 488 bin-package-db-0.0.0.0
 489 hpc-0.5.0.2
 490 haskell98-1.0.1.0
 491 </screen>
 492
 493     <para>
 494       To fix the problem, you need to recompile the broken packages
 495       against the new dependencies.  The easiest way to do this is to
 496       use <literal>cabal-install</literal>, or download the packages
 497       from <ulink
 498     url="http://hackage.haskell.org/packages/hackage.html">HackageDB</ulink>
 499       and build and install them as normal.</para>
 500
 501     <para>Be careful not to recompile any packages that GHC itself
 502       depends on, as this may render the <literal>ghc</literal>
 503       package itself broken, and <literal>ghc</literal> cannot be
 504       simply recompiled.  The only way to recover from this would be
 505       to re-install GHC.</para>
 506   </sect2>
 507
 508   <sect2 id="package-management">
 509     <title>Package management (the <literal>ghc-pkg</literal> command)</title>
 510     <indexterm><primary>packages</primary>
 511       <secondary>management</secondary></indexterm>
 512
 513     <para>The <literal>ghc-pkg</literal> tool is for querying and
 514       modifying package databases.  To see what package databases are
 515       in use, use
 516       <literal>ghc-pkg&nbsp;list</literal>.  The stack of databases that
 517       <literal>ghc-pkg</literal> knows about can be modified using the
 518       <literal>GHC_PACKAGE_PATH</literal> environment variable (see <xref
 519         linkend="ghc-package-path" />, and using
 520         <literal>--package-conf</literal> options on the
 521         <literal>ghc-pkg</literal> command line.</para>
 522
 523     <para>When asked to modify a database, <literal>ghc-pkg</literal> modifies
 524       the global database by default.  Specifying <option>--user</option>
 525       causes it to act on the user database, or <option>--package-conf</option>
 526       can be used to act on another database entirely.  When multiple of these
 527       options are given, the rightmost one is used as the database to act
 528       upon.</para>
 529
 530    <para>Commands that query the package database (list, latest,
 531      describe, field, dot) operate on the list of databases specified by
 532      the flags <option>--user</option>, <option>--global</option>, and
 533      <option>--package-conf</option>.  If none of these flags are
 534      given, the default is <option>--global</option>
 535      <option>--user</option>.</para>
 536
 537     <para>If the environment variable <literal>GHC_PACKAGE_PATH</literal> is
 538       set, and its value does not end in a separator (<literal>:</literal> on
 539       Unix, <literal>;</literal> on Windows), then the last database is
 540       considered to be the global database, and will be modified by default by
 541       <literal>ghc-pkg</literal>.  The intention here is that
 542       <literal>GHC_PACKAGE_PATH</literal> can be used to create a virtual
 543       package environment into which Cabal packages can be installed without
 544       setting anything other than <literal>GHC_PACKAGE_PATH</literal>.</para>
 545
 546     <para>The <literal>ghc-pkg</literal> program may be run in the ways listed
 547       below.  Where a package name is required, the package can be named in
 548       full including the version number
 549       (e.g. <literal>network-1.0</literal>), or without the version number.
 550       Naming a package without the version number matches all versions of the
 551       package; the specified action will be applied to all the matching
 552       packages.  A package specifier that matches all version of the package
 553       can also be written <replaceable>pkg</replaceable><literal>-*</literal>,
 554       to make it clearer that multiple packages are being matched.</para>
 555
 556     <variablelist>
 557       <varlistentry>
 558         <term><literal>ghc-pkg init <replaceable>path</replaceable></literal></term>
 559         <listitem>
 560           <para>Creates a new, empty, package database
 561             at <replaceable>path</replaceable>, which must not already
 562             exist.</para>
 563         </listitem>
 564       </varlistentry>
 565
 566       <varlistentry>
 567         <term><literal>ghc-pkg register <replaceable>file</replaceable></literal></term>
 568         <listitem>
 569           <para>Reads a package specification from
 570             <replaceable>file</replaceable> (which may be &ldquo;<literal>-</literal>&rdquo;
 571             to indicate standard input),
 572             and adds it to the database of installed packages.  The syntax of
 573             <replaceable>file</replaceable> is given in <xref
 574               linkend="installed-pkg-info" />.</para>
 575
 576           <para>The package specification must be a package that isn't already
 577             installed.</para>
 578         </listitem>
 579       </varlistentry>
 580
 581       <varlistentry>
 582         <term><literal>ghc-pkg update <replaceable>file</replaceable></literal></term>
 583         <listitem>
 584           <para>The same as <literal>register</literal>, except that if a
 585             package of the same name is already installed, it is
 586             replaced by the new one.</para>
 587         </listitem>
 588       </varlistentry>
 589
 590       <varlistentry>
 591         <term><literal>ghc-pkg unregister <replaceable>P</replaceable></literal></term>
 592         <listitem>
 593           <para>Remove the specified package from the database.</para>
 594         </listitem>
 595       </varlistentry>
 596
 597       <varlistentry>
 598         <term><literal>ghc-pkg expose <replaceable>P</replaceable></literal></term>
 599         <listitem>
 600           <para>Sets the <literal>exposed</literal> flag for package
 601             <replaceable>P</replaceable> to <literal>True</literal>.</para>
 602         </listitem>
 603       </varlistentry>
 604
 605       <varlistentry>
 606         <term><literal>ghc-pkg check</literal></term>
 607         <listitem>
 608           <para>Check consistency of dependencies in the package
 609           database, and report packages that have missing
 610           dependencies.</para>
 611         </listitem>
 612       </varlistentry>
 613
 614       <varlistentry>
 615         <term><literal>ghc-pkg hide <replaceable>P</replaceable></literal></term>
 616         <listitem>
 617           <para>Sets the <literal>exposed</literal> flag for package
 618             <replaceable>P</replaceable> to <literal>False</literal>.</para>
 619         </listitem>
 620       </varlistentry>
 621
 622       <varlistentry>
 623         <term><literal>ghc-pkg list [<replaceable>P</replaceable>] [<option>--simple-output</option>]</literal></term>
 624         <listitem>
 625           <para>This option displays the currently installed
 626             packages, for each of the databases known to
 627             <literal>ghc-pkg</literal>.  That includes the global database, the
 628             user's local database, and any further files specified using the
 629             <option>-f</option> option on the command line.</para>
 630
 631           <para>Hidden packages (those for which the <literal>exposed</literal>
 632             flag is <literal>False</literal>) are shown in parentheses in the
 633             list of packages.</para>
 634
 635           <para>If an optional package identifier <replaceable>P</replaceable>
 636             is given, then only packages matching that identifier are
 637             shown.</para>
 638
 639           <para>If the option <option>--simple-output</option> is given, then
 640             the packages are listed on a single line separated by spaces, and
 641             the database names are not included.  This is intended to make it
 642             easier to parse the output of <literal>ghc-pkg list</literal> using
 643             a script.</para>
 644         </listitem>
 645       </varlistentry>
 646
 647       <varlistentry>
 648         <term><literal>ghc-pkg find-module <replaceable>M</replaceable> [<option>--simple-output</option>]</literal></term>
 649         <listitem>
 650     <para>This option lists registered packages exposing module
 651       <replaceable>M</replaceable>. Examples:</para>
 652 <screen>
 653 $ ghc-pkg find-module Var
 654 c:/fptools/validate/ghc/driver/package.conf.inplace:
 655     (ghc-6.9.20080428)
 656
 657 $ ghc-pkg find-module Data.Sequence
 658 c:/fptools/validate/ghc/driver/package.conf.inplace:
 659     containers-0.1
 660 </screen>
 661   <para>Otherwise, it behaves like <literal>ghc-pkg list</literal>,
 662   including options.</para>
 663         </listitem>
 664       </varlistentry>
 665
 666
 667       <varlistentry>
 668         <term><literal>ghc-pkg latest <replaceable>P</replaceable></literal></term>
 669         <listitem>
 670           <para>Prints the latest available version of package
 671             <replaceable>P</replaceable>.</para>
 672         </listitem>
 673       </varlistentry>
 674
 675       <varlistentry>
 676         <term><literal>ghc-pkg describe <replaceable>P</replaceable></literal></term>
 677         <listitem>
 678           <para>Emit the full description of the specified package.  The
 679             description is in the form of an
 680             <literal>InstalledPackageInfo</literal>, the same as the input file
 681             format for <literal>ghc-pkg register</literal>.  See <xref
 682               linkend="installed-pkg-info" /> for details.</para>
 683
 684           <para>If the pattern matches multiple packages, the
 685             description for each package is emitted, separated by the
 686             string <literal>---</literal> on a line by itself.</para>
 687         </listitem>
 688       </varlistentry>
 689
 690       <varlistentry>
 691         <term><literal>ghc-pkg field <replaceable>P</replaceable> <replaceable>field</replaceable>[,<replaceable>field</replaceable>]*</literal></term>
 692         <listitem>
 693           <para>Show just a single field of the installed package description
 694       for <literal>P</literal>. Multiple fields can be selected by separating
 695       them with commas</para>
 696         </listitem>
 697       </varlistentry>
 698
 699       <varlistentry>
 700         <term><literal>ghc-pkg dot</literal></term>
 701         <listitem>
 702           <para>
 703             Generate a graph of the package dependencies in a form
 704             suitable for input for the <ulink url="http://www.graphviz.org/">graphviz</ulink> tools.  For example,
 705             to generate a PDF of the dependency graph:</para>
 706 <screen>
 707 ghc-pkg dot | tred | dot -Tpdf >pkgs.pdf
 708 </screen>
 709         </listitem>
 710       </varlistentry>
 711
 712       <varlistentry>
 713         <term><literal>ghc-pkg dump</literal></term>
 714         <listitem>
 715           <para>Emit the full description of every package, in the
 716             form of an <literal>InstalledPackageInfo</literal>.
 717             Multiple package descriptions are separated by the
 718             string <literal>---</literal> on a line by itself.</para>
 719
 720           <para>This is almost the same as <literal>ghc-pkg describe '*'</literal>, except that <literal>ghc-pkg dump</literal>
 721             is intended for use by tools that parse the results, so
 722             for example where <literal>ghc-pkg describe '*'</literal>
 723             will emit an error if it can't find any packages that
 724             match the pattern, <literal>ghc-pkg dump</literal> will
 725             simply emit nothing.</para>
 726         </listitem>
 727       </varlistentry>
 728
 729       <varlistentry>
 730         <term><literal>ghc-pkg recache</literal></term>
 731         <listitem>
 732           <para>
 733             Re-creates the binary cache
 734             file <filename>package.cache</filename> for the selected
 735             database.  This may be necessary if the cache has somehow
 736             become out-of-sync with the contents of the database
 737             (<literal>ghc-pkg</literal> will warn you if this might be
 738             the case).</para>
 739
 740           <para>
 741             The other time when <literal>ghc-pkg recache</literal> is
 742             useful is for registering packages manually: it is
 743             possible to register a package by simply putting the
 744             appropriate file in the package database directory and
 745             invoking <literal>ghc-pkg recache</literal> to update the
 746             cache.  This method of registering packages may be more
 747             convenient for automated packaging systems.
 748           </para>
 749         </listitem>
 750       </varlistentry>
 751     </variablelist>
 752
 753     <para>
 754       Substring matching is supported for <replaceable>M</replaceable> in
 755       <literal>find-module</literal> and for <replaceable>P</replaceable> in
 756       <literal>list</literal>, <literal>describe</literal>, and
 757       <literal>field</literal>, where a <literal>'*'</literal> indicates open
 758       substring ends (<literal>prefix*</literal>, <literal>*suffix</literal>,
 759       <literal>*infix*</literal>). Examples (output omitted):
 760     </para>
 761     <screen>
 762     -- list all regex-related packages
 763     ghc-pkg list '*regex*' --ignore-case
 764     -- list all string-related packages
 765     ghc-pkg list '*string*' --ignore-case
 766     -- list OpenGL-related packages
 767     ghc-pkg list '*gl*' --ignore-case
 768     -- list packages exporting modules in the Data hierarchy
 769     ghc-pkg find-module 'Data.*'
 770     -- list packages exporting Monad modules
 771     ghc-pkg find-module '*Monad*'
 772     -- list names and maintainers for all packages
 773     ghc-pkg field '*' name,maintainer
 774     -- list location of haddock htmls for all packages
 775     ghc-pkg field '*' haddock-html
 776     -- dump the whole database
 777     ghc-pkg describe '*'
 778 </screen>
 779
 780     <para>Additionally, the following flags are accepted by
 781       <literal>ghc-pkg</literal>:</para>
 782
 783     <variablelist>
 784       <varlistentry>
 785         <term>
 786           <option>&ndash;&ndash;auto-ghci-libs</option><indexterm><primary><option>&ndash;&ndash;auto-ghci-libs</option></primary>
 787           </indexterm>
 788         </term>
 789         <listitem>
 790           <para>Automatically generate the GHCi
 791             <filename>.o</filename> version of each
 792             <filename>.a</filename> Haskell library, using GNU ld (if
 793             that is available).  Without this option,
 794             <literal>ghc-pkg</literal> will warn if GHCi versions of
 795             any Haskell libraries in the package don't exist.</para>
 796
 797             <para>GHCi <literal>.o</literal> libraries don't
 798             necessarily have to live in the same directory as the
 799             corresponding <literal>.a</literal> library.  However,
 800             this option will cause the GHCi library to be created in
 801             the same directory as the <literal>.a</literal>
 802             library.</para>
 803         </listitem>
 804       </varlistentry>
 805
 806       <varlistentry>
 807         <term>
 808           <option>-f</option> <replaceable>file</replaceable>
 809           <indexterm><primary><option>-f</option></primary>
 810           </indexterm>
 811         </term>
 812         <term>
 813           <option>-package-conf</option> <replaceable>file</replaceable>
 814           <indexterm><primary><option>-package-conf</option></primary>
 815           </indexterm>
 816         </term>
 817         <listitem>
 818           <para>Adds <replaceable>file</replaceable> to the stack of package
 819             databases.  Additionally, <replaceable>file</replaceable> will
 820             also be the database modified by a <literal>register</literal>,
 821             <literal>unregister</literal>, <literal>expose</literal> or
 822             <literal>hide</literal> command, unless it is overridden by a later
 823             <option>--package-conf</option>, <option>--user</option> or
 824             <option>--global</option> option.</para>
 825         </listitem>
 826       </varlistentry>
 827
 828       <varlistentry>
 829         <term>
 830           <option>&ndash;&ndash;force</option>
 831           <indexterm><primary>
 832               <option>&ndash;&ndash;force</option>
 833             </primary></indexterm>
 834         </term>
 835         <listitem>
 836           <para>Causes <literal>ghc-pkg</literal> to ignore missing
 837             dependencies, directories and libraries when registering a package,
 838             and just go ahead and add it anyway.  This might be useful if your
 839             package installation system needs to add the package to
 840             GHC before building and installing the files.</para>
 841         </listitem>
 842       </varlistentry>
 843
 844       <varlistentry>
 845         <term>
 846           <option>&ndash;&ndash;global</option><indexterm><primary><option>&ndash;&ndash;global</option></primary>
 847           </indexterm>
 848         </term>
 849         <listitem>
 850           <para>Operate on the global package database (this is the default).
 851             This flag affects the <literal>register</literal>,
 852             <literal>update</literal>, <literal>unregister</literal>,
 853             <literal>expose</literal>, and <literal>hide</literal>
 854             commands.</para>
 855         </listitem>
 856       </varlistentry>
 857
 858       <varlistentry>
 859         <term>
 860           <option>&ndash;&ndash;help</option><indexterm><primary><option>&ndash;&ndash;help</option></primary>
 861           </indexterm>
 862         </term>
 863         <term>
 864           <option>-?</option><indexterm><primary><option>-?</option></primary>
 865           </indexterm>
 866         </term>
 867         <listitem>
 868           <para>Outputs the command-line syntax.</para>
 869         </listitem>
 870       </varlistentry>
 871
 872       <varlistentry>
 873         <term>
 874           <option>&ndash;&ndash;user</option><indexterm><primary><option>&ndash;&ndash;user</option></primary>
 875           </indexterm>
 876         </term>
 877         <listitem>
 878           <para>Operate on the current user's local package database.
 879             This flag affects the <literal>register</literal>,
 880             <literal>update</literal>, <literal>unregister</literal>,
 881             <literal>expose</literal>, and <literal>hide</literal>
 882             commands.</para>
 883         </listitem>
 884       </varlistentry>
 885
 886       <varlistentry>
 887         <term>
 888           <option>-v</option><optional><replaceable>n</replaceable></optional><indexterm><primary><option>-v</option></primary><secondary>ghc-pkg
 889               option</secondary></indexterm>
 890         </term>
 891         <term>
 892           <option>--verbose</option><optional>=<replaceable>n</replaceable></optional><indexterm><primary><option>--verbose</option></primary><secondary>ghc-pkg option</secondary></indexterm>
 893         </term>
 894         <listitem>
 895           <para>
 896             Control verbosity.  Verbosity levels range from 0-2, where
 897             the default is 1, and <option>-v</option> alone selects
 898             level 2.
 899           </para>
 900         </listitem>
 901       </varlistentry>
 902
 903       <varlistentry>
 904         <term>
 905           <option>-V</option><indexterm><primary><option>-V</option></primary>
 906           </indexterm>
 907         </term>
 908         <term>
 909           <option>&ndash;&ndash;version</option><indexterm><primary><option>&ndash;&ndash;version</option></primary>
 910           </indexterm>
 911         </term>
 912         <listitem>
 913           <para>Output the <literal>ghc-pkg</literal> version number.</para>
 914         </listitem>
 915       </varlistentry>
 916     </variablelist>
 917
 918   </sect2>
 919
 920   <sect2 id="building-packages">
 921     <title>Building a package from Haskell source</title>
 922     <indexterm><primary>packages</primary>
 923       <secondary>building</secondary></indexterm>
 924
 925     <para>We don't recommend building packages the hard way.  Instead, use the
 926       <ulink url="../Cabal/index.html">Cabal</ulink> infrastructure
 927       if possible.  If your package is particularly complicated or requires a
 928       lot of configuration, then you might have to fall back to the low-level
 929       mechanisms, so a few hints for those brave souls follow.</para>
 930
 931     <para>You need to build an "installed package info" file for
 932       passing to <literal>ghc-pkg</literal> when installing your
 933       package.  The contents of this file are described in
 934       <xref linkend="installed-pkg-info" />.</para>
 935
 936     <para>The Haskell code in a package may be built into one or more
 937       archive libraries (e.g. <filename>libHSfoo.a</filename>), or a
 938       single shared object
 939       (e.g. <filename>libHSfoo.dll/.so/.dylib</filename>).  The
 940       restriction to a single shared object is because the package
 941       system is used to tell the compiler when it should make an
 942       inter-shared-object call rather than an intra-shared-object-call
 943       call (inter-shared-object calls require an extra
 944       indirection).</para>
 945     <itemizedlist>
 946       <listitem><para>Building a static library is done by using the
 947           <literal>ar</literal> tool, like so:</para>
 948
 949 <screen>ar cqs libHSfoo-1.0.a A.o B.o C.o ...</screen>
 950
 951           <para>where <filename>A.o</filename>,
 952             <filename>B.o</filename> and so on are the compiled Haskell
 953             modules, and <filename>libHSfoo.a</filename> is the library you
 954             wish to create.  The syntax may differ slightly on your system,
 955             so check the documentation if you run into difficulties.</para>
 956       </listitem>
 957       <listitem>
 958         <para>Versions of the Haskell libraries for use with GHCi may also
 959           abe included: GHCi cannot load <literal>.a</literal> files
 960           directly, instead it will look for an object file
 961           called <filename>HSfoo.o</filename> and load that.  On some
 962           systems, the <literal>ghc-pkg</literal> tool can automatically
 963           build the GHCi version of each library, see
 964           <xref linkend="package-management"/>.  To build these libraries
 965           by hand from the <literal>.a</literal> archive, it is possible
 966           to use GNU <command>ld</command> as follows:</para>
 967
 968 <screen>ld -r &ndash;&ndash;whole-archive -o HSfoo.o libHSfoo.a</screen>
 969
 970         <para>(replace
 971           <literal>&ndash;&ndash;whole-archive</literal> with
 972           <literal>&ndash;all_load</literal> on MacOS X)</para>
 973       </listitem>
 974       <listitem>
 975         <para>When building the package as shared library, GHC can be used to
 976           perform the link step. This hides some of the details
 977           out the underlying linker and provides a common
 978           interface to all shared object variants that are supported
 979           by GHC (DLLs, ELF DSOs, and Mac OS dylibs). The shared
 980           object must be named in specific way for two reasons: (1)
 981           the name must contain the GHC compiler version, so that two
 982           library variants don't collide that are compiled by
 983           different versions of GHC and that therefore are most likely
 984           incompatible with respect to calling conventions, (2) it
 985           must be different from the static name otherwise we would
 986           not be able to control the linker as precisely as necessary
 987           to make
 988           the <option>-static</option>/<option>-dynamic</option> flags
 989           work, see <xref linkend="options-linker" />.</para>
 990
 991 <screen>ghc -shared libHSfoo-1.0-ghc<replaceable>GHCVersion</replaceable>.so A.o B.o C.o</screen>
 992         <para>Using GHC's version number in the shared object name
 993           allows different library versions compiled by different GHC
 994           versions to be installed in standard system locations,
 995           e.g. under *nix /usr/lib. To obtain the version number of
 996           GHC invoke <literal>ghc --numeric-version</literal> and use
 997           its output in place
 998           of <replaceable>GHCVersion</replaceable>. See also
 999           <xref linkend="options-codegen" /> on how object files must
1000           be prepared for shared object linking.</para>
1001       </listitem>
1002     </itemizedlist>
1003
1004      <para>To compile a module which is to be part of a new package,
1005       use the <literal>-package-name</literal> option (<xref linkend="using-packages"/>).
1006       Failure to use the <literal>-package-name</literal> option
1007       when compiling a package will probably result in disaster, but
1008       you will only discover later when you attempt to import modules
1009       from the package.  At this point GHC will complain that the
1010       package name it was expecting the module to come from is not the
1011       same as the package name stored in the <literal>.hi</literal>
1012       file.</para>
1013
1014     <para>It is worth noting with shared objects, when each package
1015       is built as a single shared object file, since a reference to a shared object costs an extra
1016       indirection, intra-package references are cheaper than
1017       inter-package references. Of course, this applies to the
1018       <filename>main</filename> package as well.</para>
1019     </sect2>
1020
1021   <sect2 id="installed-pkg-info">
1022     <title>
1023       <literal>InstalledPackageInfo</literal>: a package specification
1024     </title>
1025
1026     <para>A package specification is a Haskell record; in particular, it is the
1027       record <ulink
1028         url="../libraries/Cabal/Distribution-InstalledPackageInfo.html#%tInstalledPackageInfo">InstalledPackageInfo</ulink> in the module Distribution.InstalledPackageInfo, which is part of the Cabal package distributed with GHC.</para>
1029
1030     <para>An <literal>InstalledPackageInfo</literal> has a human
1031       readable/writable syntax.  The functions
1032       <literal>parseInstalledPackageInfo</literal> and
1033       <literal>showInstalledPackageInfo</literal> read and write this syntax
1034       respectively.  Here's an example of the
1035       <literal>InstalledPackageInfo</literal> for the <literal>unix</literal> package:</para>
1036
1037 <screen>
1038 $ ghc-pkg describe unix
1039 name: unix
1040 version: 2.3.1.0
1041 id: unix-2.3.1.0-de7803f1a8cd88d2161b29b083c94240
1042 license: BSD3
1043 copyright:
1044 maintainer: libraries@haskell.org
1045 stability:
1046 homepage:
1047 package-url:
1048 description: This package gives you access to the set of operating system
1049              services standardised by POSIX 1003.1b (or the IEEE Portable
1050              Operating System Interface for Computing Environments -
1051              IEEE Std. 1003.1).
1052              .
1053              The package is not supported under Windows (except under Cygwin).
1054 category: System
1055 author:
1056 exposed: True
1057 exposed-modules: System.Posix System.Posix.DynamicLinker.Module
1058                  System.Posix.DynamicLinker.Prim System.Posix.Directory
1059                  System.Posix.DynamicLinker System.Posix.Env System.Posix.Error
1060                  System.Posix.Files System.Posix.IO System.Posix.Process
1061                  System.Posix.Process.Internals System.Posix.Resource
1062                  System.Posix.Temp System.Posix.Terminal System.Posix.Time
1063                  System.Posix.Unistd System.Posix.User System.Posix.Signals
1064                  System.Posix.Signals.Exts System.Posix.Semaphore
1065                  System.Posix.SharedMem
1066 hidden-modules:
1067 import-dirs: /usr/lib/ghc-6.12.1/unix-2.3.1.0
1068 library-dirs: /usr/lib/ghc-6.12.1/unix-2.3.1.0
1069 hs-libraries: HSunix-2.3.1.0
1070 extra-libraries: rt util dl
1071 extra-ghci-libraries:
1072 include-dirs: /usr/lib/ghc-6.12.1/unix-2.3.1.0/include
1073 includes: HsUnix.h execvpe.h
1074 depends: base-4.2.0.0-247bb20cde37c3ef4093ee124e04bc1c
1075 hugs-options:
1076 cc-options:
1077 ld-options:
1078 framework-dirs:
1079 frameworks:
1080 haddock-interfaces: /usr/share/doc/ghc/html/libraries/unix/unix.haddock
1081 haddock-html: /usr/share/doc/ghc/html/libraries/unix
1082 </screen>
1083
1084     <para>Here is a brief description of the syntax of this file:</para>
1085
1086     <para>A package description consists of a number of field/value pairs.  A
1087       field starts with the field name in the left-hand column followed by a
1088       &ldquo;<literal>:</literal>&rdquo;, and the value continues until the next line that begins in the
1089       left-hand column, or the end of file.</para>
1090
1091     <para>The syntax of the value depends on the field.   The various field
1092       types are:</para>
1093
1094     <variablelist>
1095       <varlistentry>
1096         <term>freeform</term>
1097         <listitem>
1098           <para>Any arbitrary string, no interpretation or parsing is
1099             done.</para>
1100         </listitem>
1101       </varlistentry>
1102       <varlistentry>
1103         <term>string</term>
1104         <listitem>
1105           <para>A sequence of non-space characters, or a sequence of arbitrary
1106             characters surrounded by quotes <literal>"...."</literal>.</para>
1107         </listitem>
1108       </varlistentry>
1109       <varlistentry>
1110         <term>string list</term>
1111         <listitem>
1112           <para>A sequence of strings, separated by commas.  The sequence may
1113             be empty.</para>
1114         </listitem>
1115       </varlistentry>
1116     </variablelist>
1117
1118     <para>In addition, there are some fields with special syntax (e.g. package
1119       names, version, dependencies).</para>
1120
1121     <para>The allowed fields, with their types, are:</para>
1122
1123     <variablelist>
1124       <varlistentry>
1125         <term>
1126           <literal>name</literal>
1127           <indexterm><primary><literal>name</literal></primary><secondary>package specification</secondary></indexterm>
1128         </term>
1129         <listitem>
1130           <para>The package's name (without the version).</para>
1131         </listitem>
1132       </varlistentry>
1133
1134       <varlistentry>
1135         <term>
1136           <literal>id</literal>
1137           <indexterm><primary><literal>id</literal></primary><secondary>package specification</secondary></indexterm>
1138         </term>
1139         <listitem>
1140           <para>The package's unique identifier.  It is up to you to
1141           choose a suitable one.</para>
1142         </listitem>
1143       </varlistentry>
1144
1145       <varlistentry>
1146         <term>
1147           <literal>version</literal>
1148           <indexterm><primary><literal>version</literal></primary><secondary>package specification</secondary></indexterm>
1149         </term>
1150         <listitem>
1151           <para>The package's version, usually in the form
1152             <literal>A.B</literal> (any number of components are allowed).</para>
1153         </listitem>
1154       </varlistentry>
1155
1156       <varlistentry>
1157         <term>
1158           <literal>license</literal>
1159           <indexterm><primary><literal>auto</literal></primary><secondary>package specification</secondary></indexterm>
1160         </term>
1161         <listitem>
1162           <para>(string) The type of license under which this package is distributed.
1163             This field is a value of the <ulink
1164         url="../libraries/Cabal/Distribution-License.html#t:License"><literal>License</literal></ulink> type.</para>
1165         </listitem>
1166       </varlistentry>
1167
1168         <varlistentry>
1169           <term>
1170             <literal>license-file</literal>
1171             <indexterm><primary><literal>license-file</literal></primary><secondary>package specification</secondary></indexterm>
1172           </term>
1173           <listitem>
1174             <para>(optional string) The name of a file giving detailed license
1175             information for this package.</para>
1176           </listitem>
1177         </varlistentry>
1178
1179         <varlistentry>
1180           <term>
1181             <literal>copyright</literal>
1182             <indexterm><primary><literal>copyright</literal></primary><secondary>package specification</secondary></indexterm>
1183           </term>
1184           <listitem>
1185             <para>(optional freeform) The copyright string.</para>
1186           </listitem>
1187         </varlistentry>
1188
1189         <varlistentry>
1190           <term>
1191             <literal>maintainer</literal>
1192             <indexterm><primary><literal>maintainer</literal></primary><secondary>package specification</secondary></indexterm>
1193           </term>
1194           <listitem>
1195             <para>(optinoal freeform) The email address of the package's maintainer.</para>
1196           </listitem>
1197         </varlistentry>
1198
1199         <varlistentry>
1200           <term>
1201             <literal>stability</literal>
1202             <indexterm><primary><literal>stability</literal></primary><secondary>package specification</secondary></indexterm>
1203           </term>
1204           <listitem>
1205             <para>(optional freeform) A string describing the stability of the package
1206             (eg. stable, provisional or experimental).</para>
1207           </listitem>
1208         </varlistentry>
1209
1210         <varlistentry>
1211           <term>
1212             <literal>homepage</literal>
1213             <indexterm><primary><literal>homepage</literal></primary><secondary>package specification</secondary></indexterm>
1214           </term>
1215           <listitem>
1216             <para>(optional freeform) URL of the package's home page.</para>
1217           </listitem>
1218         </varlistentry>
1219
1220       <varlistentry>
1221         <term>
1222             <literal>package-url</literal>
1223             <indexterm><primary><literal>package-url</literal></primary><secondary>package specification</secondary></indexterm>
1224           </term>
1225           <listitem>
1226             <para>(optional freeform) URL of a downloadable distribution for this
1227             package.  The distribution should be a Cabal package.</para>
1228           </listitem>
1229         </varlistentry>
1230
1231         <varlistentry>
1232           <term>
1233             <literal>description</literal>
1234             <indexterm><primary><literal>description</literal></primary><secondary>package specification</secondary></indexterm>
1235           </term>
1236           <listitem>
1237             <para>(optional freeform) Description of the package.</para>
1238           </listitem>
1239         </varlistentry>
1240
1241       <varlistentry>
1242           <term>
1243             <literal>category</literal>
1244             <indexterm><primary><literal>category</literal></primary><secondary>package specification</secondary></indexterm>
1245           </term>
1246           <listitem>
1247             <para>(optinoal freeform) Which category the package belongs to.  This field
1248             is for use in conjunction with a future centralised package
1249             distribution framework, tentatively titled Hackage.</para>
1250           </listitem>
1251         </varlistentry>
1252
1253         <varlistentry>
1254           <term>
1255             <literal>author</literal>
1256             <indexterm><primary><literal>author</literal></primary><secondary>package specification</secondary></indexterm>
1257           </term>
1258           <listitem>
1259             <para>(optional freeform) Author of the package.</para>
1260           </listitem>
1261         </varlistentry>
1262
1263         <varlistentry>
1264           <term>
1265             <literal>exposed</literal>
1266             <indexterm><primary><literal>exposed</literal></primary><secondary>package specification</secondary></indexterm>
1267           </term>
1268           <listitem>
1269             <para>(bool) Whether the package is exposed or not.</para>
1270           </listitem>
1271         </varlistentry>
1272
1273         <varlistentry>
1274           <term>
1275             <literal>exposed-modules</literal>
1276             <indexterm><primary><literal>exposed-modules</literal></primary><secondary>package specification</secondary></indexterm>
1277           </term>
1278           <listitem>
1279             <para>(string list) modules exposed by this package.</para>
1280           </listitem>
1281         </varlistentry>
1282
1283         <varlistentry>
1284           <term>
1285             <literal>hidden-modules</literal>
1286             <indexterm><primary><literal>hidden-modules</literal></primary><secondary>package specification</secondary></indexterm>
1287           </term>
1288           <listitem>
1289             <para>(string list) modules provided by this package,
1290             but not exposed to the programmer.  These modules cannot be
1291             imported, but they are still subject to the overlapping constraint:
1292             no other package in the same program may provide a module of the
1293             same name.</para>
1294         </listitem>
1295         </varlistentry>
1296
1297         <varlistentry>
1298           <term>
1299             <literal>import-dirs</literal>
1300             <indexterm><primary><literal>import-dirs</literal></primary><secondary>package specification</secondary></indexterm>
1301           </term>
1302           <listitem>
1303             <para>(string list) A list of directories containing interface files
1304             (<literal>.hi</literal> files) for this package.</para>
1305
1306             <para>If the package contains profiling libraries, then
1307             the interface files for those library modules should have
1308             the suffix <literal>.p_hi</literal>.  So the package can
1309             contain both normal and profiling versions of the same
1310             library without conflict (see also
1311             <literal>library_dirs</literal> below).</para>
1312           </listitem>
1313         </varlistentry>
1314
1315         <varlistentry>
1316           <term>
1317             <literal>library-dirs</literal>
1318             <indexterm><primary><literal>library-dirs</literal></primary><secondary>package specification</secondary></indexterm>
1319           </term>
1320           <listitem>
1321             <para>(string list) A list of directories containing libraries for this
1322             package.</para>
1323           </listitem>
1324         </varlistentry>
1325
1326         <varlistentry>
1327           <term>
1328             <literal>hs-libraries</literal>
1329             <indexterm><primary><literal>hs-libraries</literal></primary><secondary>package specification</secondary></indexterm>
1330           </term>
1331           <listitem>
1332             <para>(string list) A list of libraries containing Haskell code for this
1333             package, with the <literal>.a</literal> or
1334             <literal>.dll</literal> suffix omitted.  When packages are
1335             built as libraries, the
1336             <literal>lib</literal> prefix is also omitted.</para>
1337
1338             <para>For use with GHCi, each library should have an
1339             object file too.  The name of the object file does
1340             <emphasis>not</emphasis> have a <literal>lib</literal>
1341             prefix, and has the normal object suffix for your
1342             platform.</para>
1343
1344             <para>For example, if we specify a Haskell library as
1345             <filename>HSfoo</filename> in the package spec, then the
1346             various flavours of library that GHC actually uses will be
1347             called:</para>
1348             <variablelist>
1349               <varlistentry>
1350                 <term><filename>libHSfoo.a</filename></term>
1351                 <listitem>
1352                   <para>The name of the library on Unix and Windows
1353                   (mingw) systems.  Note that we don't support
1354                   building dynamic libraries of Haskell code on Unix
1355                   systems.</para>
1356                 </listitem>
1357               </varlistentry>
1358               <varlistentry>
1359                 <term><filename>HSfoo.dll</filename></term>
1360                 <listitem>
1361                   <para>The name of the dynamic library on Windows
1362                   systems (optional).</para>
1363                 </listitem>
1364               </varlistentry>
1365               <varlistentry>
1366                 <term><filename>HSfoo.o</filename></term>
1367                 <term><filename>HSfoo.obj</filename></term>
1368                 <listitem>
1369                   <para>The object version of the library used by
1370                   GHCi.</para>
1371                 </listitem>
1372               </varlistentry>
1373             </variablelist>
1374           </listitem>
1375         </varlistentry>
1376
1377         <varlistentry>
1378           <term>
1379             <literal>extra-libraries</literal>
1380             <indexterm><primary><literal>extra-libraries</literal></primary><secondary>package specification</secondary></indexterm>
1381           </term>
1382           <listitem>
1383             <para>(string list) A list of extra libraries for this package.  The
1384             difference between <literal>hs-libraries</literal> and
1385             <literal>extra-libraries</literal> is that
1386             <literal>hs-libraries</literal> normally have several
1387             versions, to support profiling, parallel and other build
1388             options.  The various versions are given different
1389             suffixes to distinguish them, for example the profiling
1390             version of the standard prelude library is named
1391             <filename>libHSbase_p.a</filename>, with the
1392             <literal>_p</literal> indicating that this is a profiling
1393             version.  The suffix is added automatically by GHC for
1394             <literal>hs-libraries</literal> only, no suffix is added
1395             for libraries in
1396             <literal>extra-libraries</literal>.</para>
1397
1398             <para>The libraries listed in
1399             <literal>extra-libraries</literal> may be any libraries
1400             supported by your system's linker, including dynamic
1401             libraries (<literal>.so</literal> on Unix,
1402             <literal>.DLL</literal> on Windows).</para>
1403
1404             <para>Also, <literal>extra-libraries</literal> are placed
1405             on the linker command line after the
1406             <literal>hs-libraries</literal> for the same package.  If
1407             your package has dependencies in the other direction (i.e.
1408             <literal>extra-libraries</literal> depends on
1409             <literal>hs-libraries</literal>), and the libraries are
1410             static, you might need to make two separate
1411             packages.</para>
1412           </listitem>
1413         </varlistentry>
1414
1415         <varlistentry>
1416           <term>
1417             <literal>include-dirs</literal>
1418             <indexterm><primary><literal>include-dirs</literal></primary><secondary>package specification</secondary></indexterm>
1419           </term>
1420           <listitem>
1421             <para>(string list) A list of directories containing C includes for this
1422             package.</para>
1423           </listitem>
1424         </varlistentry>
1425
1426         <varlistentry>
1427           <term>
1428            <literal>includes</literal>
1429            <indexterm><primary><literal>includes</literal></primary><secondary>package specification</secondary></indexterm>
1430           </term>
1431           <listitem>
1432             <para>(string list) A list of files to include for via-C compilations
1433             using this package.  Typically the include file(s) will
1434             contain function prototypes for any C functions used in
1435             the package, in case they end up being called as a result
1436             of Haskell functions from the package being
1437             inlined.</para>
1438           </listitem>
1439         </varlistentry>
1440
1441         <varlistentry>
1442           <term>
1443             <literal>depends</literal>
1444             <indexterm><primary><literal>depends</literal></primary><secondary>package specification</secondary></indexterm>
1445           </term>
1446           <listitem>
1447             <para>(package id list) Packages on which this package
1448             depends.</para>
1449           </listitem>
1450         </varlistentry>
1451
1452         <varlistentry>
1453           <term>
1454             <literal>hugs-options</literal>
1455             <indexterm><primary><literal>hugs-options</literal></primary><secondary>package specification</secondary></indexterm>
1456           </term>
1457           <listitem>
1458             <para>(string list) Options to pass to Hugs for this package.</para>
1459           </listitem>
1460         </varlistentry>
1461
1462         <varlistentry>
1463           <term>
1464             <literal>cc-options</literal>
1465             <indexterm><primary><literal>cc-options</literal></primary><secondary>package specification</secondary></indexterm>
1466           </term>
1467           <listitem>
1468             <para>(string list) Extra arguments to be added to the gcc command line
1469             when this package is being used (only for via-C
1470             compilations).</para>
1471           </listitem>
1472         </varlistentry>
1473
1474         <varlistentry>
1475           <term>
1476             <literal>ld-options</literal>
1477             <indexterm><primary><literal>ld-options</literal></primary><secondary>package specification</secondary></indexterm>
1478           </term>
1479           <listitem>
1480             <para>(string list) Extra arguments to be added to the
1481             <command>gcc</command> command line (for linking) when
1482             this package is being used.</para>
1483           </listitem>
1484         </varlistentry>
1485
1486         <varlistentry>
1487           <term>
1488             <literal>framework-dirs</literal>
1489             <indexterm><primary><literal>framework-dirs</literal></primary><secondary>package specification</secondary></indexterm>
1490           </term>
1491           <listitem>
1492             <para>(string list) On Darwin/MacOS X, a list of directories containing
1493             frameworks for this package. This corresponds to the
1494             <option>-framework-path</option> option. It is ignored on all other
1495             platforms.</para>
1496           </listitem>
1497         </varlistentry>
1498
1499         <varlistentry>
1500           <term>
1501             <literal>frameworks</literal>
1502             <indexterm><primary><literal>frameworks</literal></primary><secondary>package specification</secondary></indexterm>
1503           </term>
1504           <listitem>
1505             <para>(string list) On Darwin/MacOS X, a list of frameworks to link to. This
1506             corresponds to the <option>-framework</option> option. Take a look
1507             at Apple's developer documentation to find out what frameworks
1508             actually are. This entry is ignored on all other platforms.</para>
1509           </listitem>
1510         </varlistentry>
1511
1512         <varlistentry>
1513           <term>
1514             <literal>haddock-interfaces</literal>
1515             <indexterm><primary><literal>haddock-interfaces</literal></primary><secondary>package specification</secondary></indexterm>
1516           </term>
1517           <listitem>
1518             <para>(string list) A list of filenames containing <ulink
1519               url="http://www.haskell.org/haddock/">Haddock</ulink> interface
1520             files (<literal>.haddock</literal> files) for this package.</para>
1521           </listitem>
1522         </varlistentry>
1523
1524         <varlistentry>
1525           <term>
1526             <literal>haddock-html</literal>
1527             <indexterm><primary><literal>haddock-html</literal></primary><secondary>package specification</secondary></indexterm>
1528           </term>
1529           <listitem>
1530             <para>(optional string) The directory containing the Haddock-generated HTML
1531             for this package.</para>
1532           </listitem>
1533         </varlistentry>
1534       </variablelist>
1535
1536 <!--  This isn't true any more.  I'm not sure if we still need it -SDM
1537       <para>
1538       The <literal>ghc-pkg</literal> tool performs expansion of
1539       environment variables occurring in input package specifications.
1540       So, if the <literal>mypkg</literal> was added to the package
1541       database as follows:
1542       </para>
1543 <screen>
1544   $ installdir=/usr/local/lib ghc-pkg -a &lt; mypkg.pkg
1545 </screen>
1546
1547       <para>
1548       The occurrence of <literal>${installdir}</literal> is replaced
1549       with <literal>/usr/local/lib</literal> in the package data that
1550       is added for <literal>mypkg</literal>.
1551       </para>
1552
1553       <para>
1554       This feature enables the distribution of package specification
1555       files that can be easily configured when installing.
1556       </para>
1557
1558       <para>For examples of more package specifications, take a look
1559       at the <literal>package.conf</literal> in your GHC
1560       installation.</para>
1561
1562 -->
1563
1564     </sect2>
1565   </sect1>
1566
1567 <!-- Emacs stuff:
1568      ;;; Local Variables: ***
1569      ;;; mode: xml ***
1570      ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter" "sect1") ***
1571      ;;; End: ***
1572  -->