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