docs/users_guide/packages.xml

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