ghc/docs/users_guide/packages.sgml

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