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>
  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 Unix 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> (the object suffix
 124           varies between platforms, as usual) and load that.  An
 125           object file can be built from a <literal>.a</literal>
 126           archive as follows (using GNU <command>ld</command> on
 127           Unix):</para>
 128
 129 <screen>
 130 ld -r --whole-archive -o HSfoo.o libHSfoo.a
 131 </screen>
 132         </listitem>
 133
 134         <listitem>
 135           <para>GHC does not maintain detailed cross-package
 136           dependency information.  It does remember which modules in
 137           other packages the current module depends on, but not which
 138           things within those imported things.</para>
 139         </listitem>
 140       </itemizedlist>
 141
 142       <para>To compile a module which is to be part of a new package,
 143       use the <literal>-package-name</literal> option:</para>
 144
 145       <variablelist>
 146         <varlistentry>
 147           <term><option>-package-name <replaceable>foo</replaceable></option></term>
 148           <indexterm><primary><literal>-package-name</literal></primary>
 149             <secondary>option</secondary></indexterm>
 150           <listitem>
 151             <para>This option is added to the command line when
 152             compiling a module that is destined to be part of package
 153             <literal>foo</literal>.  If this flag is omitted then the
 154             default package <literal>Main</literal> is assumed.</para>
 155           </listitem>
 156         </varlistentry>
 157       </variablelist>
 158
 159       <para>Failure to use the <literal>-package-name</literal> option
 160       when compiling a package will result in disaster on Windows, but
 161       is relatively harmless on Unix at the moment (it will just cause
 162       a few extra dependencies in some interface files).  However,
 163       bear in mind that we might add support for Unix shared libraries
 164       at some point in the future.</para>
 165
 166       <para>It is worth noting that on Windows, when each package
 167       is built as a DLL, since a reference to a DLL costs an extra
 168       indirection, intra-package references are cheaper than
 169       inter-package references. Of course, this applies to the
 170       <filename>Main</filename> package as well.</para>
 171     </sect2>
 172
 173     <sect2 id="package-management">
 174       <title>Package management</title>
 175       <indexterm><primary>packages</primary>
 176         <secondary>management</secondary></indexterm>
 177
 178       <para>The <literal>ghc-pkg</literal> tool allows packages to be
 179       added or removed from a package configuration file.  By default,
 180       the system-wide configuration file is used, but alternatively
 181       packages can be added or removed from a user-specified
 182       configuration file using the <option>--config-file</option>
 183       option.  An empty package configuration file consists of the
 184       string <quote><literal>[]</literal></quote>.</para>
 185
 186       <para>The <literal>ghc-pkg</literal> program accepts the
 187       following options:</para>
 188
 189       <variablelist>
 190         <varlistentry>
 191           <term><option>--add-package</option></term>
 192           <term><option>-a</option></term>
 193           <indexterm><primary><option>--add-package</option></primary>
 194               </indexterm>
 195           <listitem>
 196             <para>Reads a package specification (see below) on stdin,
 197             and adds it to the database of installed packages.  The
 198             package specification must be a package that isn't already
 199             installed.</para>
 200           </listitem>
 201         </varlistentry>
 202
 203         <varlistentry>
 204           <term><option>--config-file <replaceable>file</replaceable></option></term>
 205           <term><option>-f <replaceable>file</replaceable></option></term>
 206           <indexterm><primary><option>--config-file</option></primary>
 207               </indexterm>
 208           <listitem>
 209             <para>Use <replaceable>file</replaceable> instead of the
 210             default package configuration file.  This, in conjunction
 211             with GHC's <option>-package-conf</option> option, allows
 212             a user to have a local set of packages in addition to the
 213             system-wide installed set.</para>
 214           </listitem>
 215         </varlistentry>
 216
 217         <varlistentry>
 218           <term><option>--list-packages</option></term>
 219           <term><option>-l</option></term>
 220           <indexterm><primary><option>--list-packages</option></primary></indexterm>
 221           <listitem>
 222             <para>This option displays the list of currently installed
 223             packages.</para>
 224
 225 <screen>
 226   $ ghc-pkg --list-packages
 227   gmp, rts, std, lang, concurrent, data, net, posix, text, util
 228 </screen>
 229
 230             <para>Note that your GHC installation might have a
 231             slightly different set of packages installed.</para>
 232
 233             <para>The <literal>gmp</literal> and
 234             <literal>rts</literal> packages are always present, and
 235             represent the multi-precision integer and runtime system
 236             libraries respectively.  The <literal>std</literal>
 237             package contains the Haskell prelude and standard
 238             libraries.  The rest of the packages are optional
 239             libraries.</para>
 240           </listitem>
 241         </varlistentry>
 242
 243         <varlistentry>
 244           <term><option>--remove-package <replaceable>foo</replaceable></option></term>
 245           <term><option>-r <replaceable>foo</replaceable></option></term>
 246           <indexterm><primary><option>--delete-package</option></primary>
 247               </indexterm>
 248           <listitem>
 249             <para>Removes the specified package from the installed
 250             configuration.</para>
 251           </listitem>
 252         </varlistentry>
 253       </variablelist>
 254
 255       <para>When modifying the configuration file
 256       <replaceable>file</replaceable>, a copy of the original file is
 257       saved in <replaceable>file</replaceable><literal>.old</literal>,
 258       so in an emergency you can always restore the old settings by
 259       copying the old file back again.</para>
 260
 261       <para>A package specification looks like this:</para>
 262
 263 <screen>
 264   Package {
 265      name            = "mypkg",
 266      import_dirs     = ["/usr/local/lib/imports/mypkg"],
 267      source_dirs     = [],
 268      library_dirs    = ["/usr/local/lib"],
 269      hs_libraries    = ["HSmypkg" ],
 270      extra_libraries = ["HSmypkg_cbits"],
 271      include_dirs    = [],
 272      c_includes      = ["HsMyPkg.h"],
 273      package_deps    = ["text", "data"],
 274      extra_ghc_opts  = [],
 275      extra_cc_opts   = [],
 276      extra_ld_opts   = ["-lmy_clib"]
 277   }
 278 </screen>
 279
 280       <para>Components of a package specification may be specified in
 281       any order, and are:</para>
 282
 283       <variablelist>
 284         <varlistentry>
 285           <term><literal>name</literal></term>
 286           <indexterm><primary><literal>name</literal></primary>
 287             <secondary>package specification</secondary></indexterm>
 288           <listitem>
 289             <para>The package's name, for use with
 290             the <literal>-package</literal> flag and as listed in the
 291             <literal>--list-packages</literal> list.
 292             </para>
 293           </listitem>
 294         </varlistentry>
 295
 296         <varlistentry>
 297           <term><literal>import_dirs</literal></term>
 298           <indexterm><primary><literal>import_dirs</literal></primary>
 299             <secondary>package specification</secondary></indexterm>
 300           <listitem>
 301             <para>A list of directories containing interface files
 302             (<literal>.hi</literal> files) for this package.</para>
 303           </listitem>
 304         </varlistentry>
 305
 306         <varlistentry>
 307           <term><literal>source_dirs</literal></term>
 308           <indexterm><primary><literal>source_dirs</literal></primary>
 309             <secondary>package specification</secondary></indexterm>
 310           <listitem>
 311             <para>A list of directories containing Haskell source
 312             files for this package.  This field isn't used by GHC, but
 313             could potentially be used by an all-interpreted system
 314             like Hugs.</para>
 315           </listitem>
 316         </varlistentry>
 317
 318         <varlistentry>
 319           <term><literal>library_dirs</literal></term>
 320           <indexterm><primary><literal>library_dirs</literal></primary>
 321             <secondary>package specification</secondary></indexterm>
 322           <listitem>
 323             <para>A list of directories containing libraries for this
 324             package.</para>
 325           </listitem>
 326         </varlistentry>
 327
 328         <varlistentry>
 329           <term><literal>hs_libraries</literal></term>
 330           <indexterm><primary><literal>hs_libraries</literal></primary>
 331             <secondary>package specification</secondary></indexterm>
 332           <listitem>
 333             <para>A list of libraries containing Haskell code for this
 334             package, with the <literal>.a</literal> or
 335             <literal>.dll</literal> suffix omitted.  When packages are
 336             built as libraries, the
 337             <literal>lib</literal> prefix is also omitted.</para>
 338
 339             <para>For use with GHCi, each library should have an
 340             object file too.  The name of the object file does
 341             <emphasis>not</emphasis> have a <literal>lib</literal>
 342             prefix, and has the normal object suffix for your
 343             platform.</para>
 344
 345             <para>For example, if we specify a Haskell library as
 346             <filename>HSfoo</filename> in the package spec, then the
 347             various flavours of library that GHC actually uses will be
 348             called:</para>
 349             <variablelist>
 350               <varlistentry>
 351                 <term><filename>libHSfoo.a</filename></term>
 352                 <listitem>
 353                   <para>The name of the library on Unix
 354                   systems.</para>
 355                 </listitem>
 356               </varlistentry>
 357               <varlistentry>
 358                 <term><filename>HSfoo.dll</filename></term>
 359                 <listitem>
 360                   <para>The name of the dynamic library on Windows
 361                   systems.</para>
 362                 </listitem>
 363               </varlistentry>
 364               <varlistentry>
 365                 <term><filename>HSfoo.o</filename></term>
 366                 <term><filename>HSfoo.obj</filename></term>
 367                 <listitem>
 368                   <para>The object version of the library used by
 369                   GHCi.</para>
 370                 </listitem>
 371               </varlistentry>
 372             </variablelist>
 373
 374           </listitem>
 375         </varlistentry>
 376
 377         <varlistentry>
 378           <term><literal>extra_libraries</literal></term>
 379           <indexterm><primary><literal>extra_libraries</literal></primary>
 380             <secondary>package specification</secondary></indexterm>
 381           <listitem>
 382             <para>A list of extra libraries for this package.  The
 383             difference between <literal>hs_libraries</literal> and
 384             <literal>extra_libraries</literal> is that
 385             <literal>hs_libraries</literal> normally have several
 386             versions, to support profiling, parallel and other build
 387             options.  The various versions are given different
 388             suffixes to distinguish them, for example the profiling
 389             version of the standard prelude library is named
 390             <filename>libHSstd_p.a</filename>, with the
 391             <literal>_p</literal> indicating that this is a profiling
 392             version.  The suffix is added automatically by GHC for
 393             <literal>hs_libraries</literal> only, no suffix is added
 394             for libraries in
 395             <literal>extra_libraries</literal>.</para>
 396
 397             <para>Also, <literal>extra_libraries</literal> are placed
 398             on the linker command line after the
 399             <literal>hs_libraries</literal> for the same package.  If
 400             your package has dependencies in the other direction (i.e.
 401             <literal>extra_libraries</literal> depends on
 402             <literal>hs_libraries</literal>), and the libraries are
 403             static, you might need to make two separate
 404             packages.</para>
 405           </listitem>
 406         </varlistentry>
 407
 408         <varlistentry>
 409           <term><literal>include_dirs</literal></term>
 410           <indexterm><primary><literal>include_dirs</literal></primary>
 411             <secondary>package specification</secondary></indexterm>
 412           <listitem>
 413             <para>A list of directories containing C includes for this
 414             package (maybe the empty list).</para>
 415           </listitem>
 416         </varlistentry>
 417
 418         <varlistentry>
 419           <term><literal>c_includes</literal></term>
 420           <indexterm><primary><literal>c_includes</literal></primary>
 421             <secondary>package specification</secondary></indexterm>
 422           <listitem>
 423             <para>A list of files to include for via-C compilations
 424             using this package.  Typically this include file will
 425             contain function prototypes for any C functions used in
 426             the package, in case they end up being called as a result
 427             of Haskell functions from the package being
 428             inlined.</para>
 429           </listitem>
 430         </varlistentry>
 431
 432         <varlistentry>
 433           <term><literal>package_deps</literal></term>
 434           <indexterm><primary><literal>package_deps</literal></primary>
 435             <secondary>package specification</secondary></indexterm>
 436           <listitem>
 437             <para>A list of packages which this package depends
 438             on.</para>
 439           </listitem>
 440         </varlistentry>
 441
 442         <varlistentry>
 443           <term><literal>extra_ghc_opts</literal></term>
 444           <indexterm><primary><literal>extra_ghc_opts</literal></primary>
 445             <secondary>package specification</secondary></indexterm>
 446           <listitem>
 447             <para>Extra arguments to be added to the GHC command line
 448             when this package is being used.</para>
 449           </listitem>
 450         </varlistentry>
 451
 452         <varlistentry>
 453           <term><literal>extra_cc_opts</literal></term>
 454           <indexterm><primary><literal>extra_cc_opts</literal></primary>
 455             <secondary>package specification</secondary></indexterm>
 456           <listitem>
 457             <para>Extra arguments to be added to the gcc command line
 458             when this package is being used (only for via-C
 459             compilations).</para>
 460           </listitem>
 461         </varlistentry>
 462
 463         <varlistentry>
 464           <term><literal>extra_ld_opts</literal></term>
 465           <indexterm><primary><literal>extra_ld_opts</literal></primary>
 466             <secondary>package specification</secondary></indexterm>
 467           <listitem>
 468             <para>Extra arguments to be added to the gcc command line
 469             (for linking) when this package is being used.</para>
 470           </listitem>
 471         </varlistentry>
 472       </variablelist>
 473
 474       <para>For examples of more package specifications, take a look
 475       at the <literal>package.conf</literal> in your GHC
 476       installation.</para>
 477     </sect2>
 478   </sect1>
 479
 480 <!-- Emacs stuff:
 481      ;;; Local Variables: ***
 482      ;;; mode: sgml ***
 483      ;;; sgml-parent-document: ("using.sgml" "book" "chapter") ***
 484      ;;; End: ***
 485  -->