ghc/docs/users_guide/packages.xml

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