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