ghc/docs/users_guide/packages.xml

   1 <?xml version="1.0" encoding="iso-8859-1"?>
   2   <sect1 id="packages">
   3     <title>Packages</title>
   4     <indexterm><primary>packages</primary></indexterm>
   5
   6     <para>Packages are collections of libraries, conveniently grouped
   7     together as a single entity.  The package system is flexible: a
   8     package may consist of Haskell code, foreign language code (eg. C
   9     libraries), or a mixture of the two.  A package is a good way to
  10     group together related Haskell modules, and is essential if you
  11     intend to make the modules into a Windows DLL (see below).</para>
  12
  13     <para>Because packages can contain both Haskell and C libraries, they
  14     are also a good way to provide convenient access to a Haskell
  15     layer over a C library.</para>
  16
  17     <para>GHC comes with several packages (see the accompanying
  18     library documentation), and packages can be added to or removed
  19     from an existing GHC installation, using the supplied
  20     <literal>ghc-pkg</literal><indexterm><primary><literal>ghc-pkg</literal></primary>
  21     </indexterm> tool, described in <xref
  22     linkend="package-management"/>.</para>
  23
  24     <sect2 id="using-packages">
  25       <title>Using a package</title>
  26       <indexterm><primary>packages</primary>
  27         <secondary>using</secondary></indexterm>
  28
  29       <para>Some packages,  called <emphasis>auto packages</emphasis>,
  30       are automatically available: you don't need
  31       to specify any extra flags to use them (except in certain
  32       circumstances; see below).  All the packages which contain
  33       hierarchical libraries fall into this category.</para>
  34
  35       <para>Some other packages are <emphasis>not</emphasis>
  36       automatically available: those are normally the packages
  37       containing old non-hierarchical libraries.  To gain access to a
  38       non-auto package, use the <option>-package</option> command-line
  39       flag:</para>
  40
  41       <variablelist>
  42         <varlistentry>
  43           <term>
  44             <option>-package <replaceable>lib</replaceable></option>
  45             <indexterm><primary>-package <replaceable>lib</replaceable> option</primary></indexterm>
  46           </term>
  47           <listitem>
  48             <para>This option brings into scope all the modules from
  49             package <literal><replaceable>lib</replaceable></literal> (they still have to
  50             be imported in your Haskell source, however).  It also
  51             causes the relevant libraries to be linked when linking is
  52             being done.</para>
  53             <para>Some packages depend on other packages, for example the
  54             <literal>text</literal> package makes use of some of the modules
  55             in the <literal>lang</literal> package.  The package system
  56             takes care of all these dependencies, so that when you say
  57             <literal>-package text</literal> on the command line, you
  58             automatically get <literal>-package lang</literal> too.</para>
  59           </listitem>
  60         </varlistentry>
  61       </variablelist>
  62
  63       <para>There's one case where you need to use the
  64       <option>-package</option> option even for auto packages: when
  65       linking a program in batch mode mode (<xref linkend="options-order"/>)
  66       <footnote><para>This is because
  67       GHC can't figure out from the object files which packages are
  68       required; in <option>&ndash;&ndash;make</option> mode and in
  69       GHCi the compiler has more information available to figure out
  70       the package dependencies.  We might try to lift this restriction
  71       in the future.</para></footnote>.  For example, to link a
  72       program consisting of objects <filename>Foo.o</filename> and
  73       <filename>Main.o</filename>, where we made use of the
  74       <literal>network</literal> package, we need to give GHC the <literal>-package</literal> flag thus:
  75
  76 <screen>$ ghc -o myprog Foo.o Main.o -package network</screen>
  77
  78     The same flag is necessary even if we compiled the modules from source, because GHC still
  79     reckons it's in batch mode:
  80 <screen>$ ghc -o myprog Foo.hs Main.hs -package network</screen>
  81 In <literal>--make</literal> and <literal>--interactive</literal> modes (<xref linkend="modes"/>), however, GHC figures out
  82 the auto packages required for linking without further assistance.
  83 </para>
  84
  85     </sect2>
  86
  87
  88     <sect2 id="using-local-packages">
  89       <title>Maintaining a local set of packages</title>
  90
  91       <para>When GHC starts up, it automatically reads the default set
  92       of packages from a configuration file, normally named
  93       <filename>package.conf</filename> in your GHC installation
  94       directory.</para>
  95
  96       <para>You can load in additional package configuration files
  97       using the <option>-package-conf</option> option:</para>
  98
  99       <variablelist>
 100         <varlistentry>
 101           <term>
 102             <option>-package-conf <replaceable>file</replaceable></option>
 103             <indexterm><primary><option>-package-conf <replaceable>file</replaceable></option></primary></indexterm>
 104           </term>
 105           <listitem>
 106             <para>Read in the package configuration file
 107             <replaceable>file</replaceable> in addition to the system
 108             default file.  This allows the user to have a local set of
 109             packages in addition to the system-wide ones.</para>
 110           </listitem>
 111         </varlistentry>
 112       </variablelist>
 113
 114       <para>To create your own package configuration file, just create
 115       a new file and put the string
 116       <quote><literal>[]</literal></quote> in it.  Packages can be
 117       added to the new configuration file using the
 118       <literal>ghc-pkg</literal> tool, described in <xref
 119       linkend="package-management"/>.</para>
 120     </sect2>
 121
 122     <sect2 id="building-packages">
 123       <title>Building a package from Haskell source</title>
 124       <indexterm><primary>packages</primary>
 125         <secondary>building</secondary></indexterm>
 126
 127       <para>It takes some special considerations to build a new
 128       package:</para>
 129
 130       <itemizedlist>
 131         <listitem>
 132           <para>A package may contain several Haskell modules. A
 133           package may span many directories, or many packages may
 134           exist in a single directory. Packages may not be mutually
 135           recursive.</para>
 136         </listitem>
 137
 138         <listitem>
 139           <para>A package has a name
 140           (e.g. <filename>base</filename>)</para>
 141         </listitem>
 142
 143         <listitem>
 144           <para>The Haskell code in a package may be built into one or
 145           more archive libraries
 146           (e.g. <filename>libHSfoo.a</filename>), or a single DLL on
 147           Windows (e.g. <filename>HSfoo.dll</filename>).  The
 148           restriction to a single DLL on Windows is because the
 149           package system is used to tell the compiler when it should
 150           make an inter-DLL call rather than an intra-DLL call
 151           (inter-DLL calls require an extra
 152           indirection). <emphasis>Building packages as DLLs doesn't
 153           work at the moment; see <xref linkend="win32-dlls-create"/>
 154           for the gory details.</emphasis>
 155           </para>
 156
 157           <para>Building a static library is done by using the
 158           <literal>ar</literal> tool, like so:</para>
 159
 160 <screen>ar cqs libHSfoo.a A.o B.o C.o ...</screen>
 161
 162           <para>where <filename>A.o</filename>,
 163           <filename>B.o</filename> and so on are the compiled Haskell
 164           modules, and <filename>libHSfoo.a</filename> is the library
 165           you wish to create.  The syntax may differ slightly on your
 166           system, so check the documentation if you run into
 167           difficulties.</para>
 168
 169           <para>Versions of the Haskell libraries for use with GHCi
 170           may also be included: GHCi cannot load <literal>.a</literal>
 171           files directly, instead it will look for an object file
 172           called <filename>HSfoo.o</filename> and load that.  On some
 173           systems, the <literal>ghc-pkg</literal> tool can
 174           automatically build the GHCi version of each library, see
 175           <xref linkend="package-management"/>.  To build these
 176           libraries by hand from the <literal>.a</literal> archive, it
 177           is possible to use GNU <command>ld</command> as
 178           follows:</para>
 179
 180 <screen>ld -r &ndash;&ndash;whole-archive -o HSfoo.o libHSfoo.a</screen>
 181         </listitem>
 182
 183         <listitem>
 184           <para>(replace
 185           <literal>&ndash;&ndash;--whole-archive</literal> with
 186           <literal>&ndash;all_load</literal> on MacOS X)</para>
 187
 188           <para>GHC does not maintain detailed cross-package
 189           dependency information.  It does remember which modules in
 190           other packages the current module depends on, but not which
 191           things within those imported things.</para>
 192         </listitem>
 193       </itemizedlist>
 194
 195       <para>To compile a module which is to be part of a new package,
 196       use the <literal>-package-name</literal> option:</para>
 197
 198       <variablelist>
 199         <varlistentry>
 200           <term>
 201             <option>-package-name <replaceable>foo</replaceable></option>
 202             <indexterm><primary><literal>-package-name</literal></primary><secondary>option</secondary></indexterm>
 203           </term>
 204           <listitem>
 205             <para>This option is added to the command line when
 206             compiling a module that is destined to be part of package
 207             <literal>foo</literal>.  If this flag is omitted then the
 208             default package <literal>Main</literal> is assumed.</para>
 209           </listitem>
 210         </varlistentry>
 211       </variablelist>
 212
 213       <para>Failure to use the <literal>-package-name</literal> option
 214       when compiling a package will result in disaster on Windows, but
 215       is relatively harmless on Unix at the moment (it will just cause
 216       a few extra dependencies in some interface files).  However,
 217       bear in mind that we might add support for Unix shared libraries
 218       at some point in the future.</para>
 219
 220       <para>It is worth noting that on Windows, when each package
 221       is built as a DLL, since a reference to a DLL costs an extra
 222       indirection, intra-package references are cheaper than
 223       inter-package references. Of course, this applies to the
 224       <filename>Main</filename> package as well.</para>
 225     </sect2>
 226
 227     <sect2 id="package-management">
 228       <title>Package management</title>
 229       <indexterm><primary>packages</primary>
 230         <secondary>management</secondary></indexterm>
 231
 232       <para>The <literal>ghc-pkg</literal> tool allows packages to be
 233       added or removed from a package configuration file.  By default,
 234       the system-wide configuration file is used, but alternatively
 235       packages can be added, updated or removed from a user-specified
 236       configuration file using the <option>&ndash;&ndash;config-file</option>
 237       option.  An empty package configuration file consists of the
 238       string <quote><literal>[]</literal></quote>.</para>
 239
 240       <para>The <literal>ghc-pkg</literal> program accepts the
 241       following options:</para>
 242
 243       <variablelist>
 244         <varlistentry>
 245           <term>
 246             <option>&ndash;&ndash;add-package</option>
 247             <indexterm><primary><option>&ndash;&ndash;add-package</option></primary></indexterm>
 248           </term>
 249           <term>
 250             <option>-a</option>
 251           </term>
 252           <listitem>
 253             <para>Reads package specification from the input (see below),
 254             and adds it to the database of installed packages.  The
 255             package specification must be a package that isn't already
 256             installed.</para>
 257           </listitem>
 258         </varlistentry>
 259
 260         <varlistentry>
 261           <term>
 262             <option>&ndash;&ndash;input-file=<replaceable>file</replaceable></option>
 263             <indexterm><primary><option>&ndash;&ndash;input-file</option></primary></indexterm>
 264           </term>
 265           <term>
 266             <option>-i <replaceable>file</replaceable></option>
 267           </term>
 268           <listitem>
 269             <para>Read new package specifications from file
 270             <replaceable>file</replaceable>. If a value of
 271             <filename>"-"</filename> is given, standard input is used.
 272             If no <option>-i</option> is present on the command-line,
 273             an input file of <filename>"-"</filename> is assumed.
 274             </para>
 275           </listitem>
 276         </varlistentry>
 277
 278         <varlistentry>
 279           <term>
 280             <option>&ndash;&ndash;auto-ghci-libs</option>
 281             <indexterm><primary><option>&ndash;&ndash;auto-ghci-libs</option></primary></indexterm>
 282           </term>
 283           <term>
 284             <option>-g</option>
 285           </term>
 286           <listitem>
 287             <para>Automatically generate the GHCi
 288             <filename>.o</filename> version of each
 289             <filename>.a</filename> Haskell library, using GNU ld (if
 290             that is available).  Without this option,
 291             <literal>ghc-pkg</literal> will warn if GHCi versions of
 292             any Haskell libraries in the package don't exist.</para>
 293
 294             <para>GHCi <literal>.o</literal> libraries don't
 295             necessarily have to live in the same directory as the
 296             corresponding <literal>.a</literal> library.  However,
 297             this option will cause the GHCi library to be created in
 298             the same directory as the <literal>.a</literal>
 299             library.</para>
 300           </listitem>
 301         </varlistentry>
 302
 303         <varlistentry>
 304           <term>
 305             <option>&ndash;&ndash;config-file <replaceable>file</replaceable></option>
 306             <indexterm><primary><option>&ndash;&ndash;config-file</option></primary></indexterm>
 307           </term>
 308           <term>
 309             <option>-f <replaceable>file</replaceable></option>
 310           </term>
 311           <listitem>
 312             <para>Use <replaceable>file</replaceable> as an additional
 313             package configuration file. This is used to modify
 314             configuration files for use with GHC's
 315             <option>-package-conf</option> option.</para>
 316
 317             <para>There may be any number of configuration files named
 318             on the command line; files mentioned later on the
 319             command-line override those mentioned earlier.  The
 320             <emphasis>last</emphasis> configuration file mentioned on
 321             the command-line is the only one that is actually modified
 322             by <literal>ghc-pkg</literal>.</para>
 323
 324           </listitem>
 325         </varlistentry>
 326
 327         <varlistentry>
 328           <term>
 329             <option>&ndash;&ndash;list-packages</option>
 330             <indexterm><primary><option>&ndash;&ndash;list-packages</option></primary></indexterm>
 331           </term>
 332           <term>
 333             <option>-l</option>
 334           </term>
 335           <listitem>
 336             <para>This option displays the list of currently installed
 337             packages, including those in extra configuration files
 338             specified with the <option>&ndash;&ndash;config-file</option>
 339             option.</para>
 340
 341 <screen>
 342   $ ghc-pkg &ndash;&ndash;list-packages
 343   /usr/local/lib/ghc-5.05/package.conf:
 344     hdirect, readline, lang, concurrent, posix, util, data, text, net,
 345     hssource, rts, haskell98, network, haskell-src, unix, base
 346 </screen>
 347
 348             <para>Note that your GHC installation might have a
 349             slightly different set of packages installed.</para>
 350
 351             <para>The <literal>rts</literal> package is always
 352             present, and represents the runtime system library.  The
 353             <literal>base</literal> package contains the Haskell
 354             prelude and basic hierarchical libraries, and the
 355             <literal>haskell98</literal> package contains the Haskell
 356             98 standard libraries.  The rest of the packages are
 357             optional libraries.</para>
 358           </listitem>
 359         </varlistentry>
 360
 361         <varlistentry>
 362           <term>
 363             <option>&ndash;&ndash;list-local-packages</option>
 364             <indexterm><primary><option>&ndash;&ndash;list-local-packages</option></primary></indexterm>
 365           </term>
 366           <term>
 367             <option>-L</option>
 368           </term>
 369           <listitem>
 370             <para>Displays the list of packages installed in the
 371             topmost configuration file only: that will be the
 372             configuration file specified using <option>-f</option> on
 373             the command line, or the system configuration file
 374             otherwise.</para>
 375
 376             <para>This option may be more convenient than
 377             <option>-l</option> when the output needs to be parsed by
 378             a script.</para>
 379           </listitem>
 380         </varlistentry>
 381
 382         <varlistentry>
 383           <term>
 384             <option>&ndash;&ndash;remove-package <replaceable>foo</replaceable></option>
 385             <indexterm><primary><option>&ndash;&ndash;delete-package</option></primary></indexterm>
 386           </term>
 387           <term>
 388             <option>-r <replaceable>foo</replaceable></option>
 389           </term>
 390           <listitem>
 391             <para>Removes the specified package from the installed
 392             configuration.</para>
 393           </listitem>
 394         </varlistentry>
 395         <varlistentry>
 396           <term>
 397             <option>&ndash;&ndash;update-package</option>
 398             <indexterm><primary><option>&ndash;&ndash;update-package</option></primary></indexterm>
 399           </term>
 400           <term>
 401             <option>-u</option>
 402           </term>
 403           <listitem>
 404             <para>Reads package specification from the input, and
 405             adds it to the database of installed packages. If a package
 406             with the same name is already installed, its configuration
 407             data is replaced with the new information. If the package
 408             doesn't already exist, it's added.
 409             </para>
 410           </listitem>
 411         </varlistentry>
 412         <varlistentry>
 413           <term>
 414             <option>&ndash;&ndash;force</option>
 415             <indexterm><primary><option>&ndash;&ndash;force</option></primary></indexterm>
 416           </term>
 417           <listitem>
 418             <para>Causes <literal>ghc-pkg</literal> to ignore missing
 419             directories and libraries when adding a package, and just
 420             go ahead and add it anyway.  This might be useful if your
 421             package installation system needs to add the package to
 422             GHC before building and installing the files.</para>
 423           </listitem>
 424         </varlistentry>
 425       </variablelist>
 426
 427       <para>When modifying the configuration file
 428       <replaceable>file</replaceable>, a copy of the original file is
 429       saved in <replaceable>file</replaceable><literal>.old</literal>,
 430       so in an emergency you can always restore the old settings by
 431       copying the old file back again.</para>
 432
 433       <para>A package specification looks like this:</para>
 434
 435 <screen>
 436   Package {
 437      name            = "mypkg",
 438      auto            = True,
 439      import_dirs     = ["${installdir}/imports/mypkg"],
 440      source_dirs     = [],
 441      library_dirs    = ["${installdir}"],
 442      hs_libraries    = ["HSmypkg" ],
 443      extra_libraries = ["HSmypkg_cbits"],
 444      include_dirs    = [],
 445      c_includes      = ["HsMyPkg.h"],
 446      package_deps    = ["text", "data"],
 447      extra_ghc_opts  = [],
 448      extra_cc_opts   = [],
 449      extra_ld_opts   = ["-lmy_clib"]
 450   }
 451 </screen>
 452
 453       <para>Components of a package specification may be specified in
 454       any order, and are:</para>
 455
 456       <variablelist>
 457         <varlistentry>
 458           <term>
 459             <literal>name</literal>
 460             <indexterm><primary><literal>name</literal></primary><secondary>package specification</secondary></indexterm>
 461           </term>
 462           <listitem>
 463             <para>The package's name, for use with
 464             the <literal>-package</literal> flag and as listed in the
 465             <literal>&ndash;&ndash;list-packages</literal> list.
 466             </para>
 467           </listitem>
 468         </varlistentry>
 469
 470         <varlistentry>
 471           <term>
 472             <literal>auto</literal>
 473             <indexterm><primary><literal>auto</literal></primary><secondary>package specification</secondary></indexterm>
 474           </term>
 475           <listitem>
 476             <para>Set to <literal>True</literal> if the package should
 477             be automatically available (see <xref
 478             linkend="using-packages"/>).  This is normally set to
 479             <literal>True</literal> for packages which contain
 480             hierarchical libraries, because in that case there is no
 481             danger of polluting the module namespace.</para>
 482           </listitem>
 483         </varlistentry>
 484
 485         <varlistentry>
 486           <term>
 487             <literal>import_dirs</literal>
 488             <indexterm><primary><literal>import_dirs</literal></primary><secondary>package specification</secondary></indexterm>
 489           </term>
 490           <listitem>
 491             <para>A list of directories containing interface files
 492             (<literal>.hi</literal> files) for this package.</para>
 493
 494             <para>If the package contains profiling libraries, then
 495             the interface files for those library modules should have
 496             the suffix <literal>.p_hi</literal>.  So the package can
 497             contain both normal and profiling versions of the same
 498             library without conflict (see also
 499             <literal>library_dirs</literal> below).</para>
 500           </listitem>
 501         </varlistentry>
 502
 503         <varlistentry>
 504           <term>
 505             <literal>source_dirs</literal>
 506             <indexterm><primary><literal>source_dirs</literal></primary><secondary>package specification</secondary></indexterm>
 507           </term>
 508           <listitem>
 509             <para>A list of directories containing Haskell source
 510             files for this package.  This field isn't used by GHC, but
 511             could potentially be used by an all-interpreted system
 512             like Hugs.</para>
 513           </listitem>
 514         </varlistentry>
 515
 516         <varlistentry>
 517           <term>
 518             <literal>library_dirs</literal>
 519             <indexterm><primary><literal>library_dirs</literal></primary><secondary>package specification</secondary></indexterm>
 520           </term>
 521           <listitem>
 522             <para>A list of directories containing libraries for this
 523             package.</para>
 524           </listitem>
 525         </varlistentry>
 526
 527         <varlistentry>
 528           <term>
 529             <literal>hs_libraries</literal>
 530             <indexterm><primary><literal>hs_libraries</literal></primary><secondary>package specification</secondary></indexterm>
 531           </term>
 532           <listitem>
 533             <para>A list of libraries containing Haskell code for this
 534             package, with the <literal>.a</literal> or
 535             <literal>.dll</literal> suffix omitted.  When packages are
 536             built as libraries, the
 537             <literal>lib</literal> prefix is also omitted.</para>
 538
 539             <para>For use with GHCi, each library should have an
 540             object file too.  The name of the object file does
 541             <emphasis>not</emphasis> have a <literal>lib</literal>
 542             prefix, and has the normal object suffix for your
 543             platform.</para>
 544
 545             <para>For example, if we specify a Haskell library as
 546             <filename>HSfoo</filename> in the package spec, then the
 547             various flavours of library that GHC actually uses will be
 548             called:</para>
 549             <variablelist>
 550               <varlistentry>
 551                 <term><filename>libHSfoo.a</filename></term>
 552                 <listitem>
 553                   <para>The name of the library on Unix and Windows
 554                   (mingw) systems.  Note that we don't support
 555                   building dynamic libraries of Haskell code on Unix
 556                   systems.</para>
 557                 </listitem>
 558               </varlistentry>
 559               <varlistentry>
 560                 <term><filename>HSfoo.dll</filename></term>
 561                 <listitem>
 562                   <para>The name of the dynamic library on Windows
 563                   systems (optional).</para>
 564                 </listitem>
 565               </varlistentry>
 566               <varlistentry>
 567                 <term><filename>HSfoo.o</filename></term>
 568                 <term><filename>HSfoo.obj</filename></term>
 569                 <listitem>
 570                   <para>The object version of the library used by
 571                   GHCi.</para>
 572                 </listitem>
 573               </varlistentry>
 574             </variablelist>
 575
 576           </listitem>
 577         </varlistentry>
 578
 579         <varlistentry>
 580           <term>
 581             <literal>extra_libraries</literal>
 582             <indexterm><primary><literal>extra_libraries</literal></primary><secondary>package specification</secondary></indexterm>
 583           </term>
 584           <listitem>
 585             <para>A list of extra libraries for this package.  The
 586             difference between <literal>hs_libraries</literal> and
 587             <literal>extra_libraries</literal> is that
 588             <literal>hs_libraries</literal> normally have several
 589             versions, to support profiling, parallel and other build
 590             options.  The various versions are given different
 591             suffixes to distinguish them, for example the profiling
 592             version of the standard prelude library is named
 593             <filename>libHSstd_p.a</filename>, with the
 594             <literal>_p</literal> indicating that this is a profiling
 595             version.  The suffix is added automatically by GHC for
 596             <literal>hs_libraries</literal> only, no suffix is added
 597             for libraries in
 598             <literal>extra_libraries</literal>.</para>
 599
 600             <para>The libraries listed in
 601             <literal>extra_libraries</literal> may be any libraries
 602             supported by your system's linker, including dynamic
 603             libraries (<literal>.so</literal> on Unix,
 604             <literal>.DLL</literal> on Windows).</para>
 605
 606             <para>Also, <literal>extra_libraries</literal> are placed
 607             on the linker command line after the
 608             <literal>hs_libraries</literal> for the same package.  If
 609             your package has dependencies in the other direction (i.e.
 610             <literal>extra_libraries</literal> depends on
 611             <literal>hs_libraries</literal>), and the libraries are
 612             static, you might need to make two separate
 613             packages.</para>
 614           </listitem>
 615         </varlistentry>
 616
 617         <varlistentry>
 618           <term>
 619             <literal>include_dirs</literal>
 620             <indexterm><primary><literal>include_dirs</literal></primary><secondary>package specification</secondary></indexterm>
 621           </term>
 622           <listitem>
 623             <para>A list of directories containing C includes for this
 624             package (maybe the empty list).</para>
 625           </listitem>
 626         </varlistentry>
 627
 628         <varlistentry>
 629           <term>
 630            <literal>c_includes</literal>
 631            <indexterm><primary><literal>c_includes</literal></primary><secondary>package specification</secondary></indexterm>
 632           </term>
 633           <listitem>
 634             <para>A list of files to include for via-C compilations
 635             using this package.  Typically this include file will
 636             contain function prototypes for any C functions used in
 637             the package, in case they end up being called as a result
 638             of Haskell functions from the package being
 639             inlined.</para>
 640           </listitem>
 641         </varlistentry>
 642
 643         <varlistentry>
 644           <term>
 645             <literal>package_deps</literal>
 646             <indexterm><primary><literal>package_deps</literal></primary><secondary>package specification</secondary></indexterm>
 647           </term>
 648           <listitem>
 649             <para>A list of packages which this package depends
 650             on.</para>
 651           </listitem>
 652         </varlistentry>
 653
 654         <varlistentry>
 655           <term>
 656             <literal>extra_ghc_opts</literal>
 657             <indexterm><primary><literal>extra_ghc_opts</literal></primary><secondary>package specification</secondary></indexterm>
 658           </term>
 659           <listitem>
 660             <para>Extra arguments to be added to the GHC command line
 661             when this package is being used.</para>
 662           </listitem>
 663         </varlistentry>
 664
 665         <varlistentry>
 666           <term>
 667             <literal>extra_cc_opts</literal>
 668             <indexterm><primary><literal>extra_cc_opts</literal></primary><secondary>package specification</secondary></indexterm>
 669           </term>
 670           <listitem>
 671             <para>Extra arguments to be added to the gcc command line
 672             when this package is being used (only for via-C
 673             compilations).</para>
 674           </listitem>
 675         </varlistentry>
 676
 677         <varlistentry>
 678           <term>
 679             <literal>extra_ld_opts</literal>
 680             <indexterm><primary><literal>extra_ld_opts</literal></primary><secondary>package specification</secondary></indexterm>
 681           </term>
 682           <listitem>
 683             <para>Extra arguments to be added to the
 684             <command>gcc</command> command line (for linking) when
 685             this package is being used.</para>
 686           </listitem>
 687         </varlistentry>
 688
 689         <varlistentry>
 690           <term>
 691             <literal>framework_dirs</literal>
 692             <indexterm><primary><literal>framework_dirs</literal></primary><secondary>package specification</secondary></indexterm>
 693           </term>
 694           <listitem>
 695             <para>On Darwin/MacOS X, a list of directories containing frameworks for this
 696             package. This corresponds to the <option>-framework-path</option> option.
 697             It is ignored on all other platforms.</para>
 698           </listitem>
 699         </varlistentry>
 700
 701         <varlistentry>
 702           <term>
 703             <literal>extra_frameworks</literal>
 704             <indexterm><primary><literal>extra_frameworks</literal></primary><secondary>package specification</secondary></indexterm>
 705           </term>
 706           <listitem>
 707             <para>On Darwin/MacOS X, a list of frameworks to link to. This corresponds to the
 708             <option>-framework</option> option. Take a look at Apple's developer documentation
 709             to find out what frameworks actually are. This entry is ignored on all other platforms.</para>
 710           </listitem>
 711         </varlistentry>
 712       </variablelist>
 713
 714       <para>
 715       The <literal>ghc-pkg</literal> tool performs expansion of
 716       environment variables occurring in input package specifications.
 717       So, if the <literal>mypkg</literal> was added to the package
 718       database as follows:
 719       </para>
 720 <screen>
 721   $ installdir=/usr/local/lib ghc-pkg -a &lt; mypkg.pkg
 722 </screen>
 723
 724       <para>
 725       The occurrence of <literal>${installdir}</literal> is replaced
 726       with <literal>/usr/local/lib</literal> in the package data that
 727       is added for <literal>mypkg</literal>.
 728       </para>
 729
 730       <para>
 731       This feature enables the distribution of package specification
 732       files that can be easily configured when installing.
 733       </para>
 734
 735       <para>For examples of more package specifications, take a look
 736       at the <literal>package.conf</literal> in your GHC
 737       installation.</para>
 738     </sect2>
 739   </sect1>
 740
 741 <!-- Emacs stuff:
 742      ;;; Local Variables: ***
 743      ;;; mode: xml ***
 744      ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter" "sect1") ***
 745      ;;; End: ***
 746  -->