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 modified, but alternatively
 344       the user's local package database or another specified
 345       file can be used.</para>
 346
 347     <para>Commands which only inspect the database (<literal>list</literal>,
 348       <literal>describe</literal>, <literal>field</literal>) will take into
 349       account the user's local package database too, unless the
 350       <literal>--global</literal> option is given.  This matches the behaviour
 351       of GHC, which automatically reads the user's local database if it is
 352       available.</para>
 353
 354     <para>The <literal>ghc-pkg</literal> program may be run in the ways listed
 355       below.  Where a package name is required, the package can be named in
 356       full including the version number
 357       (e.g. <literal>network-1.0</literal>), or without the version number if
 358       there is only a single version of that package installed.  Additionally,
 359       the version may be given as <literal>*</literal>, which means &ldquo;all
 360       versions&rdquo;.  For example, <literal>ghc-pkg hide network-*</literal>
 361       would hide all versions of the network package.</para>
 362
 363     <variablelist>
 364       <varlistentry>
 365         <term><literal>ghc-pkg register <replaceable>file</replaceable></literal></term>
 366         <listitem>
 367           <para>Reads a package specification from
 368             <replaceable>file</replaceable> (which may be &ldquo;<literal>-</literal>&rdquo;
 369             to indicate standard input),
 370             and adds it to the database of installed packages.  The syntax of
 371             <replaceable>file</replaceable> is given in <xref
 372               linkend="installed-pkg-info" />.</para>
 373
 374           <para>The package specification must be a package that isn't already
 375             installed.</para>
 376         </listitem>
 377       </varlistentry>
 378
 379       <varlistentry>
 380         <term><literal>ghc-pkg update <replaceable>file</replaceable></literal></term>
 381         <listitem>
 382           <para>The same as <literal>register</literal>, except that if a
 383             package of the same name is already installed, it is
 384             replaced by the new one.</para>
 385         </listitem>
 386       </varlistentry>
 387
 388       <varlistentry>
 389         <term><literal>ghc-pkg unregister <replaceable>P</replaceable></literal></term>
 390         <listitem>
 391           <para>Remove the specified package from the database.</para>
 392         </listitem>
 393       </varlistentry>
 394
 395       <varlistentry>
 396         <term><literal>ghc-pkg expose <replaceable>P</replaceable></literal></term>
 397         <listitem>
 398           <para>Sets the <literal>exposed</literal> flag for package
 399             <replaceable>P</replaceable> to <literal>True</literal>.</para>
 400         </listitem>
 401       </varlistentry>
 402
 403       <varlistentry>
 404         <term><literal>ghc-pkg hide <replaceable>P</replaceable></literal></term>
 405         <listitem>
 406           <para>Sets the <literal>exposed</literal> flag for package
 407             <replaceable>P</replaceable> to <literal>False</literal>.</para>
 408         </listitem>
 409       </varlistentry>
 410
 411       <varlistentry>
 412         <term><literal>ghc-pkg list</literal></term>
 413         <listitem>
 414           <para>This option displays the currently installed
 415             packages, for each of the databases known to
 416             <literal>ghc-pkg</literal>.  That includes the global database, the
 417             user's local database (if <option>--user</option> is given), and
 418             any further files specified using the <option>-f</option> option on
 419             the command line.</para>
 420
 421           <para>Hidden packages (those for which the <literal>exposed</literal>
 422             flag is <literal>False</literal>) are shown in parentheses in the
 423             list of packages.</para>
 424         </listitem>
 425       </varlistentry>
 426
 427       <varlistentry>
 428         <term><literal>ghc-pkg describe <replaceable>P</replaceable></literal></term>
 429         <listitem>
 430           <para>Emit the full description of the specified package.  The
 431             description is in the form of an
 432             <literal>InstalledPackageInfo</literal>, the same as the input file
 433             format for <literal>ghc-pkg register</literal>.  See <xref
 434               linkend="installed-pkg-info" /> for details.</para>
 435         </listitem>
 436       </varlistentry>
 437
 438       <varlistentry>
 439         <term><literal>ghc-pkg field <replaceable>P</replaceable> <replaceable>field</replaceable></literal></term>
 440         <listitem>
 441           <para>Show just a single field of the installed package description
 442             for <literal>P</literal>.</para>
 443         </listitem>
 444       </varlistentry>
 445     </variablelist>
 446
 447     <para>Additionally, the following flags are accepted by
 448       <literal>ghc-pkg</literal>:</para>
 449
 450     <variablelist>
 451       <varlistentry>
 452         <term>
 453           <option>&ndash;&ndash;auto-ghci-libs</option><indexterm><primary><option>&ndash;&ndash;user</option></primary>
 454           </indexterm>
 455         </term>
 456         <listitem>
 457           <para>Automatically generate the GHCi
 458             <filename>.o</filename> version of each
 459             <filename>.a</filename> Haskell library, using GNU ld (if
 460             that is available).  Without this option,
 461             <literal>ghc-pkg</literal> will warn if GHCi versions of
 462             any Haskell libraries in the package don't exist.</para>
 463
 464             <para>GHCi <literal>.o</literal> libraries don't
 465             necessarily have to live in the same directory as the
 466             corresponding <literal>.a</literal> library.  However,
 467             this option will cause the GHCi library to be created in
 468             the same directory as the <literal>.a</literal>
 469             library.</para>
 470         </listitem>
 471       </varlistentry>
 472
 473       <varlistentry>
 474         <term>
 475           <option>-f</option> <replaceable>file</replaceable>
 476           <indexterm><primary><option>-f</option></primary>
 477           </indexterm>
 478         </term>
 479         <term>
 480           <option>-package-conf</option> <replaceable>file</replaceable>
 481           <indexterm><primary><option>-package-conf</option></primary>
 482           </indexterm>
 483         </term>
 484         <listitem>
 485           <para>Operate on the package database in
 486             <replaceable>file</replaceable>.</para>
 487
 488           <para>When multiple <option>-f</option> options are given, or
 489             <option>-f</option> is used in conjunction with
 490             <option>--user</option> or <option>--global</option>, the last
 491             one on the command-line is the one that will be modified.</para>
 492         </listitem>
 493       </varlistentry>
 494
 495       <varlistentry>
 496         <term>
 497           <option>&ndash;&ndash;force</option>
 498           <indexterm><primary>
 499               <option>&ndash;&ndash;force</option>
 500             </primary></indexterm>
 501         </term>
 502         <listitem>
 503           <para>Causes <literal>ghc-pkg</literal> to ignore missing
 504             dependencies, directories and libraries when registering a package,
 505             and just go ahead and add it anyway.  This might be useful if your
 506             package installation system needs to add the package to
 507             GHC before building and installing the files.</para>
 508         </listitem>
 509       </varlistentry>
 510
 511       <varlistentry>
 512         <term>
 513           <option>&ndash;&ndash;global</option><indexterm><primary><option>&ndash;&ndash;user</option></primary>
 514           </indexterm>
 515         </term>
 516         <listitem>
 517           <para>Operate on the global package database (this is the default).
 518             This flag affects the <literal>register</literal>,
 519             <literal>update</literal>, <literal>unregister</literal>,
 520             <literal>expose</literal>, and <literal>hide</literal>
 521             commands.</para>
 522         </listitem>
 523       </varlistentry>
 524
 525       <varlistentry>
 526         <term>
 527           <option>&ndash;&ndash;help</option><indexterm><primary><option>&ndash;&ndash;user</option></primary>
 528           </indexterm>
 529         </term>
 530         <term>
 531           <option>-?</option><indexterm><primary><option>-?</option></primary>
 532           </indexterm>
 533         </term>
 534         <listitem>
 535           <para>Outputs the command-line syntax.</para>
 536         </listitem>
 537       </varlistentry>
 538
 539       <varlistentry>
 540         <term>
 541           <option>&ndash;&ndash;user</option><indexterm><primary><option>&ndash;&ndash;user</option></primary>
 542           </indexterm>
 543         </term>
 544         <listitem>
 545           <para>Operate on the current user's local package database.
 546             This flag affects the <literal>register</literal>,
 547             <literal>update</literal>, <literal>unregister</literal>,
 548             <literal>expose</literal>, and <literal>hide</literal>
 549             commands.</para>
 550         </listitem>
 551       </varlistentry>
 552
 553       <varlistentry>
 554         <term>
 555           <option>-V</option><indexterm><primary><option>-V</option></primary>
 556           </indexterm>
 557         </term>
 558         <term>
 559           <option>&ndash;&ndash;version</option><indexterm><primary><option>&ndash;&ndash;user</option></primary>
 560           </indexterm>
 561         </term>
 562         <listitem>
 563           <para>Output the <literal>ghc-pkg</literal> version number.</para>
 564         </listitem>
 565       </varlistentry>
 566     </variablelist>
 567
 568     <para>When modifying the package database
 569       <replaceable>file</replaceable>, a copy of the original file is
 570       saved in <replaceable>file</replaceable><literal>.old</literal>,
 571       so in an emergency you can always restore the old settings by
 572       copying the old file back again.</para>
 573
 574   </sect2>
 575
 576   <sect2 id="installed-pkg-info">
 577     <title>
 578       <literal>InstalledPackageInfo</literal>: a package specification
 579     </title>
 580
 581     <para>A package specification is a Haskell record; in particular, it is the
 582       record <ulink
 583         url="../libraries/Cabal/Distribution.InstalledPackageInfo#%tInstalledPackageInfo">InstalledPackageInfo</ulink> in the module Distribution.InstalledPackageInfo, which is part of the Cabal package distributed with GHC.</para>
 584
 585     <para>An <literal>InstalledPackageInfo</literal> has a human
 586       readable/writable syntax.  The functions
 587       <literal>parseInstalledPackageInfo</literal> and
 588       <literal>showInstalledPackageInfo</literal> read and write this syntax
 589       respectively.  Here's an example of the
 590       <literal>InstalledPackageInfo</literal> for the <literal>unix</literal> package:</para>
 591
 592 <screen>
 593 $ ghc-pkg describe unix
 594 name: unix
 595 version: 1.0
 596 license: BSD3
 597 copyright:
 598 maintainer: libraries@haskell.org
 599 stability:
 600 homepage:
 601 package-url:
 602 description:
 603 category:
 604 author:
 605 exposed: True
 606 exposed-modules: System.Posix,
 607                  System.Posix.DynamicLinker.Module,
 608                  System.Posix.DynamicLinker.Prim,
 609                  System.Posix.Directory,
 610                  System.Posix.DynamicLinker,
 611                  System.Posix.Env,
 612                  System.Posix.Error,
 613                  System.Posix.Files,
 614                  System.Posix.IO,
 615                  System.Posix.Process,
 616                  System.Posix.Resource,
 617                  System.Posix.Temp,
 618                  System.Posix.Terminal,
 619                  System.Posix.Time,
 620                  System.Posix.Unistd,
 621                  System.Posix.User,
 622                  System.Posix.Signals.Exts
 623 import-dirs: /usr/lib/ghc-6.4/libraries/unix
 624 library-dirs: /usr/lib/ghc-6.4/libraries/unix
 625 hs-libraries: HSunix
 626 extra-libs: HSunix_cbits, dl
 627 include-dirs: /usr/lib/ghc-6.4/libraries/unix/include
 628 includes: HsUnix.h
 629 depends: base-1.0
 630 </screen>
 631
 632     <para>The full <ulink url="../Cabal/index.html">Cabal documentation</ulink>
 633       is still in preparation (at time of writing), so in the meantime
 634       here is a brief description of the syntax of this file:</para>
 635
 636     <para>A package description consists of a number of field/value pairs.  A
 637       field starts with the field name in the left-hand column followed by a
 638       &ldquo;<literal>:</literal>&rdquo;, and the value continues until the next line that begins in the
 639       left-hand column, or the end of file.</para>
 640
 641     <para>The syntax of the value depends on the field.   The various field
 642       types are:</para>
 643
 644     <variablelist>
 645       <varlistentry>
 646         <term>freeform</term>
 647         <listitem>
 648           <para>Any arbitrary string, no interpretation or parsing is
 649             done.</para>
 650         </listitem>
 651       </varlistentry>
 652       <varlistentry>
 653         <term>string</term>
 654         <listitem>
 655           <para>A sequence of non-space characters, or a sequence of arbitrary
 656             characters surrounded by quotes <literal>"...."</literal>.</para>
 657         </listitem>
 658       </varlistentry>
 659       <varlistentry>
 660         <term>string list</term>
 661         <listitem>
 662           <para>A sequence of strings, separated by commas.  The sequence may
 663             be empty.</para>
 664         </listitem>
 665       </varlistentry>
 666     </variablelist>
 667
 668     <para>In addition, there are some fields with special syntax (e.g. package
 669       names, version, dependencies).</para>
 670
 671     <para>The allowed fields, with their types, are:</para>
 672
 673     <variablelist>
 674       <varlistentry>
 675         <term>
 676           <literal>name</literal>
 677           <indexterm><primary><literal>name</literal></primary><secondary>package specification</secondary></indexterm>
 678         </term>
 679         <listitem>
 680           <para>The package's name (without the version).</para>
 681         </listitem>
 682       </varlistentry>
 683
 684       <varlistentry>
 685         <term>
 686           <literal>version</literal>
 687           <indexterm><primary><literal>version</literal></primary><secondary>package specification</secondary></indexterm>
 688         </term>
 689         <listitem>
 690           <para>The package's version, usually in the form
 691             <literal>A.B</literal> (any number of components are allowed).</para>
 692         </listitem>
 693       </varlistentry>
 694
 695       <varlistentry>
 696         <term>
 697           <literal>license</literal>
 698           <indexterm><primary><literal>auto</literal></primary><secondary>package specification</secondary></indexterm>
 699         </term>
 700         <listitem>
 701           <para>(string) The type of license under which this package is distributed.
 702             This field is a value of the <ulink
 703         url="../libraries/Cabal/Distribution.License.html#t:License"><literal>License</literal></ulink> type.</para>
 704         </listitem>
 705       </varlistentry>
 706
 707         <varlistentry>
 708           <term>
 709             <literal>license-file</literal>
 710             <indexterm><primary><literal>license-file</literal></primary><secondary>package specification</secondary></indexterm>
 711           </term>
 712           <listitem>
 713             <para>(optional string) The name of a file giving detailed license
 714             information for this package.</para>
 715           </listitem>
 716         </varlistentry>
 717
 718         <varlistentry>
 719           <term>
 720             <literal>copyright</literal>
 721             <indexterm><primary><literal>copyright</literal></primary><secondary>package specification</secondary></indexterm>
 722           </term>
 723           <listitem>
 724             <para>(optional freeform) The copyright string.</para>
 725           </listitem>
 726         </varlistentry>
 727
 728         <varlistentry>
 729           <term>
 730             <literal>maintainer</literal>
 731             <indexterm><primary><literal>maintainer</literal></primary><secondary>package specification</secondary></indexterm>
 732           </term>
 733           <listitem>
 734             <para>(optinoal freeform) The email address of the package's maintainer.</para>
 735           </listitem>
 736         </varlistentry>
 737
 738         <varlistentry>
 739           <term>
 740             <literal>stability</literal>
 741             <indexterm><primary><literal>stability</literal></primary><secondary>package specification</secondary></indexterm>
 742           </term>
 743           <listitem>
 744             <para>(optional freeform) A string describing the stability of the package
 745             (eg. stable, provisional or experimental).</para>
 746           </listitem>
 747         </varlistentry>
 748
 749         <varlistentry>
 750           <term>
 751             <literal>homepage</literal>
 752             <indexterm><primary><literal>homepage</literal></primary><secondary>package specification</secondary></indexterm>
 753           </term>
 754           <listitem>
 755             <para>(optional freeform) URL of the package's home page.</para>
 756           </listitem>
 757         </varlistentry>
 758
 759       <varlistentry>
 760         <term>
 761             <literal>package-url</literal>
 762             <indexterm><primary><literal>package-url</literal></primary><secondary>package specification</secondary></indexterm>
 763           </term>
 764           <listitem>
 765             <para>(optional freeform) URL of a downloadable distribution for this
 766             package.  The distribution should be a Cabal package.</para>
 767           </listitem>
 768         </varlistentry>
 769
 770         <varlistentry>
 771           <term>
 772             <literal>description</literal>
 773             <indexterm><primary><literal>description</literal></primary><secondary>package specification</secondary></indexterm>
 774           </term>
 775           <listitem>
 776             <para>(optional freeform) Description of the package.</para>
 777           </listitem>
 778         </varlistentry>
 779
 780       <varlistentry>
 781           <term>
 782             <literal>category</literal>
 783             <indexterm><primary><literal>category</literal></primary><secondary>package specification</secondary></indexterm>
 784           </term>
 785           <listitem>
 786             <para>(optinoal freeform) Which category the package belongs to.  This field
 787             is for use in conjunction with a future centralised package
 788             distribution framework, tentatively titled Hackage.</para>
 789           </listitem>
 790         </varlistentry>
 791
 792         <varlistentry>
 793           <term>
 794             <literal>author</literal>
 795             <indexterm><primary><literal>author</literal></primary><secondary>package specification</secondary></indexterm>
 796           </term>
 797           <listitem>
 798             <para>(optional freeform) Author of the package.</para>
 799           </listitem>
 800         </varlistentry>
 801
 802         <varlistentry>
 803           <term>
 804             <literal>exposed</literal>
 805             <indexterm><primary><literal>exposed</literal></primary><secondary>package specification</secondary></indexterm>
 806           </term>
 807           <listitem>
 808             <para>(bool) Whether the package is exposed or not.</para>
 809           </listitem>
 810         </varlistentry>
 811
 812         <varlistentry>
 813           <term>
 814             <literal>exposed-modules</literal>
 815             <indexterm><primary><literal>exposed-modules</literal></primary><secondary>package specification</secondary></indexterm>
 816           </term>
 817           <listitem>
 818             <para>(string list) modules exposed by this package.</para>
 819           </listitem>
 820         </varlistentry>
 821
 822         <varlistentry>
 823           <term>
 824             <literal>hidden-modules</literal>
 825             <indexterm><primary><literal>hidden-modules</literal></primary><secondary>package specification</secondary></indexterm>
 826           </term>
 827           <listitem>
 828             <para>(string list) modules provided by this package,
 829             but not exposed to the programmer.  These modules cannot be
 830             imported, but they are still subject to the overlapping constraint:
 831             no other package in the same program may provide a module of the
 832             same name.</para>
 833         </listitem>
 834         </varlistentry>
 835
 836         <varlistentry>
 837           <term>
 838             <literal>import-dirs</literal>
 839             <indexterm><primary><literal>import-dirs</literal></primary><secondary>package specification</secondary></indexterm>
 840           </term>
 841           <listitem>
 842             <para>(string list) A list of directories containing interface files
 843             (<literal>.hi</literal> files) for this package.</para>
 844
 845             <para>If the package contains profiling libraries, then
 846             the interface files for those library modules should have
 847             the suffix <literal>.p_hi</literal>.  So the package can
 848             contain both normal and profiling versions of the same
 849             library without conflict (see also
 850             <literal>library_dirs</literal> below).</para>
 851           </listitem>
 852         </varlistentry>
 853
 854         <varlistentry>
 855           <term>
 856             <literal>library-dirs</literal>
 857             <indexterm><primary><literal>library-dirs</literal></primary><secondary>package specification</secondary></indexterm>
 858           </term>
 859           <listitem>
 860             <para>(string list) A list of directories containing libraries for this
 861             package.</para>
 862           </listitem>
 863         </varlistentry>
 864
 865         <varlistentry>
 866           <term>
 867             <literal>hs-libraries</literal>
 868             <indexterm><primary><literal>hs-libraries</literal></primary><secondary>package specification</secondary></indexterm>
 869           </term>
 870           <listitem>
 871             <para>(string list) A list of libraries containing Haskell code for this
 872             package, with the <literal>.a</literal> or
 873             <literal>.dll</literal> suffix omitted.  When packages are
 874             built as libraries, the
 875             <literal>lib</literal> prefix is also omitted.</para>
 876
 877             <para>For use with GHCi, each library should have an
 878             object file too.  The name of the object file does
 879             <emphasis>not</emphasis> have a <literal>lib</literal>
 880             prefix, and has the normal object suffix for your
 881             platform.</para>
 882
 883             <para>For example, if we specify a Haskell library as
 884             <filename>HSfoo</filename> in the package spec, then the
 885             various flavours of library that GHC actually uses will be
 886             called:</para>
 887             <variablelist>
 888               <varlistentry>
 889                 <term><filename>libHSfoo.a</filename></term>
 890                 <listitem>
 891                   <para>The name of the library on Unix and Windows
 892                   (mingw) systems.  Note that we don't support
 893                   building dynamic libraries of Haskell code on Unix
 894                   systems.</para>
 895                 </listitem>
 896               </varlistentry>
 897               <varlistentry>
 898                 <term><filename>HSfoo.dll</filename></term>
 899                 <listitem>
 900                   <para>The name of the dynamic library on Windows
 901                   systems (optional).</para>
 902                 </listitem>
 903               </varlistentry>
 904               <varlistentry>
 905                 <term><filename>HSfoo.o</filename></term>
 906                 <term><filename>HSfoo.obj</filename></term>
 907                 <listitem>
 908                   <para>The object version of the library used by
 909                   GHCi.</para>
 910                 </listitem>
 911               </varlistentry>
 912             </variablelist>
 913           </listitem>
 914         </varlistentry>
 915
 916         <varlistentry>
 917           <term>
 918             <literal>extra-libs</literal>
 919             <indexterm><primary><literal>extra-libs</literal></primary><secondary>package specification</secondary></indexterm>
 920           </term>
 921           <listitem>
 922             <para>(string list) A list of extra libraries for this package.  The
 923             difference between <literal>hs-libraries</literal> and
 924             <literal>extra-libs</literal> is that
 925             <literal>hs-libraries</literal> normally have several
 926             versions, to support profiling, parallel and other build
 927             options.  The various versions are given different
 928             suffixes to distinguish them, for example the profiling
 929             version of the standard prelude library is named
 930             <filename>libHSbase_p.a</filename>, with the
 931             <literal>_p</literal> indicating that this is a profiling
 932             version.  The suffix is added automatically by GHC for
 933             <literal>hs-libraries</literal> only, no suffix is added
 934             for libraries in
 935             <literal>extra-libs</literal>.</para>
 936
 937             <para>The libraries listed in
 938             <literal>extra-libs</literal> may be any libraries
 939             supported by your system's linker, including dynamic
 940             libraries (<literal>.so</literal> on Unix,
 941             <literal>.DLL</literal> on Windows).</para>
 942
 943             <para>Also, <literal>extra-libs</literal> are placed
 944             on the linker command line after the
 945             <literal>hs-libraries</literal> for the same package.  If
 946             your package has dependencies in the other direction (i.e.
 947             <literal>extra-libs</literal> depends on
 948             <literal>hs-libraries</literal>), and the libraries are
 949             static, you might need to make two separate
 950             packages.</para>
 951           </listitem>
 952         </varlistentry>
 953
 954         <varlistentry>
 955           <term>
 956             <literal>include-dirs</literal>
 957             <indexterm><primary><literal>include-dirs</literal></primary><secondary>package specification</secondary></indexterm>
 958           </term>
 959           <listitem>
 960             <para>(string list) A list of directories containing C includes for this
 961             package.</para>
 962           </listitem>
 963         </varlistentry>
 964
 965         <varlistentry>
 966           <term>
 967            <literal>includes</literal>
 968            <indexterm><primary><literal>includes</literal></primary><secondary>package specification</secondary></indexterm>
 969           </term>
 970           <listitem>
 971             <para>(string list) A list of files to include for via-C compilations
 972             using this package.  Typically the include file(s) will
 973             contain function prototypes for any C functions used in
 974             the package, in case they end up being called as a result
 975             of Haskell functions from the package being
 976             inlined.</para>
 977           </listitem>
 978         </varlistentry>
 979
 980         <varlistentry>
 981           <term>
 982             <literal>depends</literal>
 983             <indexterm><primary><literal>depends</literal></primary><secondary>package specification</secondary></indexterm>
 984           </term>
 985           <listitem>
 986             <para>(package name list) Packages on which this package depends.  This field contains
 987             packages with explicit versions are required, except that when
 988             submitting a package to <literal>ghc-pkg register</literal>, the
 989             versions will be filled in if they are unambiguous.</para>
 990           </listitem>
 991         </varlistentry>
 992
 993         <varlistentry>
 994           <term>
 995             <literal>extra-hugs-opts</literal>
 996             <indexterm><primary><literal>extra-hugs-opts</literal></primary><secondary>package specification</secondary></indexterm>
 997           </term>
 998           <listitem>
 999             <para>(string list) Options to pass to Hugs for this package.</para>
