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><option>&ndash;&ndash;config-file <replaceable>file</replaceable></option></term>
 305           <term><option>-f <replaceable>file</replaceable></option></term>
 306           <indexterm><primary><option>&ndash;&ndash;config-file</option></primary>
 307               </indexterm>
 308           <listitem>
 309             <para>Use <replaceable>file</replaceable> as an additional
 310             package configuration file. This is used to modify
 311             configuration files for use with GHC's
 312             <option>-package-conf</option> option.</para>
 313
 314             <para>There may be any number of configuration files named
 315             on the command line; files mentioned later on the
 316             command-line override those mentioned earlier.  The
 317             <emphasis>last</emphasis> configuration file mentioned on
 318             the command-line is the only one that is actually modified
 319             by <literal>ghc-pkg</literal>.</para>
 320
 321           </listitem>
 322         </varlistentry>
 323
 324         <varlistentry>
 325           <term><option>&ndash;&ndash;list-packages</option></term>
 326           <term><option>-l</option></term>
 327           <indexterm><primary><option>&ndash;&ndash;list-packages</option></primary></indexterm>
 328           <listitem>
 329             <para>This option displays the list of currently installed
 330             packages, including those in extra configuration files
 331             specified with the <option>&ndash;&ndash;config-file</option>
 332             option.</para>
 333
 334 <screen>
 335   $ ghc-pkg &ndash;&ndash;list-packages
 336   /usr/local/lib/ghc-5.05/package.conf:
 337     hdirect, readline, lang, concurrent, posix, util, data, text, net,
 338     hssource, rts, haskell98, network, haskell-src, unix, base
 339 </screen>
 340
 341             <para>Note that your GHC installation might have a
 342             slightly different set of packages installed.</para>
 343
 344             <para>The <literal>rts</literal> package is always
 345             present, and represents the runtime system library.  The
 346             <literal>base</literal> package contains the Haskell
 347             prelude and basic hierarchical libraries, and the
 348             <literal>haskell98</literal> package contains the Haskell
 349             98 standard libraries.  The rest of the packages are
 350             optional libraries.</para>
 351           </listitem>
 352         </varlistentry>
 353
 354         <varlistentry>
 355           <term><option>&ndash;&ndash;list-local-packages</option></term>
 356           <term><option>-L</option></term>
 357           <indexterm><primary><option>&ndash;&ndash;list-local-packages</option></primary></indexterm>
 358           <listitem>
 359             <para>Displays the list of packages installed in the
 360             topmost configuration file only: that will be the
 361             configuration file specified using <option>-f</option> on
 362             the command line, or the system configuration file
 363             otherwise.</para>
 364
 365             <para>This option may be more convenient than
 366             <option>-l</option> when the output needs to be parsed by
 367             a script.</para>
 368           </listitem>
 369         </varlistentry>
 370
 371         <varlistentry>
 372           <term><option>&ndash;&ndash;remove-package <replaceable>foo</replaceable></option></term>
 373           <term><option>-r <replaceable>foo</replaceable></option></term>
 374           <indexterm><primary><option>&ndash;&ndash;delete-package</option></primary>
 375               </indexterm>
 376           <listitem>
 377             <para>Removes the specified package from the installed
 378             configuration.</para>
 379           </listitem>
 380         </varlistentry>
 381         <varlistentry>
 382           <term><option>&ndash;&ndash;update-package</option></term>
 383           <term><option>-u</option></term>
 384           <indexterm><primary><option>&ndash;&ndash;update-package</option></primary></indexterm>
 385           <listitem>
 386             <para>Reads package specification from the input, and
 387             adds it to the database of installed packages. If a package
 388             with the same name is already installed, its configuration
 389             data is replaced with the new information. If the package
 390             doesn't already exist, it's added.
 391             </para>
 392           </listitem>
 393         </varlistentry>
 394         <varlistentry>
 395           <term><option>&ndash;&ndash;force</option></term>
 396           <indexterm><primary><option>&ndash;&ndash;force</option></primary></indexterm>
 397           <listitem>
 398             <para>Causes <literal>ghc-pkg</literal> to ignore missing
 399             directories and libraries when adding a package, and just
 400             go ahead and add it anyway.  This might be useful if your
 401             package installation system needs to add the package to
 402             GHC before building and installing the files.</para>
 403           </listitem>
 404         </varlistentry>
 405       </variablelist>
 406
 407       <para>When modifying the configuration file
 408       <replaceable>file</replaceable>, a copy of the original file is
 409       saved in <replaceable>file</replaceable><literal>.old</literal>,
 410       so in an emergency you can always restore the old settings by
 411       copying the old file back again.</para>
 412
 413       <para>A package specification looks like this:</para>
 414
 415 <screen>
 416   Package {
 417      name            = "mypkg",
 418      auto            = True,
 419      import_dirs     = ["${installdir}/imports/mypkg"],
 420      source_dirs     = [],
 421      library_dirs    = ["${installdir}"],
 422      hs_libraries    = ["HSmypkg" ],
 423      extra_libraries = ["HSmypkg_cbits"],
 424      include_dirs    = [],
 425      c_includes      = ["HsMyPkg.h"],
 426      package_deps    = ["text", "data"],
 427      extra_ghc_opts  = [],
 428      extra_cc_opts   = [],
 429      extra_ld_opts   = ["-lmy_clib"]
 430   }
 431 </screen>
 432
 433       <para>Components of a package specification may be specified in
 434       any order, and are:</para>
 435
 436       <variablelist>
 437         <varlistentry>
 438           <term><literal>name</literal></term>
 439           <indexterm><primary><literal>name</literal></primary>
 440             <secondary>package specification</secondary></indexterm>
 441           <listitem>
 442             <para>The package's name, for use with
 443             the <literal>-package</literal> flag and as listed in the
 444             <literal>&ndash;&ndash;list-packages</literal> list.
 445             </para>
 446           </listitem>
 447         </varlistentry>
 448
 449         <varlistentry>
 450           <term><literal>auto</literal></term>
 451           <indexterm><primary><literal>auto</literal></primary>
 452             <secondary>package specification</secondary>
 453           </indexterm>
 454           <listitem>
 455             <para>Set to <literal>True</literal> if the package should
 456             be automatically available (see <xref
 457             linkend="using-packages"/>).  This is normally set to
 458             <literal>True</literal> for packages which contain
 459             hierarchical libraries, because in that case there is no
 460             danger of polluting the module namespace.</para>
 461           </listitem>
 462         </varlistentry>
 463
 464         <varlistentry>
 465           <term><literal>import_dirs</literal></term>
 466           <indexterm><primary><literal>import_dirs</literal></primary>
 467             <secondary>package specification</secondary></indexterm>
 468           <listitem>
 469             <para>A list of directories containing interface files
 470             (<literal>.hi</literal> files) for this package.</para>
 471
 472             <para>If the package contains profiling libraries, then
 473             the interface files for those library modules should have
 474             the suffix <literal>.p_hi</literal>.  So the package can
 475             contain both normal and profiling versions of the same
 476             library without conflict (see also
 477             <literal>library_dirs</literal> below).</para>
 478           </listitem>
 479         </varlistentry>
 480
 481         <varlistentry>
 482           <term><literal>source_dirs</literal></term>
 483           <indexterm><primary><literal>source_dirs</literal></primary>
 484             <secondary>package specification</secondary></indexterm>
 485           <listitem>
 486             <para>A list of directories containing Haskell source
 487             files for this package.  This field isn't used by GHC, but
 488             could potentially be used by an all-interpreted system
 489             like Hugs.</para>
 490           </listitem>
 491         </varlistentry>
 492
 493         <varlistentry>
 494           <term><literal>library_dirs</literal></term>
 495           <indexterm><primary><literal>library_dirs</literal></primary>
 496             <secondary>package specification</secondary></indexterm>
 497           <listitem>
 498             <para>A list of directories containing libraries for this
 499             package.</para>
 500           </listitem>
 501         </varlistentry>
 502
 503         <varlistentry>
 504           <term><literal>hs_libraries</literal></term>
 505           <indexterm><primary><literal>hs_libraries</literal></primary>
 506             <secondary>package specification</secondary></indexterm>
 507           <listitem>
 508             <para>A list of libraries containing Haskell code for this
 509             package, with the <literal>.a</literal> or
 510             <literal>.dll</literal> suffix omitted.  When packages are
 511             built as libraries, the
 512             <literal>lib</literal> prefix is also omitted.</para>
 513
 514             <para>For use with GHCi, each library should have an
 515             object file too.  The name of the object file does
 516             <emphasis>not</emphasis> have a <literal>lib</literal>
 517             prefix, and has the normal object suffix for your
 518             platform.</para>
 519
 520             <para>For example, if we specify a Haskell library as
 521             <filename>HSfoo</filename> in the package spec, then the
 522             various flavours of library that GHC actually uses will be
 523             called:</para>
 524             <variablelist>
 525               <varlistentry>
 526                 <term><filename>libHSfoo.a</filename></term>
 527                 <listitem>
 528                   <para>The name of the library on Unix and Windows
 529                   (mingw) systems.  Note that we don't support
 530                   building dynamic libraries of Haskell code on Unix
 531                   systems.</para>
 532                 </listitem>
 533               </varlistentry>
 534               <varlistentry>
 535                 <term><filename>HSfoo.dll</filename></term>
 536                 <listitem>
 537                   <para>The name of the dynamic library on Windows
 538                   systems (optional).</para>
 539                 </listitem>
 540               </varlistentry>
 541               <varlistentry>
 542                 <term><filename>HSfoo.o</filename></term>
 543                 <term><filename>HSfoo.obj</filename></term>
 544                 <listitem>
 545                   <para>The object version of the library used by
 546                   GHCi.</para>
 547                 </listitem>
 548               </varlistentry>
 549             </variablelist>
 550
 551           </listitem>
 552         </varlistentry>
 553
 554         <varlistentry>
 555           <term><literal>extra_libraries</literal></term>
 556           <indexterm><primary><literal>extra_libraries</literal></primary>
 557             <secondary>package specification</secondary></indexterm>
 558           <listitem>
 559             <para>A list of extra libraries for this package.  The
 560             difference between <literal>hs_libraries</literal> and
 561             <literal>extra_libraries</literal> is that
 562             <literal>hs_libraries</literal> normally have several
 563             versions, to support profiling, parallel and other build
 564             options.  The various versions are given different
 565             suffixes to distinguish them, for example the profiling
 566             version of the standard prelude library is named
 567             <filename>libHSstd_p.a</filename>, with the
 568             <literal>_p</literal> indicating that this is a profiling
 569             version.  The suffix is added automatically by GHC for
 570             <literal>hs_libraries</literal> only, no suffix is added
 571             for libraries in
 572             <literal>extra_libraries</literal>.</para>
 573
 574             <para>The libraries listed in
 575             <literal>extra_libraries</literal> may be any libraries
 576             supported by your system's linker, including dynamic
 577             libraries (<literal>.so</literal> on Unix,
 578             <literal>.DLL</literal> on Windows).</para>
 579
 580             <para>Also, <literal>extra_libraries</literal> are placed
 581             on the linker command line after the
 582             <literal>hs_libraries</literal> for the same package.  If
 583             your package has dependencies in the other direction (i.e.
 584             <literal>extra_libraries</literal> depends on
 585             <literal>hs_libraries</literal>), and the libraries are
 586             static, you might need to make two separate
 587             packages.</para>
 588           </listitem>
 589         </varlistentry>
 590
 591         <varlistentry>
 592           <term><literal>include_dirs</literal></term>
 593           <indexterm><primary><literal>include_dirs</literal></primary>
 594             <secondary>package specification</secondary></indexterm>
 595           <listitem>
 596             <para>A list of directories containing C includes for this
 597             package (maybe the empty list).</para>
 598           </listitem>
 599         </varlistentry>
 600
 601         <varlistentry>
 602           <term><literal>c_includes</literal></term>
 603           <indexterm><primary><literal>c_includes</literal></primary>
 604             <secondary>package specification</secondary></indexterm>
 605           <listitem>
 606             <para>A list of files to include for via-C compilations
 607             using this package.  Typically this include file will
 608             contain function prototypes for any C functions used in
 609             the package, in case they end up being called as a result
 610             of Haskell functions from the package being
 611             inlined.</para>
 612           </listitem>
 613         </varlistentry>
 614
 615         <varlistentry>
 616           <term><literal>package_deps</literal></term>
 617           <indexterm><primary><literal>package_deps</literal></primary>
 618             <secondary>package specification</secondary></indexterm>
 619           <listitem>
 620             <para>A list of packages which this package depends
 621             on.</para>
 622           </listitem>
 623         </varlistentry>
 624
 625         <varlistentry>
 626           <term><literal>extra_ghc_opts</literal></term>
 627           <indexterm><primary><literal>extra_ghc_opts</literal></primary>
 628             <secondary>package specification</secondary></indexterm>
 629           <listitem>
 630             <para>Extra arguments to be added to the GHC command line
 631             when this package is being used.</para>
 632           </listitem>
 633         </varlistentry>
 634
 635         <varlistentry>
 636           <term><literal>extra_cc_opts</literal></term>
 637           <indexterm><primary><literal>extra_cc_opts</literal></primary>
 638             <secondary>package specification</secondary></indexterm>
 639           <listitem>
 640             <para>Extra arguments to be added to the gcc command line
 641             when this package is being used (only for via-C
 642             compilations).</para>
 643           </listitem>
 644         </varlistentry>
 645
 646         <varlistentry>
 647           <term><literal>extra_ld_opts</literal></term>
 648           <indexterm><primary><literal>extra_ld_opts</literal></primary>
 649             <secondary>package specification</secondary></indexterm>
 650           <listitem>
 651             <para>Extra arguments to be added to the
 652             <command>gcc</command> command line (for linking) when
 653             this package is being used.</para>
 654           </listitem>
 655         </varlistentry>
 656
 657         <varlistentry>
 658           <term><literal>framework_dirs</literal></term>
 659           <indexterm><primary><literal>framework_dirs</literal></primary>
 660             <secondary>package specification</secondary></indexterm>
 661           <listitem>
 662             <para>On Darwin/MacOS X, a list of directories containing frameworks for this
 663             package. This corresponds to the <option>-framework-path</option> option.
 664             It is ignored on all other platforms.</para>
 665           </listitem>
 666         </varlistentry>
 667
 668         <varlistentry>
 669           <term><literal>extra_frameworks</literal></term>
 670           <indexterm><primary><literal>extra_frameworks</literal></primary>
 671             <secondary>package specification</secondary></indexterm>
 672           <listitem>
 673             <para>On Darwin/MacOS X, a list of frameworks to link to. This corresponds to the
 674             <option>-framework</option> option. Take a look at Apple's developer documentation
 675             to find out what frameworks actually are. This entry is ignored on all other platforms.</para>
 676           </listitem>
 677         </varlistentry>
 678       </variablelist>
 679
 680       <para>
 681       The <literal>ghc-pkg</literal> tool performs expansion of
 682       environment variables occurring in input package specifications.
 683       So, if the <literal>mypkg</literal> was added to the package
 684       database as follows:
 685       </para>
 686 <screen>
 687   $ installdir=/usr/local/lib ghc-pkg -a &lt; mypkg.pkg
 688 </screen>
 689
 690       <para>
 691       The occurrence of <literal>${installdir}</literal> is replaced
 692       with <literal>/usr/local/lib</literal> in the package data that
 693       is added for <literal>mypkg</literal>.
 694       </para>
 695
 696       <para>
 697       This feature enables the distribution of package specification
 698       files that can be easily configured when installing.
 699       </para>
 700
 701       <para>For examples of more package specifications, take a look
 702       at the <literal>package.conf</literal> in your GHC
 703       installation.</para>
 704     </sect2>
 705   </sect1>
 706
 707 <!-- Emacs stuff:
 708      ;;; Local Variables: ***
 709      ;;; mode: xml ***
 710      ;;; sgml-parent-document: ("using.sgml" "book" "chapter") ***
 711      ;;; End: ***
 712  -->