ghc/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 compiler.  GHC
   9     comes with several packages: see the accompanying
  10     <ulink url="../libraries/index.html">library documentation</ulink>.</para>
  11
  12   <para>Using a package couldn't be simpler: if you're using
  13     <option>--make</option> or GHCi, then most of the installed packages will be
  14     automatically available to your program without any further options.  The
  15     exceptions to this rule are covered below in <xref
  16       linkend="using-packages" />.</para>
  17
  18   <para>Building your own packages is also quite straightforward: we provide
  19     the <ulink url="http://www.haskell.org/cabal/">Cabal</ulink> infrastructure which
  20     automates the process of configuring, building, installing and distributing
  21     a package.  All you need to do is write a simple configuration file, put a
  22     few files in the right places, and you have a package.  See the
  23     <ulink url="../Cabal/index.html">Cabal documentation</ulink>
  24     for details, and also the Cabal libraries (<ulink url="../libraries/Cabal/Distribution.Simple.html">Distribution.Simple</ulink>,
  25     for example).</para>
  26
  27   <sect2 id="using-packages">
  28   <title>Using Packages
  29   </title>
  30     <indexterm><primary>packages</primary>
  31       <secondary>using</secondary></indexterm>
  32
  33     <para>To see which packages are installed, use the
  34       <literal>ghc-pkg</literal> command:</para>
  35
  36 <screen>
  37 $ ghc-pkg list
  38 /usr/lib/ghc-6.4/package.conf:
  39     base-1.0, haskell98-1.0, template-haskell-1.0, mtl-1.0, unix-1.0,
  40     Cabal-1.0, haskell-src-1.0, parsec-1.0, network-1.0,
  41     QuickCheck-1.0, HUnit-1.1, fgl-1.0, X11-1.1, HGL-3.1, OpenGL-2.0,
  42     GLUT-2.0, stm-1.0, readline-1.0, (lang-1.0), (concurrent-1.0),
  43     (posix-1.0), (util-1.0), (data-1.0), (text-1.0), (net-1.0),
  44     (hssource-1.0), rts-1.0
  45       </screen>
  46
  47     <para>Packages are either exposed or hidden.  Only
  48       modules from exposed packages may be imported by your Haskell code; if
  49       you try to import a module from a hidden package, GHC will emit an error
  50       message.</para>
  51
  52     <para>Each package has an exposed flag, which says whether it is exposed by
  53       default or not.  Packages hidden by default are listed in
  54       parentheses (eg. <literal>(lang-1.0)</literal>) in the output from
  55       <literal>ghc-pkg list</literal>.  To expose a package which is hidden by
  56       default, use the <option>-package</option>
  57       flag (see below).</para>
  58
  59    <para>To see which modules are exposed by a package:</para>
  60
  61 <screen>
  62 $ ghc-pkg field network exposed-modules
  63 exposed-modules: Network.BSD,
  64                  Network.CGI,
  65                  Network.Socket,
  66                  Network.URI,
  67                  Network
  68 </screen>
  69
  70     <para>In general, packages containing hierarchical modules are usually
  71       exposed by default.  However, it is possible for two packages to contain
  72       the same module: in this case, only one of the packages can be
  73       exposed.  This might happen if you have two versions of the same package
  74       installed, for example.  The general rule is:</para>
  75
  76     <blockquote><para>There must be no overlaps in the modules provided by all
  77         of the exposed packages, and the packages they depend on, and so
  78         on.</para></blockquote>
  79
  80     <para>The GHC command line options that control packages are:</para>
  81
  82     <variablelist>
  83       <varlistentry>
  84         <term>
  85           <option>-package <replaceable>P</replaceable></option>
  86           <indexterm><primary><option>-package</option></primary></indexterm>
  87         </term>
  88         <listitem>
  89           <para>This option causes package <replaceable>P</replaceable> to be
  90             exposed.  The package <replaceable>P</replaceable> can be specified
  91             in full with its version number
  92             (e.g. <literal>network-1.0</literal>) or the version number can be
  93             omitted if there is only one version of the package
  94             installed.</para>
  95
  96           <para>If there are multiple versions of <replaceable>P</replaceable>
  97             installed, then all other versions will become hidden.</para>
  98
  99           <para>The <option>-package <replaceable>P</replaceable></option>
 100             option also causes package <replaceable>P</replaceable> to be
 101             linked into the resulting executable.  In
 102             <option>&ndash;&ndash;make</option> mode and GHCi, the compiler
 103             normally determines which packages are required by the current
 104             Haskell modules, and links only those.  In batch mode however, the
 105             dependency information isn't available, and explicit
 106             <option>-package</option> options must be given when linking.</para>
 107
 108           <para>For example, to link a program consisting of objects
 109             <filename>Foo.o</filename> and <filename>Main.o</filename>, where
 110             we made use of the <literal>network</literal> package, we need to
 111             give GHC the <literal>-package</literal> flag thus:
 112
 113 <screen>$ ghc -o myprog Foo.o Main.o -package network</screen>
 114
 115             The same flag is necessary even if we compiled the modules from
 116             source, because GHC still reckons it's in batch mode:
 117
 118 <screen>$ ghc -o myprog Foo.hs Main.hs -package network</screen>
 119
 120             In <literal>--make</literal> and <literal>--interactive</literal>
 121             modes (<xref linkend="modes" />), however, GHC figures out the
 122             packages required for linking without further assistance.</para>
 123
 124           <para>The one other time you might need to use
 125             <option>-package</option> to force linking a package is when the
 126             package does not contain any Haskell modules (it might contain a C
 127             library only, for example).  In that case, GHC
 128             will never discover a dependency on it, so it has to be mentioned
 129             explicitly.</para>
 130         </listitem>
 131       </varlistentry>
 132
 133       <varlistentry>
 134         <term><option>-hide-all-packages</option>
 135         <indexterm><primary><option>-hide-package</option></primary>
 136           </indexterm></term>
 137         <listitem>
 138           <para>Ignore the exposed flag on installed packages, and hide them
 139             all by default.  If you use
 140             this flag, then any packages you require (including
 141             <literal>base</literal>) need to be explicitly exposed using
 142             <option>-package</option> options.</para>
 143
 144           <para>This is a good way to insulate your program from differences
 145             in the globally exposed packages, and being explicit about package
 146             dependencies is a Good Thing.</para>
 147         </listitem>
 148       </varlistentry>
 149
 150       <varlistentry>
 151         <term><option>-hide-package</option> <replaceable>P</replaceable>
 152         <indexterm><primary><option>-hide-package</option></primary>
 153           </indexterm></term>
 154         <listitem>
 155           <para>This option does the opposite of <option>-package</option>: it
 156             causes the specified package to be <firstterm>hidden</firstterm>,
 157             which means that none of its modules will be available for import
 158             by Haskell <literal>import</literal> directives.</para>
 159
 160           <para>Note that the package might still end up being linked into the
 161             final program, if it is a dependency (direct or indirect) of
 162             another exposed package.</para>
 163         </listitem>
 164       </varlistentry>
 165
 166       <varlistentry>
 167         <term><option>-ignore-package</option> <replaceable>P</replaceable>
 168         <indexterm><primary><option>-ignore-package</option></primary>
 169           </indexterm></term>
 170         <listitem>
 171           <para>Causes the compiler to behave as if package
 172             <replaceable>P</replaceable> is not installed at all.  This is not
 173             the same as <option>-hide-package</option>, because under
 174             <option>-hide-package</option> the package might still be present
 175             in the program if another package depends on it.</para>
 176
 177           <para><option>-ignore-package</option> <replaceable>P</replaceable>
 178             not only causes package <replaceable>P</replaceable> to be removed,
 179             but also everything that depends on <replaceable>P</replaceable>,
 180             and so on.</para>
 181
 182           <para>Why do we need <option>-ignore-package</option>?  Well, it is
 183             particularly useful when you're actually compiling package
 184             <replaceable>P</replaceable> itself.  The compiler will refuse to
 185             compile module <replaceable>M</replaceable> if
 186             <replaceable>M</replaceable> is already part of a package.  So we
 187             might try <option>-hide-package</option>
 188             <replaceable>P</replaceable>; but then if
 189             <replaceable>P</replaceable> is a dependency of another package
 190             <replaceable>P'</replaceable> we would have to
 191             <option>-hide-package</option> <replaceable>P'</replaceable> too;
 192             and the author of the code can't know in advance which packages are
 193             installed on the system and hence which
 194             <option>-hide-package</option> flags are required.  So, we provide
 195             <option>-ignore-package</option> which does the Right Thing.</para>
 196         </listitem>
 197       </varlistentry>
 198     </variablelist>
 199   </sect2>
 200
 201   <sect2 id="package-databases">
 202     <title>Package Databases</title>
 203
 204     <para>A package database is a file, normally called
 205       <literal>package.conf</literal> which contains descriptions of installed
 206       packages.  GHC usually knows about two package databases:</para>
 207
 208     <itemizedlist>
 209       <listitem>
 210         <para>The global package database, which comes with your GHC
 211           installation.</para>
 212       </listitem>
 213       <listitem>
 214         <para>A package database private to each user.  On Unix
 215           systems this will be
 216           <filename>$HOME/.ghc/<replaceable>arch</replaceable>-<replaceable>os</replaceable>-<replaceable>version</replaceable>/package.conf</filename>, and on
 217           Windows it will be something like
 218           <filename>C:\Documents&nbsp;And&nbsp;Settings\<replaceable>user</replaceable>\ghc</filename>.
 219           The <literal>ghc-pkg</literal> tool knows where this file should be
 220           located, and will create it if it doesn't exist (see <xref
 221             linkend="package-management" />).</para>
 222       </listitem>
 223     </itemizedlist>
 224
 225     <para>When GHC starts up, it reads the contents of these two package
 226       databases, and builds up a list of the packages it knows about.  You can
 227       see GHC's package table by running GHC with the <option>-v</option>
 228       flag.</para>
 229
 230     <para>Package databases may overlap: for example, packages in the user
 231       database will override those of the same name in the global
 232       database.</para>
 233
 234     <para>You can control the loading of package databses using the following
 235       GHC options:</para>
 236
 237     <variablelist>
 238       <varlistentry>
 239         <term>
 240           <option>-package-conf <replaceable>file</replaceable></option>
 241           <indexterm><primary><option>-package-conf</option></primary></indexterm>
 242         </term>
 243         <listitem>
 244           <para>Read in the package configuration file
 245             <replaceable>file</replaceable> in addition to the system
 246             default file and the user's local file.  Packages in additional
 247             files read this way will override those in the global and user
 248             databases.</para>
 249         </listitem>
 250       </varlistentry>
 251
 252       <varlistentry>
 253         <term><option>-no-user-package-conf</option>
 254           <indexterm><primary><option>-no-user-package-conf</option></primary>
 255           </indexterm>
 256         </term>
 257         <listitem>
 258           <para>Prevent loading of the user's local package database.</para>
 259         </listitem>
 260       </varlistentry>
 261     </variablelist>
 262
 263     <para>To create a new package database, just create
 264       a new file and put the string
 265       <quote><literal>[]</literal></quote> in it.  Packages can be
 266       added to the file using the
 267       <literal>ghc-pkg</literal> tool, described in <xref
 268       linkend="package-management"/>.</para>
 269   </sect2>
 270
 271   <sect2 id="building-packages">
 272     <title>Building a package from Haskell source</title>
 273     <indexterm><primary>packages</primary>
 274       <secondary>building</secondary></indexterm>
 275
 276     <para>We don't recommend building packages the hard way.  Instead, use the
 277       <ulink url="../Cabal/index.html">Cabal</ulink> infrastructure
 278       if possible.  If your package is particularly complicated or requires a
 279       lot of configuration, then you might have to fall back to the low-level
 280       mechanisms, so a few hints for those brave souls follow.</para>
 281
 282     <itemizedlist>
 283       <listitem>
 284         <para>You need to build an "installed package info" file for
 285           passing to <literal>ghc-pkg</literal> when installing your
 286           package.  The contents of this file are described in <xref
 287             linkend="installed-pkg-info" />.</para>
 288       </listitem>
 289
 290       <listitem>
 291         <para>The Haskell code in a package may be built into one or
 292           more archive libraries
 293           (e.g. <filename>libHSfoo.a</filename>), or a single DLL on
 294           Windows (e.g. <filename>HSfoo.dll</filename>).  The
 295           restriction to a single DLL on Windows is because the
 296           package system is used to tell the compiler when it should
 297           make an inter-DLL call rather than an intra-DLL call
 298           (inter-DLL calls require an extra
 299           indirection). <emphasis>Building packages as DLLs doesn't
 300           work at the moment; see <xref linkend="win32-dlls-create"/>
 301           for the gory details.</emphasis>
 302           </para>
 303
 304         <para>Building a static library is done by using the
 305           <literal>ar</literal> tool, like so:</para>
 306
 307 <screen>ar cqs libHSfoo.a A.o B.o C.o ...</screen>
 308
 309         <para>where <filename>A.o</filename>,
 310           <filename>B.o</filename> and so on are the compiled Haskell
 311           modules, and <filename>libHSfoo.a</filename> is the library
 312           you wish to create.  The syntax may differ slightly on your
 313           system, so check the documentation if you run into
 314           difficulties.</para>
 315
 316         <para>Versions of the Haskell libraries for use with GHCi
 317           may also be included: GHCi cannot load <literal>.a</literal>
 318           files directly, instead it will look for an object file
 319           called <filename>HSfoo.o</filename> and load that.  On some
 320           systems, the <literal>ghc-pkg</literal> tool can
 321           automatically build the GHCi version of each library, see
 322           <xref linkend="package-management"/>.  To build these
 323           libraries by hand from the <literal>.a</literal> archive, it
 324           is possible to use GNU <command>ld</command> as
 325           follows:</para>
 326
 327 <screen>ld -r &ndash;&ndash;whole-archive -o HSfoo.o libHSfoo.a</screen>
 328
 329         <para>(replace
 330           <literal>&ndash;&ndash;--whole-archive</literal> with
 331           <literal>&ndash;all_load</literal> on MacOS X)</para>
 332
 333           <para>GHC does not maintain detailed cross-package
 334           dependency information.  It does remember which modules in
 335           other packages the current module depends on, but not which
 336           things within those imported things.</para>
 337       </listitem>
 338
 339       <listitem>
 340         <para>When compiling a Haskell module which is to be part of a new package
 341           <replaceable>P</replaceable>, use
 342           <option>-ignore-package</option>&nbsp;<replaceable>P</replaceable>.</para>
 343       </listitem>
 344     </itemizedlist>
 345
 346     <para>It is worth noting that on Windows, when each package
 347       is built as a DLL, since a reference to a DLL costs an extra
 348       indirection, intra-package references are cheaper than
 349       inter-package references. Of course, this applies to the
 350       <filename>Main</filename> package as well.</para>
 351     </sect2>
 352
 353   <sect2 id="package-management">
 354     <title>Package management (the <literal>ghc-pkg</literal> command)</title>
 355     <indexterm><primary>packages</primary>
 356       <secondary>management</secondary></indexterm>
 357
 358     <para>The <literal>ghc-pkg</literal> tool allows packages to be
 359       added or removed from a package database.  By default,
 360       the system-wide package database is modified, but alternatively
 361       the user's local package database or another specified
 362       file can be used.</para>
 363
 364     <para>Commands which only inspect the database (<literal>list</literal>,
 365       <literal>describe</literal>, <literal>field</literal>) will take into
 366       account the user's local package database too, unless the
 367       <literal>--global</literal> option is given.  This matches the behaviour
 368       of GHC, which automatically reads the user's local database if it is
 369       available.</para>
 370
 371     <para>The <literal>ghc-pkg</literal> program may be run in the ways listed
 372       below.  Where a package name is required, the package can be named in
 373       full including the version number
 374       (e.g. <literal>network-1.0</literal>), or without the version number if
 375       there is only a single version of that package installed.  Additionally,
 376       the version may be given as <literal>*</literal>, which means &ldquo;all
 377       versions&rdquo;.  For example, <literal>ghc-pkg hide network-*</literal>
 378       would hide all versions of the network package.</para>
 379
 380     <variablelist>
 381       <varlistentry>
 382         <term><literal>ghc-pkg register <replaceable>file</replaceable></literal></term>
 383         <listitem>
 384           <para>Reads a package specification from
 385             <replaceable>file</replaceable> (which may be &ldquo;<literal>-</literal>&rdquo;
 386             to indicate standard input),
 387             and adds it to the database of installed packages.  The syntax of
 388             <replaceable>file</replaceable> is given in <xref
 389               linkend="installed-pkg-info" />.</para>
 390
 391           <para>The package specification must be a package that isn't already
 392             installed.</para>
 393         </listitem>
 394       </varlistentry>
 395
 396       <varlistentry>
 397         <term><literal>ghc-pkg update <replaceable>file</replaceable></literal></term>
 398         <listitem>
 399           <para>The same as <literal>register</literal>, except that if a
 400             package of the same name is already installed, it is
 401             replaced by the new one.</para>
 402         </listitem>
 403       </varlistentry>
 404
 405       <varlistentry>
 406         <term><literal>ghc-pkg unregister <replaceable>P</replaceable></literal></term>
 407         <listitem>
 408           <para>Remove the specified package from the database.</para>
 409         </listitem>
 410       </varlistentry>
 411
 412       <varlistentry>
 413         <term><literal>ghc-pkg expose <replaceable>P</replaceable></literal></term>
 414         <listitem>
 415           <para>Sets the <literal>exposed</literal> flag for package
 416             <replaceable>P</replaceable> to <literal>True</literal>.</para>
 417         </listitem>
 418       </varlistentry>
 419
 420       <varlistentry>
 421         <term><literal>ghc-pkg hide <replaceable>P</replaceable></literal></term>
 422         <listitem>
 423           <para>Sets the <literal>exposed</literal> flag for package
 424             <replaceable>P</replaceable> to <literal>False</literal>.</para>
 425         </listitem>
 426       </varlistentry>
 427
 428       <varlistentry>
 429         <term><literal>ghc-pkg list</literal></term>
 430         <listitem>
 431           <para>This option displays the currently installed
 432             packages, for each of the databases known to
 433             <literal>ghc-pkg</literal>.  That includes the global database, the
 434             user's local database (if <option>--user</option> is given), and
 435             any further files specified using the <option>-f</option> option on
 436             the command line.</para>
 437
 438           <para>Hidden packages (those for which the <literal>exposed</literal>
 439             flag is <literal>False</literal>) are shown in parentheses in the
 440             list of packages.</para>
 441         </listitem>
 442       </varlistentry>
 443
 444       <varlistentry>
 445         <term><literal>ghc-pkg describe <replaceable>P</replaceable></literal></term>
 446         <listitem>
 447           <para>Emit the full description of the specified package.  The
 448             description is in the form of an
 449             <literal>InstalledPackageInfo</literal>, the same as the input file
 450             format for <literal>ghc-pkg register</literal>.  See <xref
 451               linkend="installed-pkg-info" /> for details.</para>
 452         </listitem>
 453       </varlistentry>
 454
 455       <varlistentry>
 456         <term><literal>ghc-pkg field <replaceable>P</replaceable> <replaceable>field</replaceable></literal></term>
 457         <listitem>
 458           <para>Show just a single field of the installed package description
 459             for <literal>P</literal>.</para>
 460         </listitem>
 461       </varlistentry>
 462     </variablelist>
 463
 464     <para>Additionally, the following flags are accepted by
 465       <literal>ghc-pkg</literal>:</para>
 466
 467     <variablelist>
 468       <varlistentry>
 469         <term>
 470           <option>&ndash;&ndash;auto-ghci-libs</option><indexterm><primary><option>&ndash;&ndash;user</option></primary>
 471           </indexterm>
 472         </term>
 473         <listitem>
 474           <para>Automatically generate the GHCi
 475             <filename>.o</filename> version of each
 476             <filename>.a</filename> Haskell library, using GNU ld (if
 477             that is available).  Without this option,
 478             <literal>ghc-pkg</literal> will warn if GHCi versions of
 479             any Haskell libraries in the package don't exist.</para>
 480
 481             <para>GHCi <literal>.o</literal> libraries don't
 482             necessarily have to live in the same directory as the
 483             corresponding <literal>.a</literal> library.  However,
 484             this option will cause the GHCi library to be created in
 485             the same directory as the <literal>.a</literal>
 486             library.</para>
 487         </listitem>
 488       </varlistentry>
 489
 490       <varlistentry>
 491         <term>
 492           <option>-f</option> <replaceable>file</replaceable>
 493           <indexterm><primary><option>-f</option></primary>
 494           </indexterm>
 495         </term>
 496         <term>
 497           <option>-package-conf</option> <replaceable>file</replaceable>
 498           <indexterm><primary><option>-package-conf</option></primary>
 499           </indexterm>
 500         </term>
 501         <listitem>
 502           <para>Operate on the package database in
 503             <replaceable>file</replaceable>.</para>
 504
 505           <para>When multiple <option>-f</option> options are given, or
 506             <option>-f</option> is used in conjunction with
 507             <option>--user</option> or <option>--global</option>, the last
 508             one on the command-line is the one that will be modified.</para>
 509         </listitem>
 510       </varlistentry>
 511
 512       <varlistentry>
 513         <term>
 514           <option>&ndash;&ndash;force</option>
 515           <indexterm><primary>
 516               <option>&ndash;&ndash;force</option>
 517             </primary></indexterm>
 518         </term>
 519         <listitem>
 520           <para>Causes <literal>ghc-pkg</literal> to ignore missing
 521             dependencies, directories and libraries when registering a package,
 522             and just go ahead and add it anyway.  This might be useful if your
 523             package installation system needs to add the package to
 524             GHC before building and installing the files.</para>
 525         </listitem>
 526       </varlistentry>
 527
 528       <varlistentry>
 529         <term>
 530           <option>&ndash;&ndash;global</option><indexterm><primary><option>&ndash;&ndash;user</option></primary>
 531           </indexterm>
 532         </term>
 533         <listitem>
 534           <para>Operate on the global package database (this is the default).
 535             This flag affects the <literal>register</literal>,
 536             <literal>update</literal>, <literal>unregister</literal>,
 537             <literal>expose</literal>, and <literal>hide</literal>
 538             commands.</para>
 539         </listitem>
 540       </varlistentry>
 541
 542       <varlistentry>
 543         <term>
 544           <option>&ndash;&ndash;help</option><indexterm><primary><option>&ndash;&ndash;user</option></primary>
 545           </indexterm>
 546         </term>
 547         <term>
 548           <option>-?</option><indexterm><primary><option>-?</option></primary>
 549           </indexterm>
 550         </term>
 551         <listitem>
 552           <para>Outputs the command-line syntax.</para>
 553         </listitem>
 554       </varlistentry>
 555
 556       <varlistentry>
 557         <term>
 558           <option>&ndash;&ndash;user</option><indexterm><primary><option>&ndash;&ndash;user</option></primary>
 559           </indexterm>
 560         </term>
 561         <listitem>
 562           <para>Operate on the current user's local package database.
 563             This flag affects the <literal>register</literal>,
 564             <literal>update</literal>, <literal>unregister</literal>,
 565             <literal>expose</literal>, and <literal>hide</literal>
 566             commands.</para>
 567         </listitem>
 568       </varlistentry>
 569
 570       <varlistentry>
 571         <term>
 572           <option>-V</option><indexterm><primary><option>-V</option></primary>
 573           </indexterm>
 574         </term>
 575         <term>
 576           <option>&ndash;&ndash;version</option><indexterm><primary><option>&ndash;&ndash;user</option></primary>
 577           </indexterm>
 578         </term>
 579         <listitem>
 580           <para>Output the <literal>ghc-pkg</literal> version number.</para>
 581         </listitem>
 582       </varlistentry>
 583     </variablelist>
 584
 585     <para>When modifying the package database
 586       <replaceable>file</replaceable>, a copy of the original file is
 587       saved in <replaceable>file</replaceable><literal>.old</literal>,
 588       so in an emergency you can always restore the old settings by
 589       copying the old file back again.</para>
 590
 591   </sect2>
 592
 593   <sect2 id="installed-pkg-info">
 594     <title>
 595       <literal>InstalledPackageInfo</literal>: a package specification
 596     </title>
 597
 598     <para>A package specification is a Haskell record; in particular, it is the
 599       record <ulink
 600         url="../libraries/Cabal/Distribution.InstalledPackageInfo.html#%tInstalledPackageInfo">InstalledPackageInfo</ulink> in the module Distribution.InstalledPackageInfo, which is part of the Cabal package distributed with GHC.</para>
 601
 602     <para>An <literal>InstalledPackageInfo</literal> has a human
 603       readable/writable syntax.  The functions
 604       <literal>parseInstalledPackageInfo</literal> and
 605       <literal>showInstalledPackageInfo</literal> read and write this syntax
 606       respectively.  Here's an example of the
 607       <literal>InstalledPackageInfo</literal> for the <literal>unix</literal> package:</para>
 608
 609 <screen>
 610 $ ghc-pkg describe unix
 611 name: unix
 612 version: 1.0
 613 license: BSD3
 614 copyright:
 615 maintainer: libraries@haskell.org
 616 stability:
 617 homepage:
 618 package-url:
 619 description:
 620 category:
 621 author:
 622 exposed: True
 623 exposed-modules: System.Posix,
 624                  System.Posix.DynamicLinker.Module,
 625                  System.Posix.DynamicLinker.Prim,
 626                  System.Posix.Directory,
 627                  System.Posix.DynamicLinker,
 628                  System.Posix.Env,
 629                  System.Posix.Error,
 630                  System.Posix.Files,
 631                  System.Posix.IO,
 632                  System.Posix.Process,
 633                  System.Posix.Resource,
 634                  System.Posix.Temp,
 635                  System.Posix.Terminal,
 636                  System.Posix.Time,
 637                  System.Posix.Unistd,
 638                  System.Posix.User,
 639                  System.Posix.Signals.Exts
 640 import-dirs: /usr/lib/ghc-6.4/libraries/unix
 641 library-dirs: /usr/lib/ghc-6.4/libraries/unix
 642 hs-libraries: HSunix
 643 extra-libs: HSunix_cbits, dl
 644 include-dirs: /usr/lib/ghc-6.4/libraries/unix/include
 645 includes: HsUnix.h
 646 depends: base-1.0
 647 </screen>
 648
 649     <para>The full <ulink url="../Cabal/index.html">Cabal documentation</ulink>
 650       is still in preparation (at time of writing), so in the meantime
 651       here is a brief description of the syntax of this file:</para>
 652
 653     <para>A package description consists of a number of field/value pairs.  A
 654       field starts with the field name in the left-hand column followed by a
 655       &ldquo;<literal>:</literal>&rdquo;, and the value continues until the next line that begins in the
 656       left-hand column, or the end of file.</para>
 657
 658     <para>The syntax of the value depends on the field.   The various field
 659       types are:</para>
 660
 661     <variablelist>
 662       <varlistentry>
 663         <term>freeform</term>
 664         <listitem>
 665           <para>Any arbitrary string, no interpretation or parsing is
 666             done.</para>
 667         </listitem>
 668       </varlistentry>
 669       <varlistentry>
 670         <term>string</term>
 671         <listitem>
 672           <para>A sequence of non-space characters, or a sequence of arbitrary
 673             characters surrounded by quotes <literal>"...."</literal>.</para>
 674         </listitem>
 675       </varlistentry>
 676       <varlistentry>
 677         <term>string list</term>
 678         <listitem>
 679           <para>A sequence of strings, separated by commas.  The sequence may
 680             be empty.</para>
 681         </listitem>
 682       </varlistentry>
 683     </variablelist>
 684
 685     <para>In addition, there are some fields with special syntax (e.g. package
 686       names, version, dependencies).</para>
 687
 688     <para>The allowed fields, with their types, are:</para>
 689
 690     <variablelist>
 691       <varlistentry>
 692         <term>
 693           <literal>name</literal>
 694           <indexterm><primary><literal>name</literal></primary><secondary>package specification</secondary></indexterm>
 695         </term>
 696         <listitem>
 697           <para>The package's name (without the version).</para>
 698         </listitem>
 699       </varlistentry>
 700
 701       <varlistentry>
 702         <term>
 703           <literal>version</literal>
 704           <indexterm><primary><literal>version</literal></primary><secondary>package specification</secondary></indexterm>
 705         </term>
 706         <listitem>
 707           <para>The package's version, usually in the form
 708             <literal>A.B</literal> (any number of components are allowed).</para>
 709         </listitem>
 710       </varlistentry>
 711
 712       <varlistentry>
 713         <term>
 714           <literal>license</literal>
 715           <indexterm><primary><literal>auto</literal></primary><secondary>package specification</secondary></indexterm>
 716         </term>
 717         <listitem>
 718           <para>(string) The type of license under which this package is distributed.
 719             This field is a value of the <ulink
 720         url="../libraries/Cabal/Distribution.License.html#t:License"><literal>License</literal></ulink> type.</para>
 721         </listitem>
 722       </varlistentry>
 723
 724         <varlistentry>
 725           <term>
 726             <literal>license-file</literal>
 727             <indexterm><primary><literal>license-file</literal></primary><secondary>package specification</secondary></indexterm>
 728           </term>
 729           <listitem>
 730             <para>(optional string) The name of a file giving detailed license
 731             information for this package.</para>
 732           </listitem>
 733         </varlistentry>
 734
 735         <varlistentry>
 736           <term>
 737             <literal>copyright</literal>
 738             <indexterm><primary><literal>copyright</literal></primary><secondary>package specification</secondary></indexterm>
 739           </term>
 740           <listitem>
 741             <para>(optional freeform) The copyright string.</para>
 742           </listitem>
 743         </varlistentry>
 744
 745         <varlistentry>
 746           <term>
 747             <literal>maintainer</literal>
 748             <indexterm><primary><literal>maintainer</literal></primary><secondary>package specification</secondary></indexterm>
 749           </term>
 750           <listitem>
 751             <para>(optinoal freeform) The email address of the package's maintainer.</para>
 752           </listitem>
 753         </varlistentry>
 754
 755         <varlistentry>
 756           <term>
 757             <literal>stability</literal>
 758             <indexterm><primary><literal>stability</literal></primary><secondary>package specification</secondary></indexterm>
 759           </term>
 760           <listitem>
 761             <para>(optional freeform) A string describing the stability of the package
 762             (eg. stable, provisional or experimental).</para>
 763           </listitem>
 764         </varlistentry>
 765
 766         <varlistentry>
 767           <term>
 768             <literal>homepage</literal>
 769             <indexterm><primary><literal>homepage</literal></primary><secondary>package specification</secondary></indexterm>
 770           </term>
 771           <listitem>
 772             <para>(optional freeform) URL of the package's home page.</para>
 773           </listitem>
 774         </varlistentry>
 775
 776       <varlistentry>
 777         <term>
 778             <literal>package-url</literal>
 779             <indexterm><primary><literal>package-url</literal></primary><secondary>package specification</secondary></indexterm>
 780           </term>
 781           <listitem>
 782             <para>(optional freeform) URL of a downloadable distribution for this
 783             package.  The distribution should be a Cabal package.</para>
 784           </listitem>
 785         </varlistentry>
 786
 787         <varlistentry>
 788           <term>
 789             <literal>description</literal>
 790             <indexterm><primary><literal>description</literal></primary><secondary>package specification</secondary></indexterm>
 791           </term>
 792           <listitem>
 793             <para>(optional freeform) Description of the package.</para>
 794           </listitem>
 795         </varlistentry>
 796
 797       <varlistentry>
 798           <term>
 799             <literal>category</literal>
 800             <indexterm><primary><literal>category</literal></primary><secondary>package specification</secondary></indexterm>
 801           </term>
 802           <listitem>
 803             <para>(optinoal freeform) Which category the package belongs to.  This field
 804             is for use in conjunction with a future centralised package
 805             distribution framework, tentatively titled Hackage.</para>
 806           </listitem>
 807         </varlistentry>
 808
 809         <varlistentry>
 810           <term>
 811             <literal>author</literal>
 812             <indexterm><primary><literal>author</literal></primary><secondary>package specification</secondary></indexterm>
 813           </term>
 814           <listitem>
 815             <para>(optional freeform) Author of the package.</para>
 816           </listitem>
 817         </varlistentry>
 818
 819         <varlistentry>
 820           <term>
 821             <literal>exposed</literal>
 822             <indexterm><primary><literal>exposed</literal></primary><secondary>package specification</secondary></indexterm>
 823           </term>
 824           <listitem>
 825             <para>(bool) Whether the package is exposed or not.</para>
 826           </listitem>
 827         </varlistentry>
 828
 829         <varlistentry>
 830           <term>
 831             <literal>exposed-modules</literal>
 832             <indexterm><primary><literal>exposed-modules</literal></primary><secondary>package specification</secondary></indexterm>
 833           </term>
 834           <listitem>
 835             <para>(string list) modules exposed by this package.</para>
 836           </listitem>
 837         </varlistentry>
 838
 839         <varlistentry>
 840           <term>
 841             <literal>hidden-modules</literal>
 842             <indexterm><primary><literal>hidden-modules</literal></primary><secondary>package specification</secondary></indexterm>
 843           </term>
 844           <listitem>
 845             <para>(string list) modules provided by this package,
 846             but not exposed to the programmer.  These modules cannot be
 847             imported, but they are still subject to the overlapping constraint:
 848             no other package in the same program may provide a module of the
 849             same name.</para>
 850         </listitem>
 851         </varlistentry>
 852
 853         <varlistentry>
 854           <term>
 855             <literal>import-dirs</literal>
 856             <indexterm><primary><literal>import-dirs</literal></primary><secondary>package specification</secondary></indexterm>
 857           </term>
 858           <listitem>
 859             <para>(string list) A list of directories containing interface files
 860             (<literal>.hi</literal> files) for this package.</para>
 861
 862             <para>If the package contains profiling libraries, then
 863             the interface files for those library modules should have
 864             the suffix <literal>.p_hi</literal>.  So the package can
 865             contain both normal and profiling versions of the same
 866             library without conflict (see also
 867             <literal>library_dirs</literal> below).</para>
 868           </listitem>
 869         </varlistentry>
 870
 871         <varlistentry>
 872           <term>
 873             <literal>library-dirs</literal>
 874             <indexterm><primary><literal>library-dirs</literal></primary><secondary>package specification</secondary></indexterm>
 875           </term>
 876           <listitem>
 877             <para>(string list) A list of directories containing libraries for this
 878             package.</para>
 879           </listitem>
 880         </varlistentry>
 881
 882         <varlistentry>
 883           <term>
 884             <literal>hs-libraries</literal>
 885             <indexterm><primary><literal>hs-libraries</literal></primary><secondary>package specification</secondary></indexterm>
 886           </term>
 887           <listitem>
 888             <para>(string list) A list of libraries containing Haskell code for this
 889             package, with the <literal>.a</literal> or
 890             <literal>.dll</literal> suffix omitted.  When packages are
 891             built as libraries, the
 892             <literal>lib</literal> prefix is also omitted.</para>
 893
 894             <para>For use with GHCi, each library should have an
 895             object file too.  The name of the object file does
 896             <emphasis>not</emphasis> have a <literal>lib</literal>
 897             prefix, and has the normal object suffix for your
 898             platform.</para>
 899
 900             <para>For example, if we specify a Haskell library as
 901             <filename>HSfoo</filename> in the package spec, then the
 902             various flavours of library that GHC actually uses will be
 903             called:</para>
 904             <variablelist>
 905               <varlistentry>
 906                 <term><filename>libHSfoo.a</filename></term>
 907                 <listitem>
 908                   <para>The name of the library on Unix and Windows
 909                   (mingw) systems.  Note that we don't support
 910                   building dynamic libraries of Haskell code on Unix
 911                   systems.</para>
 912                 </listitem>
 913               </varlistentry>
 914               <varlistentry>
 915                 <term><filename>HSfoo.dll</filename></term>
 916                 <listitem>
 917                   <para>The name of the dynamic library on Windows
 918                   systems (optional).</para>
 919                 </listitem>
 920               </varlistentry>
 921               <varlistentry>
 922                 <term><filename>HSfoo.o</filename></term>
 923                 <term><filename>HSfoo.obj</filename></term>
 924                 <listitem>
 925                   <para>The object version of the library used by
 926                   GHCi.</para>
 927                 </listitem>
 928               </varlistentry>
 929             </variablelist>
 930           </listitem>
 931         </varlistentry>
 932
 933         <varlistentry>
 934           <term>
 935             <literal>extra-libs</literal>
 936             <indexterm><primary><literal>extra-libs</literal></primary><secondary>package specification</secondary></indexterm>
 937           </term>
 938           <listitem>
 939             <para>(string list) A list of extra libraries for this package.  The
 940             difference between <literal>hs-libraries</literal> and
 941             <literal>extra-libs</literal> is that
 942             <literal>hs-libraries</literal> normally have several
 943             versions, to support profiling, parallel and other build
 944             options.  The various versions are given different
 945             suffixes to distinguish them, for example the profiling
 946             version of the standard prelude library is named
 947             <filename>libHSbase_p.a</filename>, with the
 948             <literal>_p</literal> indicating that this is a profiling
 949             version.  The suffix is added automatically by GHC for
 950             <literal>hs-libraries</literal> only, no suffix is added
 951             for libraries in
 952             <literal>extra-libs</literal>.</para>
 953
 954             <para>The libraries listed in
 955             <literal>extra-libs</literal> may be any libraries
 956             supported by your system's linker, including dynamic
 957             libraries (<literal>.so</literal> on Unix,
 958             <literal>.DLL</literal> on Windows).</para>
 959
 960             <para>Also, <literal>extra-libs</literal> are placed
 961             on the linker command line after the
 962             <literal>hs-libraries</literal> for the same package.  If
 963             your package has dependencies in the other direction (i.e.
 964             <literal>extra-libs</literal> depends on
 965             <literal>hs-libraries</literal>), and the libraries are
 966             static, you might need to make two separate
 967             packages.</para>
 968           </listitem>
 969         </varlistentry>
 970
 971         <varlistentry>
 972           <term>
 973             <literal>include-dirs</literal>
 974             <indexterm><primary><literal>include-dirs</literal></primary><secondary>package specification</secondary></indexterm>
 975           </term>
 976           <listitem>
 977             <para>(string list) A list of directories containing C includes for this
 978             package.</para>
 979           </listitem>
 980         </varlistentry>
 981
 982         <varlistentry>
 983           <term>
 984            <literal>includes</literal>
 985            <indexterm><primary><literal>includes</literal></primary><secondary>package specification</secondary></indexterm>
 986           </term>
 987           <listitem>
 988             <para>(string list) A list of files to include for via-C compilations
 989             using this package.  Typically the include file(s) will
 990             contain function prototypes for any C functions used in
 991             the package, in case they end up being called as a result
 992             of Haskell functions from the package being
 993             inlined.</para>
 994           </listitem>
 995         </varlistentry>
 996
 997         <varlistentry>
 998           <term>
 999             <literal>depends</literal>
