2 <title>Packages</title>
3 <indexterm><primary>packages</primary></indexterm>
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>
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>
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>
23 <sect2 id="using-packages">
24 <title>Using a package</title>
25 <indexterm><primary>packages</primary>
26 <secondary>using</secondary></indexterm>
28 <para>Some packages are automatically available: you don't need
29 to specify any extra flags to use them (except in certain
30 circumstances; see below). All the packages which contain
31 hierarchical libraries fall into this category.</para>
33 <para>Some other packages are <emphasis>not</emphasis>
34 automatically available: those are normally the packages
35 containing old non-hierarchical libraries. To gain access to a
36 non-auto package, use the <option>-package</option> command-line
41 <term><option>-package <replaceable>lib</replaceable></option></term>
42 <indexterm><primary>-package <replaceable>lib</replaceable> option</primary></indexterm>
44 <para>This option brings into scope all the modules from
45 package <literal><replaceable>lib</replaceable></literal> (they still have to
46 be imported in your Haskell source, however). It also
47 causes the relevant libraries to be linked when linking is
53 <para>There's one case where you need to use the
54 <option>-package</option> option even for auto packages: when
55 linking a program in batch mode<footnote><para>This is because
56 GHC can't figure out from the object files which packages are
57 required; in <option>––make</option> mode and in
58 GHCi the compiler has more information available to figure out
59 the package dependencies. We might try to lift this restriction
60 in the future.</para></footnote>. For example, to link a
61 program consisting of objects <filename>Foo.o</filename> and
62 <filename>Main.o</filename>, where we made use of the
63 <literal>network</literal> package:</para>
65 <screen>$ ghc -o myprog Foo.o Main.o -package network</screen>
67 <para>Some packages depend on other packages, for example the
68 <literal>text</literal> package makes use of some of the modules
69 in the <literal>lang</literal> package. The package system
70 takes care of all these dependencies, so that when you say
71 <literal>-package text</literal> on the command line, you
72 automatically get <literal>-package lang</literal> too.</para>
75 <sect2 id="using-local-packages">
76 <title>Maintaining a local set of packages</title>
78 <para>When GHC starts up, it automatically reads the default set
79 of packages from a configuration file, normally named
80 <filename>package.conf</filename> in your GHC installation
83 <para>You can load in additional package configuration files
84 using the <option>-package-conf</option> option:</para>
88 <term><option>-package-conf <replaceable>file</replaceable></option></term>
89 <indexterm><primary><option>-package-conf <replaceable>file</replaceable></option></primary>
92 <para>Read in the package configuration file
93 <replaceable>file</replaceable> in addition to the system
94 default file. This allows the user to have a local set of
95 packages in addition to the system-wide ones.</para>
100 <para>To create your own package configuration file, just create
101 a new file and put the string
102 <quote><literal>[]</literal></quote> in it. Packages can be
103 added to the new configuration file using the
104 <literal>ghc-pkg</literal> tool, described in <xref
105 linkend="package-management">.</para>
108 <sect2 id="building-packages">
109 <title>Building a package from Haskell source</title>
110 <indexterm><primary>packages</primary>
111 <secondary>building</secondary></indexterm>
113 <para>It takes some special considerations to build a new
118 <para>A package may contain several Haskell modules. A
119 package may span many directories, or many packages may
120 exist in a single directory. Packages may not be mutually
125 <para>A package has a name
126 (e.g. <filename>base</filename>)</para>
130 <para>The Haskell code in a package may be built into one or
131 more archive libraries
132 (e.g. <filename>libHSfoo.a</filename>), or a single DLL on
133 Windows (e.g. <filename>HSfoo.dll</filename>). The
134 restriction to a single DLL on Windows is because the
135 package system is used to tell the compiler when it should
136 make an inter-DLL call rather than an intra-DLL call
137 (inter-DLL calls require an extra
138 indirection). <emphasis>Building packages as DLLs doesn't
139 work at the moment; see <XRef LinkEnd="win32-dlls-create">
140 for the gory details.</emphasis>
143 <para>Building a static library is done by using the
144 <literal>ar</literal> tool, like so:</para>
146 <screen>ar cqs libHSfoo.a A.o B.o C.o ...</screen>
148 <para>where <filename>A.o</filename>,
149 <filename>B.o</filename> and so on are the compiled Haskell
150 modules, and <filename>libHSfoo.a</filename> is the library
151 you wish to create. The syntax may differ slightly on your
152 system, so check the documentation if you run into
155 <para>Versions of the Haskell libraries for use with GHCi
156 may also be included: GHCi cannot load <literal>.a</literal>
157 files directly, instead it will look for an object file
158 called <filename>HSfoo.o</filename> and load that. On some
159 systems, the <literal>ghc-pkg</literal> tool can
160 automatically build the GHCi version of each library, see
161 <xref linkend="package-management">. To build these
162 libraries by hand from the <literal>.a</literal> archive, it
163 is possible to use GNU <command>ld</command> as
166 <screen>ld -r ––whole-archive -o HSfoo.o libHSfoo.a</screen>
171 <literal>––--whole-archive</literal> with
172 <literal>–all_load</literal> on MacOS X)</para>
174 <para>GHC does not maintain detailed cross-package
175 dependency information. It does remember which modules in
176 other packages the current module depends on, but not which
177 things within those imported things.</para>
181 <para>To compile a module which is to be part of a new package,
182 use the <literal>-package-name</literal> option:</para>
186 <term><option>-package-name <replaceable>foo</replaceable></option></term>
187 <indexterm><primary><literal>-package-name</literal></primary>
188 <secondary>option</secondary></indexterm>
190 <para>This option is added to the command line when
191 compiling a module that is destined to be part of package
192 <literal>foo</literal>. If this flag is omitted then the
193 default package <literal>Main</literal> is assumed.</para>
198 <para>Failure to use the <literal>-package-name</literal> option
199 when compiling a package will result in disaster on Windows, but
200 is relatively harmless on Unix at the moment (it will just cause
201 a few extra dependencies in some interface files). However,
202 bear in mind that we might add support for Unix shared libraries
203 at some point in the future.</para>
205 <para>It is worth noting that on Windows, when each package
206 is built as a DLL, since a reference to a DLL costs an extra
207 indirection, intra-package references are cheaper than
208 inter-package references. Of course, this applies to the
209 <filename>Main</filename> package as well.</para>
212 <sect2 id="package-management">
213 <title>Package management</title>
214 <indexterm><primary>packages</primary>
215 <secondary>management</secondary></indexterm>
217 <para>The <literal>ghc-pkg</literal> tool allows packages to be
218 added or removed from a package configuration file. By default,
219 the system-wide configuration file is used, but alternatively
220 packages can be added, updated or removed from a user-specified
221 configuration file using the <option>––config-file</option>
222 option. An empty package configuration file consists of the
223 string <quote><literal>[]</literal></quote>.</para>
225 <para>The <literal>ghc-pkg</literal> program accepts the
226 following options:</para>
230 <term><option>––add-package</option></term>
231 <term><option>-a</option></term>
232 <indexterm><primary><option>––add-package</option></primary></indexterm>
234 <para>Reads package specification from the input (see below),
235 and adds it to the database of installed packages. The
236 package specification must be a package that isn't already
242 <term><option>––input-file=<replaceable>file</replaceable></option></term>
243 <term><option>-i <replaceable>file</replaceable></option></term>
244 <indexterm><primary><option>––input-file</option></primary></indexterm>
246 <para>Read new package specifications from file
247 <replaceable>file</replaceable>. If a value of
248 <filename>"-"</filename> is given, standard input is used.
249 If no <option>-i</option> is present on the command-line,
250 an input file of <filename>"-"</filename> is assumed.
256 <term><option>––auto-ghci-libs</option></term>
257 <term><option>-g</option></term>
258 <indexterm><primary><option>––auto-ghci-libs</option></primary>
261 <para>Automatically generate the GHCi
262 <filename>.o</filename> version of each
263 <filename>.a</filename> Haskell library, using GNU ld (if
264 that is available). Without this option,
265 <literal>ghc-pkg</literal> will warn if GHCi versions of
266 any Haskell libraries in the package don't exist.</para>
268 <para>GHCi <literal>.o</literal> libraries don't
269 necessarily have to live in the same directory as the
270 corresponding <literal>.a</literal> library. However,
271 this option will cause the GHCi library to be created in
272 the same directory as the <literal>.a</literal>
278 <term><option>––config-file <replaceable>file</replaceable></option></term>
279 <term><option>-f <replaceable>file</replaceable></option></term>
280 <indexterm><primary><option>––config-file</option></primary>
283 <para>Use <replaceable>file</replaceable> as an additional
284 package configuration file. This is used to modify
285 configuration files for use with GHC's
286 <option>-package-conf</option> option.</para>
288 <para>There may be any number of configuration files named
289 on the command line; files mentioned later on the
290 command-line override those mentioned earlier. The
291 <emphasis>last</emphasis> configuration file mentioned on
292 the command-line is the only one that is actually modified
293 by <literal>ghc-pkg</literal>.</para>
299 <term><option>––list-packages</option></term>
300 <term><option>-l</option></term>
301 <indexterm><primary><option>––list-packages</option></primary></indexterm>
303 <para>This option displays the list of currently installed
304 packages, including those in extra configuration files
305 specified with the <option>––config-file</option>
309 $ ghc-pkg ––list-packages
310 /usr/local/lib/ghc-5.05/package.conf:
311 hdirect, readline, lang, concurrent, posix, util, data, text, net,
312 hssource, rts, haskell98, network, haskell-src, unix, base
315 <para>Note that your GHC installation might have a
316 slightly different set of packages installed.</para>
318 <para>The <literal>rts</literal> package is always
319 present, and represents the runtime system library. The
320 <literal>base</literal> package contains the Haskell
321 prelude and basic hierarchical libraries, and the
322 <literal>haskell98</literal> package contains the Haskell
323 98 standard libraries. The rest of the packages are
324 optional libraries.</para>
329 <term><option>––list-local-packages</option></term>
330 <term><option>-L</option></term>
331 <indexterm><primary><option>––list-local-packages</option></primary></indexterm>
333 <para>Displays the list of packages installed in the
334 topmost configuration file only: that will be the
335 configuration file specified using <option>-f</option> on
336 the command line, or the system configuration file
339 <para>This option may be more convenient than
340 <option>-l</option> when the output needs to be parsed by
346 <term><option>––remove-package <replaceable>foo</replaceable></option></term>
347 <term><option>-r <replaceable>foo</replaceable></option></term>
348 <indexterm><primary><option>––delete-package</option></primary>
351 <para>Removes the specified package from the installed
352 configuration.</para>
356 <term><option>––update-package</option></term>
357 <term><option>-u</option></term>
358 <indexterm><primary><option>––update-package</option></primary></indexterm>
360 <para>Reads package specification from the input, and
361 adds it to the database of installed packages. If a package
362 with the same name is already installed, its configuration
363 data is replaced with the new information. If the package
364 doesn't already exist, it's added.
369 <term><option>––force</option></term>
370 <indexterm><primary><option>––force</option></primary></indexterm>
372 <para>Causes <literal>ghc-pkg</literal> to ignore missing
373 directories and libraries when adding a package, and just
374 go ahead and add it anyway. This might be useful if your
375 package installation system needs to add the package to
376 GHC before building and installing the files.</para>
381 <para>When modifying the configuration file
382 <replaceable>file</replaceable>, a copy of the original file is
383 saved in <replaceable>file</replaceable><literal>.old</literal>,
384 so in an emergency you can always restore the old settings by
385 copying the old file back again.</para>
387 <para>A package specification looks like this:</para>
393 import_dirs = ["${installdir}/imports/mypkg"],
395 library_dirs = ["${installdir}"],
396 hs_libraries = ["HSmypkg" ],
397 extra_libraries = ["HSmypkg_cbits"],
399 c_includes = ["HsMyPkg.h"],
400 package_deps = ["text", "data"],
403 extra_ld_opts = ["-lmy_clib"]
407 <para>Components of a package specification may be specified in
408 any order, and are:</para>
412 <term><literal>name</literal></term>
413 <indexterm><primary><literal>name</literal></primary>
414 <secondary>package specification</secondary></indexterm>
416 <para>The package's name, for use with
417 the <literal>-package</literal> flag and as listed in the
418 <literal>––list-packages</literal> list.
424 <term><literal>auto</literal></term>
425 <indexterm><primary><literal>auto</literal></primary>
426 <secondary>package specification</secondary>
429 <para>Set to <literal>True</literal> if the package should
430 be automatically available (see <xref
431 linkend="using-packages">). This is normally set to
432 <literal>True</literal> for packages which contain
433 hierarchical libraries, because in that case there is no
434 danger of polluting the module namespace.</para>
439 <term><literal>import_dirs</literal></term>
440 <indexterm><primary><literal>import_dirs</literal></primary>
441 <secondary>package specification</secondary></indexterm>
443 <para>A list of directories containing interface files
444 (<literal>.hi</literal> files) for this package.</para>
446 <para>If the package contains profiling libraries, then
447 the interface files for those library modules should have
448 the suffix <literal>.p_hi</literal>. So the package can
449 contain both normal and profiling versions of the same
450 library without conflict (see also
451 <literal>library_dirs</literal> below).</para>
456 <term><literal>source_dirs</literal></term>
457 <indexterm><primary><literal>source_dirs</literal></primary>
458 <secondary>package specification</secondary></indexterm>
460 <para>A list of directories containing Haskell source
461 files for this package. This field isn't used by GHC, but
462 could potentially be used by an all-interpreted system
468 <term><literal>library_dirs</literal></term>
469 <indexterm><primary><literal>library_dirs</literal></primary>
470 <secondary>package specification</secondary></indexterm>
472 <para>A list of directories containing libraries for this
478 <term><literal>hs_libraries</literal></term>
479 <indexterm><primary><literal>hs_libraries</literal></primary>
480 <secondary>package specification</secondary></indexterm>
482 <para>A list of libraries containing Haskell code for this
483 package, with the <literal>.a</literal> or
484 <literal>.dll</literal> suffix omitted. When packages are
485 built as libraries, the
486 <literal>lib</literal> prefix is also omitted.</para>
488 <para>For use with GHCi, each library should have an
489 object file too. The name of the object file does
490 <emphasis>not</emphasis> have a <literal>lib</literal>
491 prefix, and has the normal object suffix for your
494 <para>For example, if we specify a Haskell library as
495 <filename>HSfoo</filename> in the package spec, then the
496 various flavours of library that GHC actually uses will be
500 <term><filename>libHSfoo.a</filename></term>
502 <para>The name of the library on Unix and Windows
503 (mingw) systems. Note that we don't support
504 building dynamic libraries of Haskell code on Unix
509 <term><filename>HSfoo.dll</filename></term>
511 <para>The name of the dynamic library on Windows
512 systems (optional).</para>
516 <term><filename>HSfoo.o</filename></term>
517 <term><filename>HSfoo.obj</filename></term>
519 <para>The object version of the library used by
529 <term><literal>extra_libraries</literal></term>
530 <indexterm><primary><literal>extra_libraries</literal></primary>
531 <secondary>package specification</secondary></indexterm>
533 <para>A list of extra libraries for this package. The
534 difference between <literal>hs_libraries</literal> and
535 <literal>extra_libraries</literal> is that
536 <literal>hs_libraries</literal> normally have several
537 versions, to support profiling, parallel and other build
538 options. The various versions are given different
539 suffixes to distinguish them, for example the profiling
540 version of the standard prelude library is named
541 <filename>libHSstd_p.a</filename>, with the
542 <literal>_p</literal> indicating that this is a profiling
543 version. The suffix is added automatically by GHC for
544 <literal>hs_libraries</literal> only, no suffix is added
546 <literal>extra_libraries</literal>.</para>
548 <para>The libraries listed in
549 <literal>extra_libraries</literal> may be any libraries
550 supported by your system's linker, including dynamic
551 libraries (<literal>.so</literal> on Unix,
552 <literal>.DLL</literal> on Windows).</para>
554 <para>Also, <literal>extra_libraries</literal> are placed
555 on the linker command line after the
556 <literal>hs_libraries</literal> for the same package. If
557 your package has dependencies in the other direction (i.e.
558 <literal>extra_libraries</literal> depends on
559 <literal>hs_libraries</literal>), and the libraries are
560 static, you might need to make two separate
566 <term><literal>include_dirs</literal></term>
567 <indexterm><primary><literal>include_dirs</literal></primary>
568 <secondary>package specification</secondary></indexterm>
570 <para>A list of directories containing C includes for this
571 package (maybe the empty list).</para>
576 <term><literal>c_includes</literal></term>
577 <indexterm><primary><literal>c_includes</literal></primary>
578 <secondary>package specification</secondary></indexterm>
580 <para>A list of files to include for via-C compilations
581 using this package. Typically this include file will
582 contain function prototypes for any C functions used in
583 the package, in case they end up being called as a result
584 of Haskell functions from the package being
590 <term><literal>package_deps</literal></term>
591 <indexterm><primary><literal>package_deps</literal></primary>
592 <secondary>package specification</secondary></indexterm>
594 <para>A list of packages which this package depends
600 <term><literal>extra_ghc_opts</literal></term>
601 <indexterm><primary><literal>extra_ghc_opts</literal></primary>
602 <secondary>package specification</secondary></indexterm>
604 <para>Extra arguments to be added to the GHC command line
605 when this package is being used.</para>
610 <term><literal>extra_cc_opts</literal></term>
611 <indexterm><primary><literal>extra_cc_opts</literal></primary>
612 <secondary>package specification</secondary></indexterm>
614 <para>Extra arguments to be added to the gcc command line
615 when this package is being used (only for via-C
616 compilations).</para>
621 <term><literal>extra_ld_opts</literal></term>
622 <indexterm><primary><literal>extra_ld_opts</literal></primary>
623 <secondary>package specification</secondary></indexterm>
625 <para>Extra arguments to be added to the
626 <command>gcc</command> command line (for linking) when
627 this package is being used.</para>
632 <term><literal>framework_dirs</literal></term>
633 <indexterm><primary><literal>framework_dirs</literal></primary>
634 <secondary>package specification</secondary></indexterm>
636 <para>On Darwin/MacOS X, a list of directories containing frameworks for this
637 package. This corresponds to the <option>-framework-path</option> option.
638 It is ignored on all other platforms.</para>
643 <term><literal>extra_frameworks</literal></term>
644 <indexterm><primary><literal>extra_frameworks</literal></primary>
645 <secondary>package specification</secondary></indexterm>
647 <para>On Darwin/MacOS X, a list of frameworks to link to. This corresponds to the
648 <option>-framework</option> option. Take a look at Apple's developer documentation
649 to find out what frameworks actually are. This entry is ignored on all other platforms.</para>
655 The <literal>ghc-pkg</literal> tool performs expansion of
656 environment variables occurring in input package specifications.
657 So, if the <literal>mypkg</literal> was added to the package
661 $ installdir=/usr/local/lib ghc-pkg -a < mypkg.pkg
665 The occurrence of <literal>${installdir}</literal> is replaced
666 with <literal>/usr/local/lib</literal> in the package data that
667 is added for <literal>mypkg</literal>.
671 This feature enables the distribution of package specification
672 files that can be easily configured when installing.
675 <para>For examples of more package specifications, take a look
676 at the <literal>package.conf</literal> in your GHC
682 ;;; Local Variables: ***
684 ;;; sgml-parent-document: ("using.sgml" "book" "chapter") ***