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