1000             <indexterm><primary><literal>depends</literal></primary><secondary>package specification</secondary></indexterm>
1001           </term>
1002           <listitem>
1003             <para>(package name list) Packages on which this package depends.  This field contains
1004             packages with explicit versions are required, except that when
1005             submitting a package to <literal>ghc-pkg register</literal>, the
1006             versions will be filled in if they are unambiguous.</para>
1007           </listitem>
1008         </varlistentry>
1009
1010         <varlistentry>
1011           <term>
1012             <literal>extra-hugs-opts</literal>
1013             <indexterm><primary><literal>extra-hugs-opts</literal></primary><secondary>package specification</secondary></indexterm>
1014           </term>
1015           <listitem>
1016             <para>(string list) Options to pass to Hugs for this package.</para>
1017           </listitem>
1018         </varlistentry>
1019
1020         <varlistentry>
1021           <term>
1022             <literal>extra-cc-opts</literal>
1023             <indexterm><primary><literal>extra-cc-opts</literal></primary><secondary>package specification</secondary></indexterm>
1024           </term>
1025           <listitem>
1026             <para>(string list) Extra arguments to be added to the gcc command line
1027             when this package is being used (only for via-C
1028             compilations).</para>
1029           </listitem>
1030         </varlistentry>
1031
1032         <varlistentry>
1033           <term>
1034             <literal>extra-ld-opts</literal>
1035             <indexterm><primary><literal>extra-ld-opts</literal></primary><secondary>package specification</secondary></indexterm>
1036           </term>
1037           <listitem>
1038             <para>(string list) Extra arguments to be added to the
1039             <command>gcc</command> command line (for linking) when
1040             this package is being used.</para>
1041           </listitem>
1042         </varlistentry>
1043
1044         <varlistentry>
1045           <term>
1046             <literal>framework-dirs</literal>
1047             <indexterm><primary><literal>framework-dirs</literal></primary><secondary>package specification</secondary></indexterm>
1048           </term>
1049           <listitem>
1050             <para>(string list) On Darwin/MacOS X, a list of directories containing
1051             frameworks for this package. This corresponds to the
1052             <option>-framework-path</option> option. It is ignored on all other
1053             platforms.</para>
1054           </listitem>
1055         </varlistentry>
1056
1057         <varlistentry>
1058           <term>
1059             <literal>extra-frameworks</literal>
1060             <indexterm><primary><literal>extra-frameworks</literal></primary><secondary>package specification</secondary></indexterm>
1061           </term>
1062           <listitem>
1063             <para>(string list) On Darwin/MacOS X, a list of frameworks to link to. This
1064             corresponds to the <option>-framework</option> option. Take a look
1065             at Apple's developer documentation to find out what frameworks
1066             actually are. This entry is ignored on all other platforms.</para>
1067           </listitem>
1068         </varlistentry>
1069
1070         <varlistentry>
1071           <term>
1072             <literal>haddock-interfaces</literal>
1073             <indexterm><primary><literal>haddock-interfaces</literal></primary><secondary>package specification</secondary></indexterm>
1074           </term>
1075           <listitem>
1076             <para>(string list) A list of filenames containing <ulink
1077               url="http://www.haskell.org/haddock/">Haddock</ulink> interface
1078             files (<literal>.haddock</literal> files) for this package.</para>
1079           </listitem>
1080         </varlistentry>
1081
1082         <varlistentry>
1083           <term>
1084             <literal>haddock-html</literal>
1085             <indexterm><primary><literal>haddock-html</literal></primary><secondary>package specification</secondary></indexterm>
1086           </term>
1087           <listitem>
1088             <para>(optional string) The directory containing the Haddock-generated HTML
1089             for this package.</para>
1090           </listitem>
1091         </varlistentry>
1092       </variablelist>
1093
1094 <!--  This isn't true any more.  I'm not sure if we still need it -SDM
1095       <para>
1096       The <literal>ghc-pkg</literal> tool performs expansion of
1097       environment variables occurring in input package specifications.
1098       So, if the <literal>mypkg</literal> was added to the package
1099       database as follows:
1100       </para>
1101 <screen>
1102   $ installdir=/usr/local/lib ghc-pkg -a &lt; mypkg.pkg
1103 </screen>
1104
1105       <para>
1106       The occurrence of <literal>${installdir}</literal> is replaced
1107       with <literal>/usr/local/lib</literal> in the package data that
1108       is added for <literal>mypkg</literal>.
1109       </para>
1110
1111       <para>
1112       This feature enables the distribution of package specification
1113       files that can be easily configured when installing.
1114       </para>
1115
1116       <para>For examples of more package specifications, take a look
1117       at the <literal>package.conf</literal> in your GHC
1118       installation.</para>
1119
1120 -->
1121
1122     </sect2>
1123   </sect1>
1124
1125 <!-- Emacs stuff:
1126      ;;; Local Variables: ***
1127      ;;; mode: xml ***
1128      ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter" "sect1") ***
1129      ;;; End: ***
1130  -->