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/removed from an
  18     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="building-packages">
  54       <title>Building a package from Haskell source</title>
  55       <indexterm><primary>packages</primary>
  56         <secondary>building</secondary></indexterm>
  57
  58       <para>It takes some special considerations to build a new
  59       package:</para>
  60
  61       <itemizedlist>
  62         <listitem>
  63           <para>A package may contain several Haskell modules. A
  64           package may span many directories, or many packages may
  65           exist in a single directory. Packages may not be mutually
  66           recursive.</para>
  67         </listitem>
  68
  69         <listitem>
  70           <para>A package has a name
  71           (e.g. <filename>std</filename>)</para>
  72         </listitem>
  73
  74         <listitem>
  75           <para>The Haskell code in a package may be built into one or
  76           more Unix libraries (e.g. <filename>libHSfoo.a</filename>),
  77           or a single DLL on Windows
  78           (e.g. <filename>HSfoo.dll</filename>).  The restriction to a
  79           single DLL on Windows is that the package system is used to
  80           tell the compiler when it should make an inter-DLL call
  81           rather than an intra-DLL call (inter-DLL calls require an
  82           extra indirection).</para>
  83
  84           <para>Versions of the Haskell libraries for use with GHCi
  85           may also be included: GHCi cannot load <literal>.a</literal>
  86           files directly, instead it will look for an object file
  87           called <filename>HSfoo.o</filename> (the object suffix
  88           varies between platforms, as usual) and load that.  An
  89           object file can be built from a <literal>.a</literal>
  90           archive as follows (using GNU <command>ld</command> on
  91           Unix):</para>
  92
  93 <screen>
  94 ld -r --whole-archive -o HSfoo.o libHSfoo.a
  95 </screen>
  96         </listitem>
  97
  98         <listitem>
  99           <para>GHC does not maintain detailed cross-package
 100           dependency information.  It does remember which modules in
 101           other packages the current module depends on, but not which
 102           things within those imported things.</para>
 103         </listitem>
 104       </itemizedlist>
 105
 106       <para>To compile a module which is to be part of a new package,
 107       use the <literal>-package-name</literal> option:</para>
 108
 109       <variablelist>
 110         <varlistentry>
 111           <term><option>-package-name <replaceable>foo</replaceable></option></term>
 112           <indexterm><primary><literal>-package-name</literal></primary>
 113             <secondary>option</secondary></indexterm>
 114           <listitem>
 115             <para>This option is added to the command line when
 116             compiling a module that is destined to be part of package
 117             <literal>foo</literal>.  If this flag is omitted then the
 118             default package <literal>Main</literal> is assumed.</para>
 119           </listitem>
 120         </varlistentry>
 121       </variablelist>
 122
 123       <para>Failure to use the <literal>-package-name</literal> option
 124       when compiling a package will result in disaster on Windows, but
 125       is relatively harmless on Unix at the moment (it will just cause
 126       a few extra dependencies in some interface files).  However,
 127       bear in mind that we might add support for Unix shared libraries
 128       at some point in the future.</para>
 129
 130       <para>It is worth noting that on Windows, because each package
 131       is built as a DLL, and a reference to a DLL costs an extra
 132       indirection, intra-package references are cheaper than
 133       inter-package references. Of course, this applies to the
 134       <filename>Main</filename> package as well.</para>
 135     </sect2>
 136
 137     <sect2 id="package-management">
 138       <title>Package management</title>
 139       <indexterm><primary>packages</primary>
 140         <secondary>management</secondary></indexterm>
 141
 142       <para>GHC uses a package configuration file, called
 143       <literal>packages.conf</literal>, which can be found in your GHC
 144       install directory.  This file isn't intended to be edited
 145       directly, instead packages can be added or removed using GHC's
 146       package management tool, <literal>ghc-pkg</literal>.</para>
 147
 148       <variablelist>
 149         <varlistentry>
 150           <term><option>--list-packages</option></term>
 151           <term><option>-l</option></term>
 152           <indexterm><primary><option>--list-packages</option></primary></indexterm>
 153           <listitem>
 154             <para>This option displays the list of currently installed
 155             packages.</para>
 156
 157 <screen>
 158   $ ghc-pkg --list-packages
 159   gmp, rts, std, lang, concurrent, data, net, posix, text, util
 160 </screen>
 161
 162             <para>Note that your GHC installation might have a
 163             slightly different set of packages installed.</para>
 164
 165             <para>The <literal>gmp</literal> and
 166             <literal>rts</literal> packages are always present, and
 167             represent the multi-precision integer and runtime system
 168             libraries respectively.  The <literal>std</literal>
 169             package contains the Haskell prelude and standard
 170             libraries.  The rest of the packages are optional
 171             libraries.</para>
 172           </listitem>
 173         </varlistentry>
 174
 175         <varlistentry>
 176           <term><option>--add-package</option></term>
 177           <term><option>-a</option></term>
 178           <indexterm><primary><option>--add-package</option></primary>
 179               </indexterm>
 180           <listitem>
 181             <para>Reads a package specification (see below) on stdin,
 182             and adds it to the database of installed packages.  The
 183             package specification must be a package that isn't already
 184             installed.</para>
 185           </listitem>
 186         </varlistentry>
 187
 188         <varlistentry>
 189           <term><option>--remove-package <replaceable>foo</replaceable></option></term>
 190           <term><option>-r <replaceable>foo</replaceable></option></term>
 191           <indexterm><primary><option>--delete-package</option></primary>
 192               </indexterm>
 193           <listitem>
 194             <para>Removes the specified package from the installed
 195             configuration.</para>
 196           </listitem>
 197         </varlistentry>
 198       </variablelist>
 199
 200       <para>In both cases, the old package configuration file is saved
 201       in <literal>packages.conf.old</literal> in your GHC install
 202       directory, so in an emergency you can always copy this file into
 203       <literal>package.conf</literal> to restore the old
 204       settings.</para>
 205
 206       <para>A package specification looks like this:</para>
 207
 208 <screen>
 209   Package {
 210      name            = "mypkg",
 211      import_dirs     = ["/usr/local/lib/imports/mypkg"],
 212      source_dirs     = [],
 213      library_dirs    = ["/usr/local/lib"],
 214      hs_libraries    = ["HSmypkg" ],
 215      extra_libraries = ["HSmypkg_cbits"],
 216      include_dirs    = [],
 217      c_includes      = ["HsMyPkg.h"],
 218      package_deps    = ["text", "data"],
 219      extra_ghc_opts  = [],
 220      extra_cc_opts   = [],
 221      extra_ld_opts   = ["-lmy_clib"]
 222   }
 223 </screen>
 224
 225       <para>Components of a package specification may be specified in
 226       any order, and are:</para>
 227
 228       <variablelist>
 229         <varlistentry>
 230           <term><literal>name</literal></term>
 231           <indexterm><primary><literal>name</literal></primary>
 232             <secondary>package specification</secondary></indexterm>
 233           <listitem>
 234             <para>The package's name, for use with
 235             the <literal>-package</literal> flag and as listed in the
 236             <literal>--list-packages</literal> list.
 237             </para>
 238           </listitem>
 239         </varlistentry>
 240
 241         <varlistentry>
 242           <term><literal>import_dirs</literal></term>
 243           <indexterm><primary><literal>import_dirs</literal></primary>
 244             <secondary>package specification</secondary></indexterm>
 245           <listitem>
 246             <para>A list of directories containing interface files
 247             (<literal>.hi</literal> files) for this package.</para>
 248           </listitem>
 249         </varlistentry>
 250
 251         <varlistentry>
 252           <term><literal>source_dirs</literal></term>
 253           <indexterm><primary><literal>source_dirs</literal></primary>
 254             <secondary>package specification</secondary></indexterm>
 255           <listitem>
 256             <para>A list of directories containing Haskell source
 257             files for this package.  This field isn't used by GHC, but
 258             could potentially be used by an all-interpreted system
 259             like Hugs.</para>
 260           </listitem>
 261         </varlistentry>
 262
 263         <varlistentry>
 264           <term><literal>library_dirs</literal></term>
 265           <indexterm><primary><literal>library_dirs</literal></primary>
 266             <secondary>package specification</secondary></indexterm>
 267           <listitem>
 268             <para>A list of directories containing libraries for this
 269             package.</para>
 270           </listitem>
 271         </varlistentry>
 272
 273         <varlistentry>
 274           <term><literal>hs_libraries</literal></term>
 275           <indexterm><primary><literal>hs_libraries</literal></primary>
 276             <secondary>package specification</secondary></indexterm>
 277           <listitem>
 278             <para>A list of libraries containing Haskell code for this
 279             package, with the <literal>.a</literal> or
 280             <literal>.dll</literal> suffix omitted.  On Unix, the
 281             <literal>lib</literal> prefix is also omitted.</para>
 282
 283             <para>For use with GHCi, each library should have an
 284             object file too.  The name of the object file does
 285             <emphasis>not</emphasis> have a <literal>lib</literal>
 286             prefix, and has the normal object suffix for your
 287             platform.</para>
 288
 289             <para>For example, if we specify a Haskell library as
 290             <filename>HSfoo</filename> in the package spec, then the
 291             various flavours of library that GHC actually uses will be
 292             called:</para>
 293             <variablelist>
 294               <varlistentry>
 295                 <term><filename>libHSfoo.a</filename></term>
 296                 <listitem>
 297                   <para>The name of the library on Unix
 298                   systems.</para>
 299                 </listitem>
 300               </varlistentry>
 301               <varlistentry>
 302                 <term><filename>HSfoo.dll</filename></term>
 303                 <listitem>
 304                   <para>The name of the dynamic library on Windows
 305                   systems.</para>
 306                 </listitem>
 307               </varlistentry>
 308               <varlistentry>
 309                 <term><filename>HSfoo.o</filename></term>
 310                 <term><filename>HSfoo.obj</filename></term>
 311                 <listitem>
 312                   <para>The object version of the library used by
 313                   GHCi.</para>
 314                 </listitem>
 315               </varlistentry>
 316             </variablelist>
 317
 318           </listitem>
 319         </varlistentry>
 320
 321         <varlistentry>
 322           <term><literal>extra_libraries</literal></term>
 323           <indexterm><primary><literal>extra_libraries</literal></primary>
 324             <secondary>package specification</secondary></indexterm>
 325           <listitem>
 326             <para>A list of extra libraries for this package.  The
 327             difference between <literal>hs_libraries</literal> and
 328             <literal>extra_libraries</literal> is that
 329             <literal>hs_libraries</literal> normally have several
 330             versions, to support profiling, parallel and other build
 331             options.  The various versions are given different
 332             suffixes to distinguish them, for example the profiling
 333             version of the standard prelude library is named
 334             <filename>libHSstd_p.a</filename>, with the
 335             <literal>_p</literal> indicating that this is a profiling
 336             version.  The suffix is added automatically by GHC for
 337             <literal>hs_libraries</literal> only, no suffix is added
 338             for libraries in
 339             <literal>extra_libraries</literal>.</para>
 340
 341             <para>Also, <literal>extra_libraries</literal> are placed
 342             on the linker command line after the
 343             <literal>hs_libraries</literal> for the same package.  If
 344             your package has dependencies in the other direction (i.e.
 345             <literal>extra_libraries</literal> depends on
 346             <literal>hs_libraries</literal>), and the libraries are
 347             static, you might need to make two separate
 348             packages.</para>
 349           </listitem>
 350         </varlistentry>
 351
 352         <varlistentry>
 353           <term><literal>include_dirs</literal></term>
 354           <indexterm><primary><literal>include_dirs</literal></primary>
 355             <secondary>package specification</secondary></indexterm>
 356           <listitem>
 357             <para>A list of directories containing C includes for this
 358             package (maybe the empty list).</para>
 359           </listitem>
 360         </varlistentry>
 361
 362         <varlistentry>
 363           <term><literal>c_includes</literal></term>
 364           <indexterm><primary><literal>c_includes</literal></primary>
 365             <secondary>package specification</secondary></indexterm>
 366           <listitem>
 367             <para>A list of files to include for via-C compilations
 368             using this package.  Typically this include file will
 369             contain function prototypes for any C functions used in
 370             the package, in case they end up being called as a result
 371             of Haskell functions from the package being
 372             inlined.</para>
 373           </listitem>
 374         </varlistentry>
 375
 376         <varlistentry>
 377           <term><literal>package_deps</literal></term>
 378           <indexterm><primary><literal>package_deps</literal></primary>
 379             <secondary>package specification</secondary></indexterm>
 380           <listitem>
 381             <para>A list of packages which this package depends
 382             on.</para>
 383           </listitem>
 384         </varlistentry>
 385
 386         <varlistentry>
 387           <term><literal>extra_ghc_opts</literal></term>
 388           <indexterm><primary><literal>extra_ghc_opts</literal></primary>
 389             <secondary>package specification</secondary></indexterm>
 390           <listitem>
 391             <para>Extra arguments to be added to the GHC command line
 392             when this package is being used.</para>
 393           </listitem>
 394         </varlistentry>
 395
 396         <varlistentry>
 397           <term><literal>extra_cc_opts</literal></term>
 398           <indexterm><primary><literal>extra_cc_opts</literal></primary>
 399             <secondary>package specification</secondary></indexterm>
 400           <listitem>
 401             <para>Extra arguments to be added to the gcc command line
 402             when this package is being used (only for via-C
 403             compilations).</para>
 404           </listitem>
 405         </varlistentry>
 406
 407         <varlistentry>
 408           <term><literal>extra_ld_opts</literal></term>
 409           <indexterm><primary><literal>extra_ld_opts</literal></primary>
 410             <secondary>package specification</secondary></indexterm>
 411           <listitem>
 412             <para>Extra arguments to be added to the gcc command line
 413             (for linking) when this package is being used.</para>
 414           </listitem>
 415         </varlistentry>
 416       </variablelist>
 417
 418       <para>For examples of more package specifications, take a look
 419       at the <literal>package.conf</literal> in your GHC
 420       installation.</para>
 421     </sect2>
 422   </sect1>
 423
 424 <!-- Emacs stuff:
 425      ;;; Local Variables: ***
 426      ;;; mode: sgml ***
 427      ;;; sgml-parent-document: ("using.sgml" "book" "chapter") ***
 428      ;;; End: ***
 429  -->