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 the accompanying
  17     library documentation), 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 id="using-local-packages">
  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>base</filename>)</para>
 105         </listitem>
 106
 107         <listitem>
 108           <para>The Haskell code in a package may be built into one or
 109           more archive libraries
 110           (e.g. <filename>libHSfoo.a</filename>), or a single DLL on
 111           Windows (e.g. <filename>HSfoo.dll</filename>).  The
 112           restriction to a single DLL on Windows is because the
 113           package system is used to tell the compiler when it should
 114           make an inter-DLL call rather than an intra-DLL call
 115           (inter-DLL calls require an extra
 116           indirection). <emphasis>Building packages as DLLs doesn't
 117           work at the moment; see <XRef LinkEnd="win32-dlls-create">
 118           for the gory details.</emphasis>
 119           </para>
 120
 121           <para>Building a static library is done by using the
 122           <literal>ar</literal> tool, like so:</para>
 123
 124 <screen>ar cqs libHSfoo.a A.o B.o C.o ...</screen>
 125
 126           <para>where <filename>A.o</filename>,
 127           <filename>B.o</filename> and so on are the compiled Haskell
 128           modules, and <filename>libHSfoo.a</filename> is the library
 129           you wish to create.  The syntax may differ slightly on your
 130           system, so check the documentation if you run into
 131           difficulties.</para>
 132
 133           <para>Versions of the Haskell libraries for use with GHCi
 134           may also be included: GHCi cannot load <literal>.a</literal>
 135           files directly, instead it will look for an object file
 136           called <filename>HSfoo.o</filename> and load that.  On some
 137           systems, the <literal>ghc-pkg</literal> tool can
 138           automatically build the GHCi version of each library, see
 139           <xref linkend="package-management">.  To build these
 140           libraries by hand from the <literal>.a</literal> archive, it
 141           is possible to use GNU <command>ld</command> as
 142           follows:</para>
 143
 144 <screen>ld -r &ndash;&ndash;whole-archive -o HSfoo.o libHSfoo.a</screen>
 145         </listitem>
 146
 147         <listitem>
 148           <para>GHC does not maintain detailed cross-package
 149           dependency information.  It does remember which modules in
 150           other packages the current module depends on, but not which
 151           things within those imported things.</para>
 152         </listitem>
 153       </itemizedlist>
 154
 155       <para>To compile a module which is to be part of a new package,
 156       use the <literal>-package-name</literal> option:</para>
 157
 158       <variablelist>
 159         <varlistentry>
 160           <term><option>-package-name <replaceable>foo</replaceable></option></term>
 161           <indexterm><primary><literal>-package-name</literal></primary>
 162             <secondary>option</secondary></indexterm>
 163           <listitem>
 164             <para>This option is added to the command line when
 165             compiling a module that is destined to be part of package
 166             <literal>foo</literal>.  If this flag is omitted then the
 167             default package <literal>Main</literal> is assumed.</para>
 168           </listitem>
 169         </varlistentry>
 170       </variablelist>
 171
 172       <para>Failure to use the <literal>-package-name</literal> option
 173       when compiling a package will result in disaster on Windows, but
 174       is relatively harmless on Unix at the moment (it will just cause
 175       a few extra dependencies in some interface files).  However,
 176       bear in mind that we might add support for Unix shared libraries
 177       at some point in the future.</para>
 178
 179       <para>It is worth noting that on Windows, when each package
 180       is built as a DLL, since a reference to a DLL costs an extra
 181       indirection, intra-package references are cheaper than
 182       inter-package references. Of course, this applies to the
 183       <filename>Main</filename> package as well.</para>
 184     </sect2>
 185
 186     <sect2 id="package-management">
 187       <title>Package management</title>
 188       <indexterm><primary>packages</primary>
 189         <secondary>management</secondary></indexterm>
 190
 191       <para>The <literal>ghc-pkg</literal> tool allows packages to be
 192       added or removed from a package configuration file.  By default,
 193       the system-wide configuration file is used, but alternatively
 194       packages can be added, updated or removed from a user-specified
 195       configuration file using the <option>&ndash;&ndash;config-file</option>
 196       option.  An empty package configuration file consists of the
 197       string <quote><literal>[]</literal></quote>.</para>
 198
 199       <para>The <literal>ghc-pkg</literal> program accepts the
 200       following options:</para>
 201
 202       <variablelist>
 203         <varlistentry>
 204           <term><option>&ndash;&ndash;add-package</option></term>
 205           <term><option>-a</option></term>
 206           <indexterm><primary><option>&ndash;&ndash;add-package</option></primary></indexterm>
 207           <listitem>
 208             <para>Reads package specification from the input (see below),
 209             and adds it to the database of installed packages.  The
 210             package specification must be a package that isn't already
 211             installed.</para>
 212           </listitem>
 213         </varlistentry>
 214
 215         <varlistentry>
 216           <term><option>&ndash;&ndash;input-file=<replaceable>file</replaceable></option></term>
 217           <term><option>-i <replaceable>file</replaceable></option></term>
 218           <indexterm><primary><option>&ndash;&ndash;input-file</option></primary></indexterm>
 219           <listitem>
 220             <para>Read new package specifications from file
 221             <replaceable>file</replaceable>. If a value of
 222             <filename>"-"</filename> is given, standard input is used.
 223             If no <option>-i</option> is present on the command-line,
 224             an input file of <filename>"-"</filename> is assumed.
 225             </para>
 226           </listitem>
 227         </varlistentry>
 228
 229         <varlistentry>
 230           <term><option>&ndash;&ndash;auto-ghci-libs</option></term>
 231           <term><option>-g</option></term>
 232           <indexterm><primary><option>&ndash;&ndash;auto-ghci-libs</option></primary>
 233               </indexterm>
 234           <listitem>
 235             <para>Automatically generate the GHCi
 236             <filename>.o</filename> version of each
 237             <filename>.a</filename> Haskell library, using GNU ld (if
 238             that is available).  Without this option,
 239             <literal>ghc-pkg</literal> will warn if GHCi versions of
 240             any Haskell libraries in the package don't exist.</para>
 241
 242             <para>GHCi <literal>.o</literal> libraries don't
 243             necessarily have to live in the same directory as the
 244             corresponding <literal>.a</literal> library.  However,
 245             this option will cause the GHCi library to be created in
 246             the same directory as the <literal>.a</literal>
 247             library.</para>
 248           </listitem>
 249         </varlistentry>
 250
 251         <varlistentry>
 252           <term><option>&ndash;&ndash;config-file <replaceable>file</replaceable></option></term>
 253           <term><option>-f <replaceable>file</replaceable></option></term>
 254           <indexterm><primary><option>&ndash;&ndash;config-file</option></primary>
 255               </indexterm>
 256           <listitem>
 257             <para>Use <replaceable>file</replaceable> instead of the
 258             default package configuration file.  This, in conjunction
 259             with GHC's <option>-package-conf</option> option, allows
 260             a user to have a local set of packages in addition to the
 261             system-wide installed set.</para>
 262           </listitem>
 263         </varlistentry>
 264
 265         <varlistentry>
 266           <term><option>&ndash;&ndash;list-packages</option></term>
 267           <term><option>-l</option></term>
 268           <indexterm><primary><option>&ndash;&ndash;list-packages</option></primary></indexterm>
 269           <listitem>
 270             <para>This option displays the list of currently installed
 271             packages.</para>
 272
 273 <screen>
 274   $ ghc-pkg &ndash;&ndash;list-packages
 275   gmp, rts, std, lang, concurrent, data, net, posix, text, util
 276 </screen>
 277
 278             <para>Note that your GHC installation might have a
 279             slightly different set of packages installed.</para>
 280
 281             <para>The <literal>gmp</literal> and
 282             <literal>rts</literal> packages are always present, and
 283             represent the multi-precision integer and runtime system
 284             libraries respectively.  The <literal>std</literal>
 285             package contains the Haskell prelude and standard
 286             libraries.  The rest of the packages are optional
 287             libraries.</para>
 288           </listitem>
 289         </varlistentry>
 290
 291         <varlistentry>
 292           <term><option>&ndash;&ndash;remove-package <replaceable>foo</replaceable></option></term>
 293           <term><option>-r <replaceable>foo</replaceable></option></term>
 294           <indexterm><primary><option>&ndash;&ndash;delete-package</option></primary>
 295               </indexterm>
 296           <listitem>
 297             <para>Removes the specified package from the installed
 298             configuration.</para>
 299           </listitem>
 300         </varlistentry>
 301         <varlistentry>
 302           <term><option>&ndash;&ndash;update-package</option></term>
 303           <term><option>-u</option></term>
 304           <indexterm><primary><option>&ndash;&ndash;update-package</option></primary></indexterm>
 305           <listitem>
 306             <para>Reads package specification from the input, and
 307             adds it to the database of installed packages. If a package
 308             with the same name is already installed, its configuration
 309             data is replaced with the new information. If the package
 310             doesn't already exist, it's added.
 311             </para>
 312           </listitem>
 313         </varlistentry>
 314         <varlistentry>
 315           <term><option>&ndash;&ndash;force</option></term>
 316           <indexterm><primary><option>&ndash;&ndash;force</option></primary></indexterm>
 317           <listitem>
 318             <para>Causes <literal>ghc-pkg</literal> to ignore missing
 319             directories and libraries when adding a package, and just
 320             go ahead and add it anyway.  This might be useful if your
 321             package installation system needs to add the package to
 322             GHC before building and installing the files.</para>
 323           </listitem>
 324         </varlistentry>
 325       </variablelist>
 326
 327       <para>When modifying the configuration file
 328       <replaceable>file</replaceable>, a copy of the original file is
 329       saved in <replaceable>file</replaceable><literal>.old</literal>,
 330       so in an emergency you can always restore the old settings by
 331       copying the old file back again.</para>
 332
 333       <para>A package specification looks like this:</para>
 334
 335 <screen>
 336   Package {
 337      name            = "mypkg",
 338      import_dirs     = ["${installdir}/imports/mypkg"],
 339      source_dirs     = [],
 340      library_dirs    = ["${installdir}"],
 341      hs_libraries    = ["HSmypkg" ],
 342      extra_libraries = ["HSmypkg_cbits"],
 343      include_dirs    = [],
 344      c_includes      = ["HsMyPkg.h"],
 345      package_deps    = ["text", "data"],
 346      extra_ghc_opts  = [],
 347      extra_cc_opts   = [],
 348      extra_ld_opts   = ["-lmy_clib"]
 349   }
 350 </screen>
 351
 352       <para>Components of a package specification may be specified in
 353       any order, and are:</para>
 354
 355       <variablelist>
 356         <varlistentry>
 357           <term><literal>name</literal></term>
 358           <indexterm><primary><literal>name</literal></primary>
 359             <secondary>package specification</secondary></indexterm>
 360           <listitem>
 361             <para>The package's name, for use with
 362             the <literal>-package</literal> flag and as listed in the
 363             <literal>&ndash;&ndash;list-packages</literal> list.
 364             </para>
 365           </listitem>
 366         </varlistentry>
 367
 368         <varlistentry>
 369           <term><literal>import_dirs</literal></term>
 370           <indexterm><primary><literal>import_dirs</literal></primary>
 371             <secondary>package specification</secondary></indexterm>
 372           <listitem>
 373             <para>A list of directories containing interface files
 374             (<literal>.hi</literal> files) for this package.</para>
 375
 376             <para>If the package contains profiling libraries, then
 377             the interface files for those library modules should have
 378             the suffix <literal>.p_hi</literal>.  So the package can
 379             contain both normal and profiling versions of the same
 380             library without conflict (see also
 381             <literal>library_dirs</literal> below).</para>
 382           </listitem>
 383         </varlistentry>
 384
 385         <varlistentry>
 386           <term><literal>source_dirs</literal></term>
 387           <indexterm><primary><literal>source_dirs</literal></primary>
 388             <secondary>package specification</secondary></indexterm>
 389           <listitem>
 390             <para>A list of directories containing Haskell source
 391             files for this package.  This field isn't used by GHC, but
 392             could potentially be used by an all-interpreted system
 393             like Hugs.</para>
 394           </listitem>
 395         </varlistentry>
 396
 397         <varlistentry>
 398           <term><literal>library_dirs</literal></term>
 399           <indexterm><primary><literal>library_dirs</literal></primary>
 400             <secondary>package specification</secondary></indexterm>
 401           <listitem>
 402             <para>A list of directories containing libraries for this
 403             package.</para>
 404           </listitem>
 405         </varlistentry>
 406
 407         <varlistentry>
 408           <term><literal>hs_libraries</literal></term>
 409           <indexterm><primary><literal>hs_libraries</literal></primary>
 410             <secondary>package specification</secondary></indexterm>
 411           <listitem>
 412             <para>A list of libraries containing Haskell code for this
 413             package, with the <literal>.a</literal> or
 414             <literal>.dll</literal> suffix omitted.  When packages are
 415             built as libraries, the
 416             <literal>lib</literal> prefix is also omitted.</para>
 417
 418             <para>For use with GHCi, each library should have an
 419             object file too.  The name of the object file does
 420             <emphasis>not</emphasis> have a <literal>lib</literal>
 421             prefix, and has the normal object suffix for your
 422             platform.</para>
 423
 424             <para>For example, if we specify a Haskell library as
 425             <filename>HSfoo</filename> in the package spec, then the
 426             various flavours of library that GHC actually uses will be
 427             called:</para>
 428             <variablelist>
 429               <varlistentry>
 430                 <term><filename>libHSfoo.a</filename></term>
 431                 <listitem>
 432                   <para>The name of the library on Unix and Windows
 433                   (mingw) systems.  Note that we don't support
 434                   building dynamic libraries of Haskell code on Unix
 435                   systems.</para>
 436                 </listitem>
 437               </varlistentry>
 438               <varlistentry>
 439                 <term><filename>HSfoo.dll</filename></term>
 440                 <listitem>
 441                   <para>The name of the dynamic library on Windows
 442                   systems (optional).</para>
 443                 </listitem>
 444               </varlistentry>
 445               <varlistentry>
 446                 <term><filename>HSfoo.o</filename></term>
 447                 <term><filename>HSfoo.obj</filename></term>
 448                 <listitem>
 449                   <para>The object version of the library used by
 450                   GHCi.</para>
 451                 </listitem>
 452               </varlistentry>
 453             </variablelist>
 454
 455           </listitem>
 456         </varlistentry>
 457
 458         <varlistentry>
 459           <term><literal>extra_libraries</literal></term>
 460           <indexterm><primary><literal>extra_libraries</literal></primary>
 461             <secondary>package specification</secondary></indexterm>
 462           <listitem>
 463             <para>A list of extra libraries for this package.  The
 464             difference between <literal>hs_libraries</literal> and
 465             <literal>extra_libraries</literal> is that
 466             <literal>hs_libraries</literal> normally have several
 467             versions, to support profiling, parallel and other build
 468             options.  The various versions are given different
 469             suffixes to distinguish them, for example the profiling
 470             version of the standard prelude library is named
 471             <filename>libHSstd_p.a</filename>, with the
 472             <literal>_p</literal> indicating that this is a profiling
 473             version.  The suffix is added automatically by GHC for
 474             <literal>hs_libraries</literal> only, no suffix is added
 475             for libraries in
 476             <literal>extra_libraries</literal>.</para>
 477
 478             <para>The libraries listed in
 479             <literal>extra_libraries</literal> may be any libraries
 480             supported by your system's linker, including dynamic
 481             libraries (<literal>.so</literal> on Unix,
 482             <literal>.DLL</literal> on Windows).</para>
 483
 484             <para>Also, <literal>extra_libraries</literal> are placed
 485             on the linker command line after the
 486             <literal>hs_libraries</literal> for the same package.  If
 487             your package has dependencies in the other direction (i.e.
 488             <literal>extra_libraries</literal> depends on
 489             <literal>hs_libraries</literal>), and the libraries are
 490             static, you might need to make two separate
 491             packages.</para>
 492           </listitem>
 493         </varlistentry>
 494
 495         <varlistentry>
 496           <term><literal>include_dirs</literal></term>
 497           <indexterm><primary><literal>include_dirs</literal></primary>
 498             <secondary>package specification</secondary></indexterm>
 499           <listitem>
 500             <para>A list of directories containing C includes for this
 501             package (maybe the empty list).</para>
 502           </listitem>
 503         </varlistentry>
 504
 505         <varlistentry>
 506           <term><literal>c_includes</literal></term>
 507           <indexterm><primary><literal>c_includes</literal></primary>
 508             <secondary>package specification</secondary></indexterm>
 509           <listitem>
 510             <para>A list of files to include for via-C compilations
 511             using this package.  Typically this include file will
 512             contain function prototypes for any C functions used in
 513             the package, in case they end up being called as a result
 514             of Haskell functions from the package being
 515             inlined.</para>
 516           </listitem>
 517         </varlistentry>
 518
 519         <varlistentry>
 520           <term><literal>package_deps</literal></term>
 521           <indexterm><primary><literal>package_deps</literal></primary>
 522             <secondary>package specification</secondary></indexterm>
 523           <listitem>
 524             <para>A list of packages which this package depends
 525             on.</para>
 526           </listitem>
 527         </varlistentry>
 528
 529         <varlistentry>
 530           <term><literal>extra_ghc_opts</literal></term>
 531           <indexterm><primary><literal>extra_ghc_opts</literal></primary>
 532             <secondary>package specification</secondary></indexterm>
 533           <listitem>
 534             <para>Extra arguments to be added to the GHC command line
 535             when this package is being used.</para>
 536           </listitem>
 537         </varlistentry>
 538
 539         <varlistentry>
 540           <term><literal>extra_cc_opts</literal></term>
 541           <indexterm><primary><literal>extra_cc_opts</literal></primary>
 542             <secondary>package specification</secondary></indexterm>
 543           <listitem>
 544             <para>Extra arguments to be added to the gcc command line
 545             when this package is being used (only for via-C
 546             compilations).</para>
 547           </listitem>
 548         </varlistentry>
 549
 550         <varlistentry>
 551           <term><literal>extra_ld_opts</literal></term>
 552           <indexterm><primary><literal>extra_ld_opts</literal></primary>
 553             <secondary>package specification</secondary></indexterm>
 554           <listitem>
 555             <para>Extra arguments to be added to the gcc command line
 556             (for linking) when this package is being used.</para>
 557           </listitem>
 558         </varlistentry>
 559
 560         <varlistentry>
 561           <term><literal>framework_dirs</literal></term>
 562           <indexterm><primary><literal>framework_dirs</literal></primary>
 563             <secondary>package specification</secondary></indexterm>
 564           <listitem>
 565             <para>On Darwin/MacOS X, a list of directories containing frameworks for this
 566             package. This corresponds to the <option>-framework-path</option> option.
 567             It is ignored on all other platforms.</para>
 568           </listitem>
 569         </varlistentry>
 570
 571         <varlistentry>
 572           <term><literal>extra_frameworks</literal></term>
 573           <indexterm><primary><literal>extra_frameworks</literal></primary>
 574             <secondary>package specification</secondary></indexterm>
 575           <listitem>
 576             <para>On Darwin/MacOS X, a list of frameworks to link to. This corresponds to the
 577             <option>-framework</option> option. Take a look at Apple's developer documentation
 578             to find out what frameworks actually are. This entry is ignored on all other platforms.</para>
 579           </listitem>
 580         </varlistentry>
 581       </variablelist>
 582
 583       <para>
 584       The <literal>ghc-pkg</literal> tool performs expansion of
 585       environment variables occurring in input package specifications.
 586       So, if the <literal>mypkg</literal> was added to the package
 587       database as follows:
 588       </para>
 589 <screen>
 590   $ installdir=/usr/local/lib ghc-pkg -a < mypkg.pkg
 591 </screen>
 592
 593       <para>
 594       The occurrence of <literal>${installdir}</literal> is replaced
 595       with <literal>/usr/local/lib</literal> in the package data that
 596       is added for <literal>mypkg</literal>.
 597       </para>
 598
 599       <para>
 600       This feature enables the distribution of package specification
 601       files that can be easily configured when installing.
 602       </para>
 603
 604       <para>For examples of more package specifications, take a look
 605       at the <literal>package.conf</literal> in your GHC
 606       installation.</para>
 607     </sect2>
 608   </sect1>
 609
 610 <!-- Emacs stuff:
 611      ;;; Local Variables: ***
 612      ;;; mode: sgml ***
 613      ;;; sgml-parent-document: ("using.sgml" "book" "chapter") ***
 614      ;;; End: ***
 615  -->