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