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>To use a package, add the <literal>-package</literal> flag
29 to the GHC command line:</para>
33 <term><option>-package <replaceable>lib</replaceable></option></term>
34 <indexterm><primary>-package <replaceable>lib</replaceable> option</primary></indexterm>
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
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>
53 <sect2 id="using-local-packages">
54 <title>Maintaining a local set of packages</title>
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
61 <para>You can load in additional package configuration files
62 using the <option>-package-conf</option> option:</para>
66 <term><option>-package-conf <replaceable>file</replaceable></option></term>
67 <indexterm><primary><option>-package-conf <replaceable>file</replaceable></option></primary>
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>
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>
86 <sect2 id="building-packages">
87 <title>Building a package from Haskell source</title>
88 <indexterm><primary>packages</primary>
89 <secondary>building</secondary></indexterm>
91 <para>It takes some special considerations to build a new
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
103 <para>A package has a name
104 (e.g. <filename>base</filename>)</para>
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>
121 <para>Building a static library is done by using the
122 <literal>ar</literal> tool, like so:</para>
124 <screen>ar cqs libHSfoo.a A.o B.o C.o ...</screen>
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
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
144 <screen>ld -r ––whole-archive -o HSfoo.o libHSfoo.a</screen>
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>
155 <para>To compile a module which is to be part of a new package,
156 use the <literal>-package-name</literal> option:</para>
160 <term><option>-package-name <replaceable>foo</replaceable></option></term>
161 <indexterm><primary><literal>-package-name</literal></primary>
162 <secondary>option</secondary></indexterm>
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>
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>
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>
186 <sect2 id="package-management">
187 <title>Package management</title>
188 <indexterm><primary>packages</primary>
189 <secondary>management</secondary></indexterm>
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>––config-file</option>
196 option. An empty package configuration file consists of the
197 string <quote><literal>[]</literal></quote>.</para>
199 <para>The <literal>ghc-pkg</literal> program accepts the
200 following options:</para>
204 <term><option>––add-package</option></term>
205 <term><option>-a</option></term>
206 <indexterm><primary><option>––add-package</option></primary></indexterm>
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
216 <term><option>––input-file=<replaceable>file</replaceable></option></term>
217 <term><option>-i <replaceable>file</replaceable></option></term>
218 <indexterm><primary><option>––input-file</option></primary></indexterm>
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.
230 <term><option>––auto-ghci-libs</option></term>
231 <term><option>-g</option></term>
232 <indexterm><primary><option>––auto-ghci-libs</option></primary>
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>
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>
252 <term><option>––config-file <replaceable>file</replaceable></option></term>
253 <term><option>-f <replaceable>file</replaceable></option></term>
254 <indexterm><primary><option>––config-file</option></primary>
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>
266 <term><option>––list-packages</option></term>
267 <term><option>-l</option></term>
268 <indexterm><primary><option>––list-packages</option></primary></indexterm>
270 <para>This option displays the list of currently installed
274 $ ghc-pkg ––list-packages
275 gmp, rts, std, lang, concurrent, data, net, posix, text, util
278 <para>Note that your GHC installation might have a
279 slightly different set of packages installed.</para>
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
292 <term><option>––remove-package <replaceable>foo</replaceable></option></term>
293 <term><option>-r <replaceable>foo</replaceable></option></term>
294 <indexterm><primary><option>––delete-package</option></primary>
297 <para>Removes the specified package from the installed
298 configuration.</para>
302 <term><option>––update-package</option></term>
303 <term><option>-u</option></term>
304 <indexterm><primary><option>––update-package</option></primary></indexterm>
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.
315 <term><option>––force</option></term>
316 <indexterm><primary><option>––force</option></primary></indexterm>
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>
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>
333 <para>A package specification looks like this:</para>
338 import_dirs = ["${installdir}/imports/mypkg"],
340 library_dirs = ["${installdir}"],
341 hs_libraries = ["HSmypkg" ],
342 extra_libraries = ["HSmypkg_cbits"],
344 c_includes = ["HsMyPkg.h"],
345 package_deps = ["text", "data"],
348 extra_ld_opts = ["-lmy_clib"]
352 <para>Components of a package specification may be specified in
353 any order, and are:</para>
357 <term><literal>name</literal></term>
358 <indexterm><primary><literal>name</literal></primary>
359 <secondary>package specification</secondary></indexterm>
361 <para>The package's name, for use with
362 the <literal>-package</literal> flag and as listed in the
363 <literal>––list-packages</literal> list.
369 <term><literal>import_dirs</literal></term>
370 <indexterm><primary><literal>import_dirs</literal></primary>
371 <secondary>package specification</secondary></indexterm>
373 <para>A list of directories containing interface files
374 (<literal>.hi</literal> files) for this package.</para>
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>
386 <term><literal>source_dirs</literal></term>
387 <indexterm><primary><literal>source_dirs</literal></primary>
388 <secondary>package specification</secondary></indexterm>
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
398 <term><literal>library_dirs</literal></term>
399 <indexterm><primary><literal>library_dirs</literal></primary>
400 <secondary>package specification</secondary></indexterm>
402 <para>A list of directories containing libraries for this
408 <term><literal>hs_libraries</literal></term>
409 <indexterm><primary><literal>hs_libraries</literal></primary>
410 <secondary>package specification</secondary></indexterm>
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>
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
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
430 <term><filename>libHSfoo.a</filename></term>
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
439 <term><filename>HSfoo.dll</filename></term>
441 <para>The name of the dynamic library on Windows
442 systems (optional).</para>
446 <term><filename>HSfoo.o</filename></term>
447 <term><filename>HSfoo.obj</filename></term>
449 <para>The object version of the library used by
459 <term><literal>extra_libraries</literal></term>
460 <indexterm><primary><literal>extra_libraries</literal></primary>
461 <secondary>package specification</secondary></indexterm>
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
476 <literal>extra_libraries</literal>.</para>
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>
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
496 <term><literal>include_dirs</literal></term>
497 <indexterm><primary><literal>include_dirs</literal></primary>
498 <secondary>package specification</secondary></indexterm>
500 <para>A list of directories containing C includes for this
501 package (maybe the empty list).</para>
506 <term><literal>c_includes</literal></term>
507 <indexterm><primary><literal>c_includes</literal></primary>
508 <secondary>package specification</secondary></indexterm>
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
520 <term><literal>package_deps</literal></term>
521 <indexterm><primary><literal>package_deps</literal></primary>
522 <secondary>package specification</secondary></indexterm>
524 <para>A list of packages which this package depends
530 <term><literal>extra_ghc_opts</literal></term>
531 <indexterm><primary><literal>extra_ghc_opts</literal></primary>
532 <secondary>package specification</secondary></indexterm>
534 <para>Extra arguments to be added to the GHC command line
535 when this package is being used.</para>
540 <term><literal>extra_cc_opts</literal></term>
541 <indexterm><primary><literal>extra_cc_opts</literal></primary>
542 <secondary>package specification</secondary></indexterm>
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>
551 <term><literal>extra_ld_opts</literal></term>
552 <indexterm><primary><literal>extra_ld_opts</literal></primary>
553 <secondary>package specification</secondary></indexterm>
555 <para>Extra arguments to be added to the gcc command line
556 (for linking) when this package is being used.</para>
561 <term><literal>framework_dirs</literal></term>
562 <indexterm><primary><literal>framework_dirs</literal></primary>
563 <secondary>package specification</secondary></indexterm>
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>
572 <term><literal>extra_frameworks</literal></term>
573 <indexterm><primary><literal>extra_frameworks</literal></primary>
574 <secondary>package specification</secondary></indexterm>
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>
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
590 $ installdir=/usr/local/lib ghc-pkg -a < mypkg.pkg
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>.
600 This feature enables the distribution of package specification
601 files that can be easily configured when installing.
604 <para>For examples of more package specifications, take a look
605 at the <literal>package.conf</literal> in your GHC
611 ;;; Local Variables: ***
613 ;;; sgml-parent-document: ("using.sgml" "book" "chapter") ***