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