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