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