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