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