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