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, called <emphasis>auto packages</emphasis>,
29 are automatically available: you don't need
30 to specify any extra flags to use them (except in certain
31 circumstances; see below). All the packages which contain
32 hierarchical libraries fall into this category.</para>
34 <para>Some other packages are <emphasis>not</emphasis>
35 automatically available: those are normally the packages
36 containing old non-hierarchical libraries. To gain access to a
37 non-auto package, use the <option>-package</option> command-line
42 <term><option>-package <replaceable>lib</replaceable></option></term>
43 <indexterm><primary>-package <replaceable>lib</replaceable> option</primary></indexterm>
45 <para>This option brings into scope all the modules from
46 package <literal><replaceable>lib</replaceable></literal> (they still have to
47 be imported in your Haskell source, however). It also
48 causes the relevant libraries to be linked when linking is
50 <para>Some packages depend on other packages, for example the
51 <literal>text</literal> package makes use of some of the modules
52 in the <literal>lang</literal> package. The package system
53 takes care of all these dependencies, so that when you say
54 <literal>-package text</literal> on the command line, you
55 automatically get <literal>-package lang</literal> too.</para>
60 <para>There's one case where you need to use the
61 <option>-package</option> option even for auto packages: when
62 linking a program in batch mode mode (<xref linkend="options-order">)
63 <footnote><para>This is because
64 GHC can't figure out from the object files which packages are
65 required; in <option>––make</option> mode and in
66 GHCi the compiler has more information available to figure out
67 the package dependencies. We might try to lift this restriction
68 in the future.</para></footnote>. For example, to link a
69 program consisting of objects <filename>Foo.o</filename> and
70 <filename>Main.o</filename>, where we made use of the
71 <literal>network</literal> package, we need to give GHC the <literal>-package</literal> flag thus:
73 <screen>$ ghc -o myprog Foo.o Main.o -package network</screen>
75 The same flag is necessary even if we compiled the modules from source, because GHC still
76 reckons it's in batch mode:
77 <screen>$ ghc -o myprog Foo.hs Main.hs -package network</screen>
78 In <literal>--make</literal> and <literal>--interactive</literal> modes (<xref linkend="modes">), however, GHC figures out
79 the auto packages required for linking without further assistance.
85 <sect2 id="using-local-packages">
86 <title>Maintaining a local set of packages</title>
88 <para>When GHC starts up, it automatically reads the default set
89 of packages from a configuration file, normally named
90 <filename>package.conf</filename> in your GHC installation
93 <para>You can load in additional package configuration files
94 using the <option>-package-conf</option> option:</para>
98 <term><option>-package-conf <replaceable>file</replaceable></option></term>
99 <indexterm><primary><option>-package-conf <replaceable>file</replaceable></option></primary>
102 <para>Read in the package configuration file
103 <replaceable>file</replaceable> in addition to the system
104 default file. This allows the user to have a local set of
105 packages in addition to the system-wide ones.</para>
110 <para>To create your own package configuration file, just create
111 a new file and put the string
112 <quote><literal>[]</literal></quote> in it. Packages can be
113 added to the new configuration file using the
114 <literal>ghc-pkg</literal> tool, described in <xref
115 linkend="package-management">.</para>
118 <sect2 id="building-packages">
119 <title>Building a package from Haskell source</title>
120 <indexterm><primary>packages</primary>
121 <secondary>building</secondary></indexterm>
123 <para>It takes some special considerations to build a new
128 <para>A package may contain several Haskell modules. A
129 package may span many directories, or many packages may
130 exist in a single directory. Packages may not be mutually
135 <para>A package has a name
136 (e.g. <filename>base</filename>)</para>
140 <para>The Haskell code in a package may be built into one or
141 more archive libraries
142 (e.g. <filename>libHSfoo.a</filename>), or a single DLL on
143 Windows (e.g. <filename>HSfoo.dll</filename>). The
144 restriction to a single DLL on Windows is because the
145 package system is used to tell the compiler when it should
146 make an inter-DLL call rather than an intra-DLL call
147 (inter-DLL calls require an extra
148 indirection). <emphasis>Building packages as DLLs doesn't
149 work at the moment; see <XRef LinkEnd="win32-dlls-create">
150 for the gory details.</emphasis>
153 <para>Building a static library is done by using the
154 <literal>ar</literal> tool, like so:</para>
156 <screen>ar cqs libHSfoo.a A.o B.o C.o ...</screen>
158 <para>where <filename>A.o</filename>,
159 <filename>B.o</filename> and so on are the compiled Haskell
160 modules, and <filename>libHSfoo.a</filename> is the library
161 you wish to create. The syntax may differ slightly on your
162 system, so check the documentation if you run into
165 <para>Versions of the Haskell libraries for use with GHCi
166 may also be included: GHCi cannot load <literal>.a</literal>
167 files directly, instead it will look for an object file
168 called <filename>HSfoo.o</filename> and load that. On some
169 systems, the <literal>ghc-pkg</literal> tool can
170 automatically build the GHCi version of each library, see
171 <xref linkend="package-management">. To build these
172 libraries by hand from the <literal>.a</literal> archive, it
173 is possible to use GNU <command>ld</command> as
176 <screen>ld -r ––whole-archive -o HSfoo.o libHSfoo.a</screen>
181 <literal>––--whole-archive</literal> with
182 <literal>–all_load</literal> on MacOS X)</para>
184 <para>GHC does not maintain detailed cross-package
185 dependency information. It does remember which modules in
186 other packages the current module depends on, but not which
187 things within those imported things.</para>
191 <para>To compile a module which is to be part of a new package,
192 use the <literal>-package-name</literal> option:</para>
196 <term><option>-package-name <replaceable>foo</replaceable></option></term>
197 <indexterm><primary><literal>-package-name</literal></primary>
198 <secondary>option</secondary></indexterm>
200 <para>This option is added to the command line when
201 compiling a module that is destined to be part of package
202 <literal>foo</literal>. If this flag is omitted then the
203 default package <literal>Main</literal> is assumed.</para>
208 <para>Failure to use the <literal>-package-name</literal> option
209 when compiling a package will result in disaster on Windows, but
210 is relatively harmless on Unix at the moment (it will just cause
211 a few extra dependencies in some interface files). However,
212 bear in mind that we might add support for Unix shared libraries
213 at some point in the future.</para>
215 <para>It is worth noting that on Windows, when each package
216 is built as a DLL, since a reference to a DLL costs an extra
217 indirection, intra-package references are cheaper than
218 inter-package references. Of course, this applies to the
219 <filename>Main</filename> package as well.</para>
222 <sect2 id="package-management">
223 <title>Package management</title>
224 <indexterm><primary>packages</primary>
225 <secondary>management</secondary></indexterm>
227 <para>The <literal>ghc-pkg</literal> tool allows packages to be
228 added or removed from a package configuration file. By default,
229 the system-wide configuration file is used, but alternatively
230 packages can be added, updated or removed from a user-specified
231 configuration file using the <option>––config-file</option>
232 option. An empty package configuration file consists of the
233 string <quote><literal>[]</literal></quote>.</para>
235 <para>The <literal>ghc-pkg</literal> program accepts the
236 following options:</para>
240 <term><option>––add-package</option></term>
241 <term><option>-a</option></term>
242 <indexterm><primary><option>––add-package</option></primary></indexterm>
244 <para>Reads package specification from the input (see below),
245 and adds it to the database of installed packages. The
246 package specification must be a package that isn't already
252 <term><option>––input-file=<replaceable>file</replaceable></option></term>
253 <term><option>-i <replaceable>file</replaceable></option></term>
254 <indexterm><primary><option>––input-file</option></primary></indexterm>
256 <para>Read new package specifications from file
257 <replaceable>file</replaceable>. If a value of
258 <filename>"-"</filename> is given, standard input is used.
259 If no <option>-i</option> is present on the command-line,
260 an input file of <filename>"-"</filename> is assumed.
266 <term><option>––auto-ghci-libs</option></term>
267 <term><option>-g</option></term>
268 <indexterm><primary><option>––auto-ghci-libs</option></primary>
271 <para>Automatically generate the GHCi
272 <filename>.o</filename> version of each
273 <filename>.a</filename> Haskell library, using GNU ld (if
274 that is available). Without this option,
275 <literal>ghc-pkg</literal> will warn if GHCi versions of
276 any Haskell libraries in the package don't exist.</para>
278 <para>GHCi <literal>.o</literal> libraries don't
279 necessarily have to live in the same directory as the
280 corresponding <literal>.a</literal> library. However,
281 this option will cause the GHCi library to be created in
282 the same directory as the <literal>.a</literal>
288 <term><option>––config-file <replaceable>file</replaceable></option></term>
289 <term><option>-f <replaceable>file</replaceable></option></term>
290 <indexterm><primary><option>––config-file</option></primary>
293 <para>Use <replaceable>file</replaceable> as an additional
294 package configuration file. This is used to modify
295 configuration files for use with GHC's
296 <option>-package-conf</option> option.</para>
298 <para>There may be any number of configuration files named
299 on the command line; files mentioned later on the
300 command-line override those mentioned earlier. The
301 <emphasis>last</emphasis> configuration file mentioned on
302 the command-line is the only one that is actually modified
303 by <literal>ghc-pkg</literal>.</para>
309 <term><option>––list-packages</option></term>
310 <term><option>-l</option></term>
311 <indexterm><primary><option>––list-packages</option></primary></indexterm>
313 <para>This option displays the list of currently installed
314 packages, including those in extra configuration files
315 specified with the <option>––config-file</option>
319 $ ghc-pkg ––list-packages
320 /usr/local/lib/ghc-5.05/package.conf:
321 hdirect, readline, lang, concurrent, posix, util, data, text, net,
322 hssource, rts, haskell98, network, haskell-src, unix, base
325 <para>Note that your GHC installation might have a
326 slightly different set of packages installed.</para>
328 <para>The <literal>rts</literal> package is always
329 present, and represents the runtime system library. The
330 <literal>base</literal> package contains the Haskell
331 prelude and basic hierarchical libraries, and the
332 <literal>haskell98</literal> package contains the Haskell
333 98 standard libraries. The rest of the packages are
334 optional libraries.</para>
339 <term><option>––list-local-packages</option></term>
340 <term><option>-L</option></term>
341 <indexterm><primary><option>––list-local-packages</option></primary></indexterm>
343 <para>Displays the list of packages installed in the
344 topmost configuration file only: that will be the
345 configuration file specified using <option>-f</option> on
346 the command line, or the system configuration file
349 <para>This option may be more convenient than
350 <option>-l</option> when the output needs to be parsed by
356 <term><option>––remove-package <replaceable>foo</replaceable></option></term>
357 <term><option>-r <replaceable>foo</replaceable></option></term>
358 <indexterm><primary><option>––delete-package</option></primary>
361 <para>Removes the specified package from the installed
362 configuration.</para>
366 <term><option>––update-package</option></term>
367 <term><option>-u</option></term>
368 <indexterm><primary><option>––update-package</option></primary></indexterm>
370 <para>Reads package specification from the input, and
371 adds it to the database of installed packages. If a package
372 with the same name is already installed, its configuration
373 data is replaced with the new information. If the package
374 doesn't already exist, it's added.
379 <term><option>––force</option></term>
380 <indexterm><primary><option>––force</option></primary></indexterm>
382 <para>Causes <literal>ghc-pkg</literal> to ignore missing
383 directories and libraries when adding a package, and just
384 go ahead and add it anyway. This might be useful if your
385 package installation system needs to add the package to
386 GHC before building and installing the files.</para>
391 <para>When modifying the configuration file
392 <replaceable>file</replaceable>, a copy of the original file is
393 saved in <replaceable>file</replaceable><literal>.old</literal>,
394 so in an emergency you can always restore the old settings by
395 copying the old file back again.</para>
397 <para>A package specification looks like this:</para>
403 import_dirs = ["${installdir}/imports/mypkg"],
405 library_dirs = ["${installdir}"],
406 hs_libraries = ["HSmypkg" ],
407 extra_libraries = ["HSmypkg_cbits"],
409 c_includes = ["HsMyPkg.h"],
410 package_deps = ["text", "data"],
413 extra_ld_opts = ["-lmy_clib"]
417 <para>Components of a package specification may be specified in
418 any order, and are:</para>
422 <term><literal>name</literal></term>
423 <indexterm><primary><literal>name</literal></primary>
424 <secondary>package specification</secondary></indexterm>
426 <para>The package's name, for use with
427 the <literal>-package</literal> flag and as listed in the
428 <literal>––list-packages</literal> list.
434 <term><literal>auto</literal></term>
435 <indexterm><primary><literal>auto</literal></primary>
436 <secondary>package specification</secondary>
439 <para>Set to <literal>True</literal> if the package should
440 be automatically available (see <xref
441 linkend="using-packages">). This is normally set to
442 <literal>True</literal> for packages which contain
443 hierarchical libraries, because in that case there is no
444 danger of polluting the module namespace.</para>
449 <term><literal>import_dirs</literal></term>
450 <indexterm><primary><literal>import_dirs</literal></primary>
451 <secondary>package specification</secondary></indexterm>
453 <para>A list of directories containing interface files
454 (<literal>.hi</literal> files) for this package.</para>
456 <para>If the package contains profiling libraries, then
457 the interface files for those library modules should have
458 the suffix <literal>.p_hi</literal>. So the package can
459 contain both normal and profiling versions of the same
460 library without conflict (see also
461 <literal>library_dirs</literal> below).</para>
466 <term><literal>source_dirs</literal></term>
467 <indexterm><primary><literal>source_dirs</literal></primary>
468 <secondary>package specification</secondary></indexterm>
470 <para>A list of directories containing Haskell source
471 files for this package. This field isn't used by GHC, but
472 could potentially be used by an all-interpreted system
478 <term><literal>library_dirs</literal></term>
479 <indexterm><primary><literal>library_dirs</literal></primary>
480 <secondary>package specification</secondary></indexterm>
482 <para>A list of directories containing libraries for this
488 <term><literal>hs_libraries</literal></term>
489 <indexterm><primary><literal>hs_libraries</literal></primary>
490 <secondary>package specification</secondary></indexterm>
492 <para>A list of libraries containing Haskell code for this
493 package, with the <literal>.a</literal> or
494 <literal>.dll</literal> suffix omitted. When packages are
495 built as libraries, the
496 <literal>lib</literal> prefix is also omitted.</para>
498 <para>For use with GHCi, each library should have an
499 object file too. The name of the object file does
500 <emphasis>not</emphasis> have a <literal>lib</literal>
501 prefix, and has the normal object suffix for your
504 <para>For example, if we specify a Haskell library as
505 <filename>HSfoo</filename> in the package spec, then the
506 various flavours of library that GHC actually uses will be
510 <term><filename>libHSfoo.a</filename></term>
512 <para>The name of the library on Unix and Windows
513 (mingw) systems. Note that we don't support
514 building dynamic libraries of Haskell code on Unix
519 <term><filename>HSfoo.dll</filename></term>
521 <para>The name of the dynamic library on Windows
522 systems (optional).</para>
526 <term><filename>HSfoo.o</filename></term>
527 <term><filename>HSfoo.obj</filename></term>
529 <para>The object version of the library used by
539 <term><literal>extra_libraries</literal></term>
540 <indexterm><primary><literal>extra_libraries</literal></primary>
541 <secondary>package specification</secondary></indexterm>
543 <para>A list of extra libraries for this package. The
544 difference between <literal>hs_libraries</literal> and
545 <literal>extra_libraries</literal> is that
546 <literal>hs_libraries</literal> normally have several
547 versions, to support profiling, parallel and other build
548 options. The various versions are given different
549 suffixes to distinguish them, for example the profiling
550 version of the standard prelude library is named
551 <filename>libHSstd_p.a</filename>, with the
552 <literal>_p</literal> indicating that this is a profiling
553 version. The suffix is added automatically by GHC for
554 <literal>hs_libraries</literal> only, no suffix is added
556 <literal>extra_libraries</literal>.</para>
558 <para>The libraries listed in
559 <literal>extra_libraries</literal> may be any libraries
560 supported by your system's linker, including dynamic
561 libraries (<literal>.so</literal> on Unix,
562 <literal>.DLL</literal> on Windows).</para>
564 <para>Also, <literal>extra_libraries</literal> are placed
565 on the linker command line after the
566 <literal>hs_libraries</literal> for the same package. If
567 your package has dependencies in the other direction (i.e.
568 <literal>extra_libraries</literal> depends on
569 <literal>hs_libraries</literal>), and the libraries are
570 static, you might need to make two separate
576 <term><literal>include_dirs</literal></term>
577 <indexterm><primary><literal>include_dirs</literal></primary>
578 <secondary>package specification</secondary></indexterm>
580 <para>A list of directories containing C includes for this
581 package (maybe the empty list).</para>
586 <term><literal>c_includes</literal></term>
587 <indexterm><primary><literal>c_includes</literal></primary>
588 <secondary>package specification</secondary></indexterm>
590 <para>A list of files to include for via-C compilations
591 using this package. Typically this include file will
592 contain function prototypes for any C functions used in
593 the package, in case they end up being called as a result
594 of Haskell functions from the package being
600 <term><literal>package_deps</literal></term>
601 <indexterm><primary><literal>package_deps</literal></primary>
602 <secondary>package specification</secondary></indexterm>
604 <para>A list of packages which this package depends
610 <term><literal>extra_ghc_opts</literal></term>
611 <indexterm><primary><literal>extra_ghc_opts</literal></primary>
612 <secondary>package specification</secondary></indexterm>
614 <para>Extra arguments to be added to the GHC command line
615 when this package is being used.</para>
620 <term><literal>extra_cc_opts</literal></term>
621 <indexterm><primary><literal>extra_cc_opts</literal></primary>
622 <secondary>package specification</secondary></indexterm>
624 <para>Extra arguments to be added to the gcc command line
625 when this package is being used (only for via-C
626 compilations).</para>
631 <term><literal>extra_ld_opts</literal></term>
632 <indexterm><primary><literal>extra_ld_opts</literal></primary>
633 <secondary>package specification</secondary></indexterm>
635 <para>Extra arguments to be added to the
636 <command>gcc</command> command line (for linking) when
637 this package is being used.</para>
642 <term><literal>framework_dirs</literal></term>
643 <indexterm><primary><literal>framework_dirs</literal></primary>
644 <secondary>package specification</secondary></indexterm>
646 <para>On Darwin/MacOS X, a list of directories containing frameworks for this
647 package. This corresponds to the <option>-framework-path</option> option.
648 It is ignored on all other platforms.</para>
653 <term><literal>extra_frameworks</literal></term>
654 <indexterm><primary><literal>extra_frameworks</literal></primary>
655 <secondary>package specification</secondary></indexterm>
657 <para>On Darwin/MacOS X, a list of frameworks to link to. This corresponds to the
658 <option>-framework</option> option. Take a look at Apple's developer documentation
659 to find out what frameworks actually are. This entry is ignored on all other platforms.</para>
665 The <literal>ghc-pkg</literal> tool performs expansion of
666 environment variables occurring in input package specifications.
667 So, if the <literal>mypkg</literal> was added to the package
671 $ installdir=/usr/local/lib ghc-pkg -a < mypkg.pkg
675 The occurrence of <literal>${installdir}</literal> is replaced
676 with <literal>/usr/local/lib</literal> in the package data that
677 is added for <literal>mypkg</literal>.
681 This feature enables the distribution of package specification
682 files that can be easily configured when installing.
685 <para>For examples of more package specifications, take a look
686 at the <literal>package.conf</literal> in your GHC
692 ;;; Local Variables: ***
694 ;;; sgml-parent-document: ("using.sgml" "book" "chapter") ***