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