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>(replace
 171           <literal>&ndash;&ndash;--whole-archive</literal> with
 172           <literal>&ndash;all_load</literal> on MacOS X)</para>
 173
 174           <para>GHC does not maintain detailed cross-package
 175           dependency information.  It does remember which modules in
 176           other packages the current module depends on, but not which
 177           things within those imported things.</para>
 178         </listitem>
 179       </itemizedlist>
 180
 181       <para>To compile a module which is to be part of a new package,
 182       use the <literal>-package-name</literal> option:</para>
 183
 184       <variablelist>
 185         <varlistentry>
 186           <term><option>-package-name <replaceable>foo</replaceable></option></term>
 187           <indexterm><primary><literal>-package-name</literal></primary>
 188             <secondary>option</secondary></indexterm>
 189           <listitem>
 190             <para>This option is added to the command line when
 191             compiling a module that is destined to be part of package
 192             <literal>foo</literal>.  If this flag is omitted then the
 193             default package <literal>Main</literal> is assumed.</para>
 194           </listitem>
 195         </varlistentry>
 196       </variablelist>
 197
 198       <para>Failure to use the <literal>-package-name</literal> option
 199       when compiling a package will result in disaster on Windows, but
 200       is relatively harmless on Unix at the moment (it will just cause
 201       a few extra dependencies in some interface files).  However,
 202       bear in mind that we might add support for Unix shared libraries
 203       at some point in the future.</para>
 204
 205       <para>It is worth noting that on Windows, when each package
 206       is built as a DLL, since a reference to a DLL costs an extra
 207       indirection, intra-package references are cheaper than
 208       inter-package references. Of course, this applies to the
 209       <filename>Main</filename> package as well.</para>
 210     </sect2>
 211
 212     <sect2 id="package-management">
 213       <title>Package management</title>
 214       <indexterm><primary>packages</primary>
 215         <secondary>management</secondary></indexterm>
 216
 217       <para>The <literal>ghc-pkg</literal> tool allows packages to be
 218       added or removed from a package configuration file.  By default,
 219       the system-wide configuration file is used, but alternatively
 220       packages can be added, updated or removed from a user-specified
 221       configuration file using the <option>&ndash;&ndash;config-file</option>
 222       option.  An empty package configuration file consists of the
 223       string <quote><literal>[]</literal></quote>.</para>
 224
 225       <para>The <literal>ghc-pkg</literal> program accepts the
 226       following options:</para>
 227
 228       <variablelist>
 229         <varlistentry>
 230           <term><option>&ndash;&ndash;add-package</option></term>
 231           <term><option>-a</option></term>
 232           <indexterm><primary><option>&ndash;&ndash;add-package</option></primary></indexterm>
 233           <listitem>
 234             <para>Reads package specification from the input (see below),
 235             and adds it to the database of installed packages.  The
 236             package specification must be a package that isn't already
 237             installed.</para>
 238           </listitem>
 239         </varlistentry>
 240
 241         <varlistentry>
 242           <term><option>&ndash;&ndash;input-file=<replaceable>file</replaceable></option></term>
 243           <term><option>-i <replaceable>file</replaceable></option></term>
 244           <indexterm><primary><option>&ndash;&ndash;input-file</option></primary></indexterm>
 245           <listitem>
 246             <para>Read new package specifications from file
 247             <replaceable>file</replaceable>. If a value of
 248             <filename>"-"</filename> is given, standard input is used.
 249             If no <option>-i</option> is present on the command-line,
 250             an input file of <filename>"-"</filename> is assumed.
 251             </para>
 252           </listitem>
 253         </varlistentry>
 254
 255         <varlistentry>
 256           <term><option>&ndash;&ndash;auto-ghci-libs</option></term>
 257           <term><option>-g</option></term>
 258           <indexterm><primary><option>&ndash;&ndash;auto-ghci-libs</option></primary>
 259               </indexterm>
 260           <listitem>
 261             <para>Automatically generate the GHCi
 262             <filename>.o</filename> version of each
 263             <filename>.a</filename> Haskell library, using GNU ld (if
 264             that is available).  Without this option,
 265             <literal>ghc-pkg</literal> will warn if GHCi versions of
 266             any Haskell libraries in the package don't exist.</para>
 267
 268             <para>GHCi <literal>.o</literal> libraries don't
 269             necessarily have to live in the same directory as the
 270             corresponding <literal>.a</literal> library.  However,
 271             this option will cause the GHCi library to be created in
 272             the same directory as the <literal>.a</literal>
 273             library.</para>
 274           </listitem>
 275         </varlistentry>
 276
 277         <varlistentry>
 278           <term><option>&ndash;&ndash;config-file <replaceable>file</replaceable></option></term>
 279           <term><option>-f <replaceable>file</replaceable></option></term>
 280           <indexterm><primary><option>&ndash;&ndash;config-file</option></primary>
 281               </indexterm>
 282           <listitem>
 283             <para>Use <replaceable>file</replaceable> as an additional
 284             package configuration file. This is used to modify
 285             configuration files for use with GHC's
 286             <option>-package-conf</option> option.</para>
 287
 288             <para>There may be any number of configuration files named
 289             on the command line; files mentioned later on the
 290             command-line override those mentioned earlier.  The
 291             <emphasis>last</emphasis> configuration file mentioned on
 292             the command-line is the only one that is actually modified
 293             by <literal>ghc-pkg</literal>.</para>
 294
 295           </listitem>
 296         </varlistentry>
 297
 298         <varlistentry>
 299           <term><option>&ndash;&ndash;list-packages</option></term>
 300           <term><option>-l</option></term>
 301           <indexterm><primary><option>&ndash;&ndash;list-packages</option></primary></indexterm>
 302           <listitem>
 303             <para>This option displays the list of currently installed
 304             packages, including those in extra configuration files
 305             specified with the <option>&ndash;&ndash;config-file</option>
 306             option.</para>
 307
 308 <screen>
 309   $ ghc-pkg &ndash;&ndash;list-packages
 310   /usr/local/lib/ghc-5.05/package.conf:
 311     hdirect, readline, lang, concurrent, posix, util, data, text, net,
 312     hssource, rts, haskell98, network, haskell-src, unix, base
 313 </screen>
 314
 315             <para>Note that your GHC installation might have a
 316             slightly different set of packages installed.</para>
 317
 318             <para>The <literal>rts</literal> package is always
 319             present, and represents the runtime system library.  The
 320             <literal>base</literal> package contains the Haskell
 321             prelude and basic hierarchical libraries, and the
 322             <literal>haskell98</literal> package contains the Haskell
 323             98 standard libraries.  The rest of the packages are
 324             optional libraries.</para>
 325           </listitem>
 326         </varlistentry>
 327
 328         <varlistentry>
 329           <term><option>&ndash;&ndash;list-local-packages</option></term>
 330           <term><option>-L</option></term>
 331           <indexterm><primary><option>&ndash;&ndash;list-local-packages</option></primary></indexterm>
 332           <listitem>
 333             <para>Displays the list of packages installed in the
 334             topmost configuration file only: that will be the
 335             configuration file specified using <option>-f</option> on
 336             the command line, or the system configuration file
 337             otherwise.</para>
 338
 339             <para>This option may be more convenient than
 340             <option>-l</option> when the output needs to be parsed by
 341             a script.</para>
 342           </listitem>
 343         </varlistentry>
 344
 345         <varlistentry>
 346           <term><option>&ndash;&ndash;remove-package <replaceable>foo</replaceable></option></term>
 347           <term><option>-r <replaceable>foo</replaceable></option></term>
 348           <indexterm><primary><option>&ndash;&ndash;delete-package</option></primary>
 349               </indexterm>
 350           <listitem>
 351             <para>Removes the specified package from the installed
 352             configuration.</para>
 353           </listitem>
 354         </varlistentry>
 355         <varlistentry>
 356           <term><option>&ndash;&ndash;update-package</option></term>
 357           <term><option>-u</option></term>
 358           <indexterm><primary><option>&ndash;&ndash;update-package</option></primary></indexterm>
 359           <listitem>
 360             <para>Reads package specification from the input, and
 361             adds it to the database of installed packages. If a package
 362             with the same name is already installed, its configuration
 363             data is replaced with the new information. If the package
 364             doesn't already exist, it's added.
 365             </para>
 366           </listitem>
 367         </varlistentry>
 368         <varlistentry>
 369           <term><option>&ndash;&ndash;force</option></term>
 370           <indexterm><primary><option>&ndash;&ndash;force</option></primary></indexterm>
 371           <listitem>
 372             <para>Causes <literal>ghc-pkg</literal> to ignore missing
 373             directories and libraries when adding a package, and just
 374             go ahead and add it anyway.  This might be useful if your
 375             package installation system needs to add the package to
 376             GHC before building and installing the files.</para>
 377           </listitem>
 378         </varlistentry>
 379       </variablelist>
 380
 381       <para>When modifying the configuration file
 382       <replaceable>file</replaceable>, a copy of the original file is
 383       saved in <replaceable>file</replaceable><literal>.old</literal>,
 384       so in an emergency you can always restore the old settings by
 385       copying the old file back again.</para>
 386
 387       <para>A package specification looks like this:</para>
 388
 389 <screen>
 390   Package {
 391      name            = "mypkg",
 392      auto            = True,
 393      import_dirs     = ["${installdir}/imports/mypkg"],
 394      source_dirs     = [],
 395      library_dirs    = ["${installdir}"],
 396      hs_libraries    = ["HSmypkg" ],
 397      extra_libraries = ["HSmypkg_cbits"],
 398      include_dirs    = [],
 399      c_includes      = ["HsMyPkg.h"],
 400      package_deps    = ["text", "data"],
 401      extra_ghc_opts  = [],
 402      extra_cc_opts   = [],
 403      extra_ld_opts   = ["-lmy_clib"]
 404   }
 405 </screen>
 406
 407       <para>Components of a package specification may be specified in
 408       any order, and are:</para>
 409
 410       <variablelist>
 411         <varlistentry>
 412           <term><literal>name</literal></term>
 413           <indexterm><primary><literal>name</literal></primary>
 414             <secondary>package specification</secondary></indexterm>
 415           <listitem>
 416             <para>The package's name, for use with
 417             the <literal>-package</literal> flag and as listed in the
 418             <literal>&ndash;&ndash;list-packages</literal> list.
 419             </para>
 420           </listitem>
 421         </varlistentry>
 422
 423         <varlistentry>
 424           <term><literal>auto</literal></term>
 425           <indexterm><primary><literal>auto</literal></primary>
 426             <secondary>package specification</secondary>
 427           </indexterm>
 428           <listitem>
 429             <para>Set to <literal>True</literal> if the package should
 430             be automatically available (see <xref
 431             linkend="using-packages">).  This is normally set to
 432             <literal>True</literal> for packages which contain
 433             hierarchical libraries, because in that case there is no
 434             danger of polluting the module namespace.</para>
 435           </listitem>
 436         </varlistentry>
 437
 438         <varlistentry>
 439           <term><literal>import_dirs</literal></term>
 440           <indexterm><primary><literal>import_dirs</literal></primary>
 441             <secondary>package specification</secondary></indexterm>
 442           <listitem>
 443             <para>A list of directories containing interface files
 444             (<literal>.hi</literal> files) for this package.</para>
 445
 446             <para>If the package contains profiling libraries, then
 447             the interface files for those library modules should have
 448             the suffix <literal>.p_hi</literal>.  So the package can
 449             contain both normal and profiling versions of the same
 450             library without conflict (see also
 451             <literal>library_dirs</literal> below).</para>
 452           </listitem>
 453         </varlistentry>
 454
 455         <varlistentry>
 456           <term><literal>source_dirs</literal></term>
 457           <indexterm><primary><literal>source_dirs</literal></primary>
 458             <secondary>package specification</secondary></indexterm>
 459           <listitem>
 460             <para>A list of directories containing Haskell source
 461             files for this package.  This field isn't used by GHC, but
 462             could potentially be used by an all-interpreted system
 463             like Hugs.</para>
 464           </listitem>
 465         </varlistentry>
 466
 467         <varlistentry>
 468           <term><literal>library_dirs</literal></term>
 469           <indexterm><primary><literal>library_dirs</literal></primary>
 470             <secondary>package specification</secondary></indexterm>
 471           <listitem>
 472             <para>A list of directories containing libraries for this
 473             package.</para>
 474           </listitem>
 475         </varlistentry>
 476
 477         <varlistentry>
 478           <term><literal>hs_libraries</literal></term>
 479           <indexterm><primary><literal>hs_libraries</literal></primary>
 480             <secondary>package specification</secondary></indexterm>
 481           <listitem>
 482             <para>A list of libraries containing Haskell code for this
 483             package, with the <literal>.a</literal> or
 484             <literal>.dll</literal> suffix omitted.  When packages are
 485             built as libraries, the
 486             <literal>lib</literal> prefix is also omitted.</para>
 487
 488             <para>For use with GHCi, each library should have an
 489             object file too.  The name of the object file does
 490             <emphasis>not</emphasis> have a <literal>lib</literal>
 491             prefix, and has the normal object suffix for your
 492             platform.</para>
 493
 494             <para>For example, if we specify a Haskell library as
 495             <filename>HSfoo</filename> in the package spec, then the
 496             various flavours of library that GHC actually uses will be
 497             called:</para>
 498             <variablelist>
 499               <varlistentry>
 500                 <term><filename>libHSfoo.a</filename></term>
 501                 <listitem>
 502                   <para>The name of the library on Unix and Windows
 503                   (mingw) systems.  Note that we don't support
 504                   building dynamic libraries of Haskell code on Unix
 505                   systems.</para>
 506                 </listitem>
 507               </varlistentry>
 508               <varlistentry>
 509                 <term><filename>HSfoo.dll</filename></term>
 510                 <listitem>
 511                   <para>The name of the dynamic library on Windows
 512                   systems (optional).</para>
 513                 </listitem>
 514               </varlistentry>
 515               <varlistentry>
 516                 <term><filename>HSfoo.o</filename></term>
 517                 <term><filename>HSfoo.obj</filename></term>
 518                 <listitem>
 519                   <para>The object version of the library used by
 520                   GHCi.</para>
 521                 </listitem>
 522               </varlistentry>
 523             </variablelist>
 524
 525           </listitem>
 526         </varlistentry>
 527
 528         <varlistentry>
 529           <term><literal>extra_libraries</literal></term>
 530           <indexterm><primary><literal>extra_libraries</literal></primary>
 531             <secondary>package specification</secondary></indexterm>
 532           <listitem>
 533             <para>A list of extra libraries for this package.  The
 534             difference between <literal>hs_libraries</literal> and
 535             <literal>extra_libraries</literal> is that
 536             <literal>hs_libraries</literal> normally have several
 537             versions, to support profiling, parallel and other build
 538             options.  The various versions are given different
 539             suffixes to distinguish them, for example the profiling
 540             version of the standard prelude library is named
 541             <filename>libHSstd_p.a</filename>, with the
 542             <literal>_p</literal> indicating that this is a profiling
 543             version.  The suffix is added automatically by GHC for
 544             <literal>hs_libraries</literal> only, no suffix is added
 545             for libraries in
 546             <literal>extra_libraries</literal>.</para>
 547
 548             <para>The libraries listed in
 549             <literal>extra_libraries</literal> may be any libraries
 550             supported by your system's linker, including dynamic
 551             libraries (<literal>.so</literal> on Unix,
 552             <literal>.DLL</literal> on Windows).</para>
 553
 554             <para>Also, <literal>extra_libraries</literal> are placed
 555             on the linker command line after the
 556             <literal>hs_libraries</literal> for the same package.  If
 557             your package has dependencies in the other direction (i.e.
 558             <literal>extra_libraries</literal> depends on
 559             <literal>hs_libraries</literal>), and the libraries are
 560             static, you might need to make two separate
 561             packages.</para>
 562           </listitem>
 563         </varlistentry>
 564
 565         <varlistentry>
 566           <term><literal>include_dirs</literal></term>
 567           <indexterm><primary><literal>include_dirs</literal></primary>
 568             <secondary>package specification</secondary></indexterm>
 569           <listitem>
 570             <para>A list of directories containing C includes for this
 571             package (maybe the empty list).</para>
 572           </listitem>
 573         </varlistentry>
 574
 575         <varlistentry>
 576           <term><literal>c_includes</literal></term>
 577           <indexterm><primary><literal>c_includes</literal></primary>
 578             <secondary>package specification</secondary></indexterm>
 579           <listitem>
 580             <para>A list of files to include for via-C compilations
 581             using this package.  Typically this include file will
 582             contain function prototypes for any C functions used in
 583             the package, in case they end up being called as a result
 584             of Haskell functions from the package being
 585             inlined.</para>
 586           </listitem>
 587         </varlistentry>
 588
 589         <varlistentry>
 590           <term><literal>package_deps</literal></term>
 591           <indexterm><primary><literal>package_deps</literal></primary>
 592             <secondary>package specification</secondary></indexterm>
 593           <listitem>
 594             <para>A list of packages which this package depends
 595             on.</para>
 596           </listitem>
 597         </varlistentry>
 598
 599         <varlistentry>
 600           <term><literal>extra_ghc_opts</literal></term>
 601           <indexterm><primary><literal>extra_ghc_opts</literal></primary>
 602             <secondary>package specification</secondary></indexterm>
 603           <listitem>
 604             <para>Extra arguments to be added to the GHC command line
 605             when this package is being used.</para>
 606           </listitem>
 607         </varlistentry>
 608
 609         <varlistentry>
 610           <term><literal>extra_cc_opts</literal></term>
 611           <indexterm><primary><literal>extra_cc_opts</literal></primary>
 612             <secondary>package specification</secondary></indexterm>
 613           <listitem>
 614             <para>Extra arguments to be added to the gcc command line
 615             when this package is being used (only for via-C
 616             compilations).</para>
 617           </listitem>
 618         </varlistentry>
 619
 620         <varlistentry>
 621           <term><literal>extra_ld_opts</literal></term>
 622           <indexterm><primary><literal>extra_ld_opts</literal></primary>
 623             <secondary>package specification</secondary></indexterm>
 624           <listitem>
 625             <para>Extra arguments to be added to the
 626             <command>gcc</command> command line (for linking) when
 627             this package is being used.</para>
 628           </listitem>
 629         </varlistentry>
 630
 631         <varlistentry>
 632           <term><literal>framework_dirs</literal></term>
 633           <indexterm><primary><literal>framework_dirs</literal></primary>
 634             <secondary>package specification</secondary></indexterm>
 635           <listitem>
 636             <para>On Darwin/MacOS X, a list of directories containing frameworks for this
 637             package. This corresponds to the <option>-framework-path</option> option.
 638             It is ignored on all other platforms.</para>
 639           </listitem>
 640         </varlistentry>
 641
 642         <varlistentry>
 643           <term><literal>extra_frameworks</literal></term>
 644           <indexterm><primary><literal>extra_frameworks</literal></primary>
 645             <secondary>package specification</secondary></indexterm>
 646           <listitem>
 647             <para>On Darwin/MacOS X, a list of frameworks to link to. This corresponds to the
 648             <option>-framework</option> option. Take a look at Apple's developer documentation
 649             to find out what frameworks actually are. This entry is ignored on all other platforms.</para>
 650           </listitem>
 651         </varlistentry>
 652       </variablelist>
 653
 654       <para>
 655       The <literal>ghc-pkg</literal> tool performs expansion of
 656       environment variables occurring in input package specifications.
 657       So, if the <literal>mypkg</literal> was added to the package
 658       database as follows:
 659       </para>
 660 <screen>
 661   $ installdir=/usr/local/lib ghc-pkg -a < mypkg.pkg
 662 </screen>
 663
 664       <para>
 665       The occurrence of <literal>${installdir}</literal> is replaced
 666       with <literal>/usr/local/lib</literal> in the package data that
 667       is added for <literal>mypkg</literal>.
 668       </para>
 669
 670       <para>
 671       This feature enables the distribution of package specification
 672       files that can be easily configured when installing.
 673       </para>
 674
 675       <para>For examples of more package specifications, take a look
 676       at the <literal>package.conf</literal> in your GHC
 677       installation.</para>
 678     </sect2>
 679   </sect1>
 680
 681 <!-- Emacs stuff:
 682      ;;; Local Variables: ***
 683      ;;; mode: sgml ***
 684      ;;; sgml-parent-document: ("using.sgml" "book" "chapter") ***
 685      ;;; End: ***
 686  -->