1000           </listitem>
1001         </varlistentry>
1002
1003         <varlistentry>
1004           <term>
1005             <literal>extra-cc-opts</literal>
1006             <indexterm><primary><literal>extra-cc-opts</literal></primary><secondary>package specification</secondary></indexterm>
1007           </term>
1008           <listitem>
1009             <para>(string list) Extra arguments to be added to the gcc command line
1010             when this package is being used (only for via-C
1011             compilations).</para>
1012           </listitem>
1013         </varlistentry>
1014
1015         <varlistentry>
1016           <term>
1017             <literal>extra-ld-opts</literal>
1018             <indexterm><primary><literal>extra-ld-opts</literal></primary><secondary>package specification</secondary></indexterm>
1019           </term>
1020           <listitem>
1021             <para>(string list) Extra arguments to be added to the
1022             <command>gcc</command> command line (for linking) when
1023             this package is being used.</para>
1024           </listitem>
1025         </varlistentry>
1026
1027         <varlistentry>
1028           <term>
1029             <literal>framework-dirs</literal>
1030             <indexterm><primary><literal>framework-dirs</literal></primary><secondary>package specification</secondary></indexterm>
1031           </term>
1032           <listitem>
1033             <para>(string list) On Darwin/MacOS X, a list of directories containing
1034             frameworks for this package. This corresponds to the
1035             <option>-framework-path</option> option. It is ignored on all other
1036             platforms.</para>
1037           </listitem>
1038         </varlistentry>
1039
1040         <varlistentry>
1041           <term>
1042             <literal>extra-frameworks</literal>
1043             <indexterm><primary><literal>extra-frameworks</literal></primary><secondary>package specification</secondary></indexterm>
1044           </term>
1045           <listitem>
1046             <para>(string list) On Darwin/MacOS X, a list of frameworks to link to. This
1047             corresponds to the <option>-framework</option> option. Take a look
1048             at Apple's developer documentation to find out what frameworks
1049             actually are. This entry is ignored on all other platforms.</para>
1050           </listitem>
1051         </varlistentry>
1052
1053         <varlistentry>
1054           <term>
1055             <literal>haddock-interfaces</literal>
1056             <indexterm><primary><literal>haddock-interfaces</literal></primary><secondary>package specification</secondary></indexterm>
1057           </term>
1058           <listitem>
1059             <para>(string list) A list of filenames containing <ulink
1060               url="http://www.haskell.org/haddock/">Haddock</ulink> interface
1061             files (<literal>.haddock</literal> files) for this package.</para>
1062           </listitem>
1063         </varlistentry>
1064
1065         <varlistentry>
1066           <term>
1067             <literal>haddock-html</literal>
1068             <indexterm><primary><literal>haddock-html</literal></primary><secondary>package specification</secondary></indexterm>
1069           </term>
1070           <listitem>
1071             <para>(optional string) The directory containing the Haddock-generated HTML
1072             for this package.</para>
1073           </listitem>
1074         </varlistentry>
1075       </variablelist>
1076
1077 <!--  This isn't true any more.  I'm not sure if we still need it -SDM
1078       <para>
1079       The <literal>ghc-pkg</literal> tool performs expansion of
1080       environment variables occurring in input package specifications.
1081       So, if the <literal>mypkg</literal> was added to the package
1082       database as follows:
1083       </para>
1084 <screen>
1085   $ installdir=/usr/local/lib ghc-pkg -a &lt; mypkg.pkg
1086 </screen>
1087
1088       <para>
1089       The occurrence of <literal>${installdir}</literal> is replaced
1090       with <literal>/usr/local/lib</literal> in the package data that
1091       is added for <literal>mypkg</literal>.
1092       </para>
1093
1094       <para>
1095       This feature enables the distribution of package specification
1096       files that can be easily configured when installing.
1097       </para>
1098
1099       <para>For examples of more package specifications, take a look
1100       at the <literal>package.conf</literal> in your GHC
1101       installation.</para>
1102
1103 -->
1104
1105     </sect2>
1106   </sect1>
1107
1108 <!-- Emacs stuff:
1109      ;;; Local Variables: ***
1110      ;;; mode: xml ***
1111      ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter" "sect1") ***
1112      ;;; End: ***
1113  -->