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