1 <?xml version="1.0" encoding="iso-8859-1"?>
3 <title>Packages</title>
4 <indexterm><primary>packages</primary></indexterm>
6 <para>Packages are collections of libraries, conveniently grouped
7 together as a single entity. The package system is flexible: a
8 package may consist of Haskell code, foreign language code (eg. C
9 libraries), or a mixture of the two. A package is a good way to
10 group together related Haskell modules, and is essential if you
11 intend to make the modules into a Windows DLL (see below).</para>
13 <para>Because packages can contain both Haskell and C libraries, they
14 are also a good way to provide convenient access to a Haskell
15 layer over a C library.</para>
17 <para>GHC comes with several packages (see the accompanying
18 library documentation), and packages can be added to or removed
19 from an existing GHC installation, using the supplied
20 <literal>ghc-pkg</literal><indexterm><primary><literal>ghc-pkg</literal></primary>
21 </indexterm> tool, described in <xref
22 linkend="package-management"/>.</para>
24 <sect2 id="using-packages">
25 <title>Using a package</title>
26 <indexterm><primary>packages</primary>
27 <secondary>using</secondary></indexterm>
29 <para>Some packages, called <emphasis>auto packages</emphasis>,
30 are automatically available: you don't need
31 to specify any extra flags to use them (except in certain
32 circumstances; see below). All the packages which contain
33 hierarchical libraries fall into this category.</para>
35 <para>Some other packages are <emphasis>not</emphasis>
36 automatically available: those are normally the packages
37 containing old non-hierarchical libraries. To gain access to a
38 non-auto package, use the <option>-package</option> command-line
44 <option>-package <replaceable>lib</replaceable></option>
45 <indexterm><primary>-package <replaceable>lib</replaceable> option</primary></indexterm>
48 <para>This option brings into scope all the modules from
49 package <literal><replaceable>lib</replaceable></literal> (they still have to
50 be imported in your Haskell source, however). It also
51 causes the relevant libraries to be linked when linking is
53 <para>Some packages depend on other packages, for example the
54 <literal>text</literal> package makes use of some of the modules
55 in the <literal>lang</literal> package. The package system
56 takes care of all these dependencies, so that when you say
57 <literal>-package text</literal> on the command line, you
58 automatically get <literal>-package lang</literal> too.</para>
63 <para>There's one case where you need to use the
64 <option>-package</option> option even for auto packages: when
65 linking a program in batch mode mode (<xref linkend="options-order"/>)
66 <footnote><para>This is because
67 GHC can't figure out from the object files which packages are
68 required; in <option>––make</option> mode and in
69 GHCi the compiler has more information available to figure out
70 the package dependencies. We might try to lift this restriction
71 in the future.</para></footnote>. For example, to link a
72 program consisting of objects <filename>Foo.o</filename> and
73 <filename>Main.o</filename>, where we made use of the
74 <literal>network</literal> package, we need to give GHC the <literal>-package</literal> flag thus:
76 <screen>$ ghc -o myprog Foo.o Main.o -package network</screen>
78 The same flag is necessary even if we compiled the modules from source, because GHC still
79 reckons it's in batch mode:
80 <screen>$ ghc -o myprog Foo.hs Main.hs -package network</screen>
81 In <literal>--make</literal> and <literal>--interactive</literal> modes (<xref linkend="modes"/>), however, GHC figures out
82 the auto packages required for linking without further assistance.
88 <sect2 id="using-local-packages">
89 <title>Maintaining a local set of packages</title>
91 <para>When GHC starts up, it automatically reads the default set
92 of packages from a configuration file, normally named
93 <filename>package.conf</filename> in your GHC installation
96 <para>You can load in additional package configuration files
97 using the <option>-package-conf</option> option:</para>
102 <option>-package-conf <replaceable>file</replaceable></option>
103 <indexterm><primary><option>-package-conf <replaceable>file</replaceable></option></primary></indexterm>
106 <para>Read in the package configuration file
107 <replaceable>file</replaceable> in addition to the system
108 default file. This allows the user to have a local set of
109 packages in addition to the system-wide ones.</para>
114 <para>To create your own package configuration file, just create
115 a new file and put the string
116 <quote><literal>[]</literal></quote> in it. Packages can be
117 added to the new configuration file using the
118 <literal>ghc-pkg</literal> tool, described in <xref
119 linkend="package-management"/>.</para>
122 <sect2 id="building-packages">
123 <title>Building a package from Haskell source</title>
124 <indexterm><primary>packages</primary>
125 <secondary>building</secondary></indexterm>
127 <para>It takes some special considerations to build a new
132 <para>A package may contain several Haskell modules. A
133 package may span many directories, or many packages may
134 exist in a single directory. Packages may not be mutually
139 <para>A package has a name
140 (e.g. <filename>base</filename>)</para>
144 <para>The Haskell code in a package may be built into one or
145 more archive libraries
146 (e.g. <filename>libHSfoo.a</filename>), or a single DLL on
147 Windows (e.g. <filename>HSfoo.dll</filename>). The
148 restriction to a single DLL on Windows is because the
149 package system is used to tell the compiler when it should
150 make an inter-DLL call rather than an intra-DLL call
151 (inter-DLL calls require an extra
152 indirection). <emphasis>Building packages as DLLs doesn't
153 work at the moment; see <xref linkend="win32-dlls-create"/>
154 for the gory details.</emphasis>
157 <para>Building a static library is done by using the
158 <literal>ar</literal> tool, like so:</para>
160 <screen>ar cqs libHSfoo.a A.o B.o C.o ...</screen>
162 <para>where <filename>A.o</filename>,
163 <filename>B.o</filename> and so on are the compiled Haskell
164 modules, and <filename>libHSfoo.a</filename> is the library
165 you wish to create. The syntax may differ slightly on your
166 system, so check the documentation if you run into
169 <para>Versions of the Haskell libraries for use with GHCi
170 may also be included: GHCi cannot load <literal>.a</literal>
171 files directly, instead it will look for an object file
172 called <filename>HSfoo.o</filename> and load that. On some
173 systems, the <literal>ghc-pkg</literal> tool can
174 automatically build the GHCi version of each library, see
175 <xref linkend="package-management"/>. To build these
176 libraries by hand from the <literal>.a</literal> archive, it
177 is possible to use GNU <command>ld</command> as
180 <screen>ld -r ––whole-archive -o HSfoo.o libHSfoo.a</screen>
185 <literal>––--whole-archive</literal> with
186 <literal>–all_load</literal> on MacOS X)</para>
188 <para>GHC does not maintain detailed cross-package
189 dependency information. It does remember which modules in
190 other packages the current module depends on, but not which
191 things within those imported things.</para>
195 <para>To compile a module which is to be part of a new package,
196 use the <literal>-package-name</literal> option:</para>
201 <option>-package-name <replaceable>foo</replaceable></option>
202 <indexterm><primary><literal>-package-name</literal></primary><secondary>option</secondary></indexterm>
205 <para>This option is added to the command line when
206 compiling a module that is destined to be part of package
207 <literal>foo</literal>. If this flag is omitted then the
208 default package <literal>Main</literal> is assumed.</para>
213 <para>Failure to use the <literal>-package-name</literal> option
214 when compiling a package will result in disaster on Windows, but
215 is relatively harmless on Unix at the moment (it will just cause
216 a few extra dependencies in some interface files). However,
217 bear in mind that we might add support for Unix shared libraries
218 at some point in the future.</para>
220 <para>It is worth noting that on Windows, when each package
221 is built as a DLL, since a reference to a DLL costs an extra
222 indirection, intra-package references are cheaper than
223 inter-package references. Of course, this applies to the
224 <filename>Main</filename> package as well.</para>
227 <sect2 id="package-management">
228 <title>Package management</title>
229 <indexterm><primary>packages</primary>
230 <secondary>management</secondary></indexterm>
232 <para>The <literal>ghc-pkg</literal> tool allows packages to be
233 added or removed from a package configuration file. By default,
234 the system-wide configuration file is used, but alternatively
235 packages can be added, updated or removed from a user-specified
236 configuration file using the <option>––config-file</option>
237 option. An empty package configuration file consists of the
238 string <quote><literal>[]</literal></quote>.</para>
240 <para>The <literal>ghc-pkg</literal> program accepts the
241 following options:</para>
246 <option>––add-package</option>
247 <indexterm><primary><option>––add-package</option></primary></indexterm>
253 <para>Reads package specification from the input (see below),
254 and adds it to the database of installed packages. The
255 package specification must be a package that isn't already
262 <option>––input-file=<replaceable>file</replaceable></option>
263 <indexterm><primary><option>––input-file</option></primary></indexterm>
266 <option>-i <replaceable>file</replaceable></option>
269 <para>Read new package specifications from file
270 <replaceable>file</replaceable>. If a value of
271 <filename>"-"</filename> is given, standard input is used.
272 If no <option>-i</option> is present on the command-line,
273 an input file of <filename>"-"</filename> is assumed.
280 <option>––auto-ghci-libs</option>
281 <indexterm><primary><option>––auto-ghci-libs</option></primary></indexterm>
287 <para>Automatically generate the GHCi
288 <filename>.o</filename> version of each
289 <filename>.a</filename> Haskell library, using GNU ld (if
290 that is available). Without this option,
291 <literal>ghc-pkg</literal> will warn if GHCi versions of
292 any Haskell libraries in the package don't exist.</para>
294 <para>GHCi <literal>.o</literal> libraries don't
295 necessarily have to live in the same directory as the
296 corresponding <literal>.a</literal> library. However,
297 this option will cause the GHCi library to be created in
298 the same directory as the <literal>.a</literal>
304 <term><option>––config-file <replaceable>file</replaceable></option></term>
305 <term><option>-f <replaceable>file</replaceable></option></term>
306 <indexterm><primary><option>––config-file</option></primary>
309 <para>Use <replaceable>file</replaceable> as an additional
310 package configuration file. This is used to modify
311 configuration files for use with GHC's
312 <option>-package-conf</option> option.</para>
314 <para>There may be any number of configuration files named
315 on the command line; files mentioned later on the
316 command-line override those mentioned earlier. The
317 <emphasis>last</emphasis> configuration file mentioned on
318 the command-line is the only one that is actually modified
319 by <literal>ghc-pkg</literal>.</para>
325 <term><option>––list-packages</option></term>
326 <term><option>-l</option></term>
327 <indexterm><primary><option>––list-packages</option></primary></indexterm>
329 <para>This option displays the list of currently installed
330 packages, including those in extra configuration files
331 specified with the <option>––config-file</option>
335 $ ghc-pkg ––list-packages
336 /usr/local/lib/ghc-5.05/package.conf:
337 hdirect, readline, lang, concurrent, posix, util, data, text, net,
338 hssource, rts, haskell98, network, haskell-src, unix, base
341 <para>Note that your GHC installation might have a
342 slightly different set of packages installed.</para>
344 <para>The <literal>rts</literal> package is always
345 present, and represents the runtime system library. The
346 <literal>base</literal> package contains the Haskell
347 prelude and basic hierarchical libraries, and the
348 <literal>haskell98</literal> package contains the Haskell
349 98 standard libraries. The rest of the packages are
350 optional libraries.</para>
355 <term><option>––list-local-packages</option></term>
356 <term><option>-L</option></term>
357 <indexterm><primary><option>––list-local-packages</option></primary></indexterm>
359 <para>Displays the list of packages installed in the
360 topmost configuration file only: that will be the
361 configuration file specified using <option>-f</option> on
362 the command line, or the system configuration file
365 <para>This option may be more convenient than
366 <option>-l</option> when the output needs to be parsed by
372 <term><option>––remove-package <replaceable>foo</replaceable></option></term>
373 <term><option>-r <replaceable>foo</replaceable></option></term>
374 <indexterm><primary><option>––delete-package</option></primary>
377 <para>Removes the specified package from the installed
378 configuration.</para>
382 <term><option>––update-package</option></term>
383 <term><option>-u</option></term>
384 <indexterm><primary><option>––update-package</option></primary></indexterm>
386 <para>Reads package specification from the input, and
387 adds it to the database of installed packages. If a package
388 with the same name is already installed, its configuration
389 data is replaced with the new information. If the package
390 doesn't already exist, it's added.
395 <term><option>––force</option></term>
396 <indexterm><primary><option>––force</option></primary></indexterm>
398 <para>Causes <literal>ghc-pkg</literal> to ignore missing
399 directories and libraries when adding a package, and just
400 go ahead and add it anyway. This might be useful if your
401 package installation system needs to add the package to
402 GHC before building and installing the files.</para>
407 <para>When modifying the configuration file
408 <replaceable>file</replaceable>, a copy of the original file is
409 saved in <replaceable>file</replaceable><literal>.old</literal>,
410 so in an emergency you can always restore the old settings by
411 copying the old file back again.</para>
413 <para>A package specification looks like this:</para>
419 import_dirs = ["${installdir}/imports/mypkg"],
421 library_dirs = ["${installdir}"],
422 hs_libraries = ["HSmypkg" ],
423 extra_libraries = ["HSmypkg_cbits"],
425 c_includes = ["HsMyPkg.h"],
426 package_deps = ["text", "data"],
429 extra_ld_opts = ["-lmy_clib"]
433 <para>Components of a package specification may be specified in
434 any order, and are:</para>
438 <term><literal>name</literal></term>
439 <indexterm><primary><literal>name</literal></primary>
440 <secondary>package specification</secondary></indexterm>
442 <para>The package's name, for use with
443 the <literal>-package</literal> flag and as listed in the
444 <literal>––list-packages</literal> list.
450 <term><literal>auto</literal></term>
451 <indexterm><primary><literal>auto</literal></primary>
452 <secondary>package specification</secondary>
455 <para>Set to <literal>True</literal> if the package should
456 be automatically available (see <xref
457 linkend="using-packages"/>). This is normally set to
458 <literal>True</literal> for packages which contain
459 hierarchical libraries, because in that case there is no
460 danger of polluting the module namespace.</para>
465 <term><literal>import_dirs</literal></term>
466 <indexterm><primary><literal>import_dirs</literal></primary>
467 <secondary>package specification</secondary></indexterm>
469 <para>A list of directories containing interface files
470 (<literal>.hi</literal> files) for this package.</para>
472 <para>If the package contains profiling libraries, then
473 the interface files for those library modules should have
474 the suffix <literal>.p_hi</literal>. So the package can
475 contain both normal and profiling versions of the same
476 library without conflict (see also
477 <literal>library_dirs</literal> below).</para>
482 <term><literal>source_dirs</literal></term>
483 <indexterm><primary><literal>source_dirs</literal></primary>
484 <secondary>package specification</secondary></indexterm>
486 <para>A list of directories containing Haskell source
487 files for this package. This field isn't used by GHC, but
488 could potentially be used by an all-interpreted system
494 <term><literal>library_dirs</literal></term>
495 <indexterm><primary><literal>library_dirs</literal></primary>
496 <secondary>package specification</secondary></indexterm>
498 <para>A list of directories containing libraries for this
504 <term><literal>hs_libraries</literal></term>
505 <indexterm><primary><literal>hs_libraries</literal></primary>
506 <secondary>package specification</secondary></indexterm>
508 <para>A list of libraries containing Haskell code for this
509 package, with the <literal>.a</literal> or
510 <literal>.dll</literal> suffix omitted. When packages are
511 built as libraries, the
512 <literal>lib</literal> prefix is also omitted.</para>
514 <para>For use with GHCi, each library should have an
515 object file too. The name of the object file does
516 <emphasis>not</emphasis> have a <literal>lib</literal>
517 prefix, and has the normal object suffix for your
520 <para>For example, if we specify a Haskell library as
521 <filename>HSfoo</filename> in the package spec, then the
522 various flavours of library that GHC actually uses will be
526 <term><filename>libHSfoo.a</filename></term>
528 <para>The name of the library on Unix and Windows
529 (mingw) systems. Note that we don't support
530 building dynamic libraries of Haskell code on Unix
535 <term><filename>HSfoo.dll</filename></term>
537 <para>The name of the dynamic library on Windows
538 systems (optional).</para>
542 <term><filename>HSfoo.o</filename></term>
543 <term><filename>HSfoo.obj</filename></term>
545 <para>The object version of the library used by
555 <term><literal>extra_libraries</literal></term>
556 <indexterm><primary><literal>extra_libraries</literal></primary>
557 <secondary>package specification</secondary></indexterm>
559 <para>A list of extra libraries for this package. The
560 difference between <literal>hs_libraries</literal> and
561 <literal>extra_libraries</literal> is that
562 <literal>hs_libraries</literal> normally have several
563 versions, to support profiling, parallel and other build
564 options. The various versions are given different
565 suffixes to distinguish them, for example the profiling
566 version of the standard prelude library is named
567 <filename>libHSstd_p.a</filename>, with the
568 <literal>_p</literal> indicating that this is a profiling
569 version. The suffix is added automatically by GHC for
570 <literal>hs_libraries</literal> only, no suffix is added
572 <literal>extra_libraries</literal>.</para>
574 <para>The libraries listed in
575 <literal>extra_libraries</literal> may be any libraries
576 supported by your system's linker, including dynamic
577 libraries (<literal>.so</literal> on Unix,
578 <literal>.DLL</literal> on Windows).</para>
580 <para>Also, <literal>extra_libraries</literal> are placed
581 on the linker command line after the
582 <literal>hs_libraries</literal> for the same package. If
583 your package has dependencies in the other direction (i.e.
584 <literal>extra_libraries</literal> depends on
585 <literal>hs_libraries</literal>), and the libraries are
586 static, you might need to make two separate
592 <term><literal>include_dirs</literal></term>
593 <indexterm><primary><literal>include_dirs</literal></primary>
594 <secondary>package specification</secondary></indexterm>
596 <para>A list of directories containing C includes for this
597 package (maybe the empty list).</para>
602 <term><literal>c_includes</literal></term>
603 <indexterm><primary><literal>c_includes</literal></primary>
604 <secondary>package specification</secondary></indexterm>
606 <para>A list of files to include for via-C compilations
607 using this package. Typically this include file will
608 contain function prototypes for any C functions used in
609 the package, in case they end up being called as a result
610 of Haskell functions from the package being
616 <term><literal>package_deps</literal></term>
617 <indexterm><primary><literal>package_deps</literal></primary>
618 <secondary>package specification</secondary></indexterm>
620 <para>A list of packages which this package depends
626 <term><literal>extra_ghc_opts</literal></term>
627 <indexterm><primary><literal>extra_ghc_opts</literal></primary>
628 <secondary>package specification</secondary></indexterm>
630 <para>Extra arguments to be added to the GHC command line
631 when this package is being used.</para>
636 <term><literal>extra_cc_opts</literal></term>
637 <indexterm><primary><literal>extra_cc_opts</literal></primary>
638 <secondary>package specification</secondary></indexterm>
640 <para>Extra arguments to be added to the gcc command line
641 when this package is being used (only for via-C
642 compilations).</para>
647 <term><literal>extra_ld_opts</literal></term>
648 <indexterm><primary><literal>extra_ld_opts</literal></primary>
649 <secondary>package specification</secondary></indexterm>
651 <para>Extra arguments to be added to the
652 <command>gcc</command> command line (for linking) when
653 this package is being used.</para>
658 <term><literal>framework_dirs</literal></term>
659 <indexterm><primary><literal>framework_dirs</literal></primary>
660 <secondary>package specification</secondary></indexterm>
662 <para>On Darwin/MacOS X, a list of directories containing frameworks for this
663 package. This corresponds to the <option>-framework-path</option> option.
664 It is ignored on all other platforms.</para>
669 <term><literal>extra_frameworks</literal></term>
670 <indexterm><primary><literal>extra_frameworks</literal></primary>
671 <secondary>package specification</secondary></indexterm>
673 <para>On Darwin/MacOS X, a list of frameworks to link to. This corresponds to the
674 <option>-framework</option> option. Take a look at Apple's developer documentation
675 to find out what frameworks actually are. This entry is ignored on all other platforms.</para>
681 The <literal>ghc-pkg</literal> tool performs expansion of
682 environment variables occurring in input package specifications.
683 So, if the <literal>mypkg</literal> was added to the package
687 $ installdir=/usr/local/lib ghc-pkg -a < mypkg.pkg
691 The occurrence of <literal>${installdir}</literal> is replaced
692 with <literal>/usr/local/lib</literal> in the package data that
693 is added for <literal>mypkg</literal>.
697 This feature enables the distribution of package specification
698 files that can be easily configured when installing.
701 <para>For examples of more package specifications, take a look
702 at the <literal>package.conf</literal> in your GHC
708 ;;; Local Variables: ***
710 ;;; sgml-parent-document: ("using.sgml" "book" "chapter") ***