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