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 <xref
17 linkend="book-hslibs">), 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>std</filename>)</para>
108 <para>The Haskell code in a package may be built into one or
109 more archive libraries (e.g. <filename>libHSfoo.a</filename>),
110 or a single DLL on Windows
111 (e.g. <filename>HSfoo.dll</filename>). The restriction to a
112 single DLL on Windows is that the package system is used to
113 tell the compiler when it should make an inter-DLL call
114 rather than an intra-DLL call (inter-DLL calls require an
115 extra indirection). <emphasis>Building packages as DLLs
116 doesn't work at the moment; see <XRef
117 LinkEnd="win32-dlls-create"> for the gory details.</emphasis>
120 <para>Versions of the Haskell libraries for use with GHCi
121 may also be included: GHCi cannot load <literal>.a</literal>
122 files directly, instead it will look for an object file
123 called <filename>HSfoo.o</filename> and load that. The
124 <literal>ghc-pkg</literal> tool can automatically build the
125 GHCi version of each library, see <xref
126 linkend="package-management">. To build these libraries by
127 hand from the <literal>.a</literal> archive, it is possible
128 to use GNU <command>ld</command> as follows:</para>
130 <screen>ld -r ––whole-archive -o HSfoo.o libHSfoo.a</screen>
134 <para>GHC does not maintain detailed cross-package
135 dependency information. It does remember which modules in
136 other packages the current module depends on, but not which
137 things within those imported things.</para>
141 <para>To compile a module which is to be part of a new package,
142 use the <literal>-package-name</literal> option:</para>
146 <term><option>-package-name <replaceable>foo</replaceable></option></term>
147 <indexterm><primary><literal>-package-name</literal></primary>
148 <secondary>option</secondary></indexterm>
150 <para>This option is added to the command line when
151 compiling a module that is destined to be part of package
152 <literal>foo</literal>. If this flag is omitted then the
153 default package <literal>Main</literal> is assumed.</para>
158 <para>Failure to use the <literal>-package-name</literal> option
159 when compiling a package will result in disaster on Windows, but
160 is relatively harmless on Unix at the moment (it will just cause
161 a few extra dependencies in some interface files). However,
162 bear in mind that we might add support for Unix shared libraries
163 at some point in the future.</para>
165 <para>It is worth noting that on Windows, when each package
166 is built as a DLL, since a reference to a DLL costs an extra
167 indirection, intra-package references are cheaper than
168 inter-package references. Of course, this applies to the
169 <filename>Main</filename> package as well.</para>
172 <sect2 id="package-management">
173 <title>Package management</title>
174 <indexterm><primary>packages</primary>
175 <secondary>management</secondary></indexterm>
177 <para>The <literal>ghc-pkg</literal> tool allows packages to be
178 added or removed from a package configuration file. By default,
179 the system-wide configuration file is used, but alternatively
180 packages can be added, updated or removed from a user-specified
181 configuration file using the <option>––config-file</option>
182 option. An empty package configuration file consists of the
183 string <quote><literal>[]</literal></quote>.</para>
185 <para>The <literal>ghc-pkg</literal> program accepts the
186 following options:</para>
190 <term><option>––add-package</option></term>
191 <term><option>-a</option></term>
192 <indexterm><primary><option>––add-package</option></primary></indexterm>
194 <para>Reads package specification from the input (see below),
195 and adds it to the database of installed packages. The
196 package specification must be a package that isn't already
202 <term><option>––input-file=<replaceable>file</replaceable></option></term>
203 <term><option>-i <replaceable>file</replaceable></option></term>
204 <indexterm><primary><option>––input-file</option></primary></indexterm>
206 <para>Read new package specifications from file
207 <replaceable>file</replaceable>. If a value of
208 <filename>"-"</filename> is given, standard input is used.
209 If no <option>-i</option> is present on the command-line,
210 an input file of <filename>"-"</filename> is assumed.
216 <term><option>––auto-ghci-libs</option></term>
217 <term><option>-g</option></term>
218 <indexterm><primary><option>––auto-ghci-libs</option></primary>
221 <para>Automatically generate the GHCi
222 <filename>.o</filename> version of each
223 <filename>.a</filename> Haskell library, using GNU ld (if
224 that is available). Without this option,
225 <literal>ghc-pkg</literal> will warn if GHCi versions of
226 any Haskell libraries in the package don't exist.</para>
228 <para>GHCi <literal>.o</literal> libraries don't
229 necessarily have to live in the same directory as the
230 corresponding <literal>.a</literal> library. However,
231 this option will cause the GHCi library to be created in
232 the same directory as the <literal>.a</literal>
238 <term><option>––config-file <replaceable>file</replaceable></option></term>
239 <term><option>-f <replaceable>file</replaceable></option></term>
240 <indexterm><primary><option>––config-file</option></primary>
243 <para>Use <replaceable>file</replaceable> instead of the
244 default package configuration file. This, in conjunction
245 with GHC's <option>-package-conf</option> option, allows
246 a user to have a local set of packages in addition to the
247 system-wide installed set.</para>
252 <term><option>––list-packages</option></term>
253 <term><option>-l</option></term>
254 <indexterm><primary><option>––list-packages</option></primary></indexterm>
256 <para>This option displays the list of currently installed
260 $ ghc-pkg ––list-packages
261 gmp, rts, std, lang, concurrent, data, net, posix, text, util
264 <para>Note that your GHC installation might have a
265 slightly different set of packages installed.</para>
267 <para>The <literal>gmp</literal> and
268 <literal>rts</literal> packages are always present, and
269 represent the multi-precision integer and runtime system
270 libraries respectively. The <literal>std</literal>
271 package contains the Haskell prelude and standard
272 libraries. The rest of the packages are optional
278 <term><option>––remove-package <replaceable>foo</replaceable></option></term>
279 <term><option>-r <replaceable>foo</replaceable></option></term>
280 <indexterm><primary><option>––delete-package</option></primary>
283 <para>Removes the specified package from the installed
284 configuration.</para>
288 <term><option>––update-package</option></term>
289 <term><option>-u</option></term>
290 <indexterm><primary><option>––update-package</option></primary></indexterm>
292 <para>Reads package specification from the input, and
293 adds it to the database of installed packages. If a package
294 with the same name is already installed, its configuration
295 data is replaced with the new information. If the package
296 doesn't already exist, it's added.
301 <term><option>––force</option></term>
302 <indexterm><primary><option>––force</option></primary></indexterm>
304 <para>Causes <literal>ghc-pkg</literal> to ignore missing
305 directories and libraries when adding a package, and just
306 go ahead and add it anyway. This might be useful if your
307 package installation system needs to add the package to
308 GHC before building and installing the files.</para>
313 <para>When modifying the configuration file
314 <replaceable>file</replaceable>, a copy of the original file is
315 saved in <replaceable>file</replaceable><literal>.old</literal>,
316 so in an emergency you can always restore the old settings by
317 copying the old file back again.</para>
319 <para>A package specification looks like this:</para>
324 import_dirs = ["${installdir}/imports/mypkg"],
326 library_dirs = ["${installdir}"],
327 hs_libraries = ["HSmypkg" ],
328 extra_libraries = ["HSmypkg_cbits"],
330 c_includes = ["HsMyPkg.h"],
331 package_deps = ["text", "data"],
334 extra_ld_opts = ["-lmy_clib"]
338 <para>Components of a package specification may be specified in
339 any order, and are:</para>
343 <term><literal>name</literal></term>
344 <indexterm><primary><literal>name</literal></primary>
345 <secondary>package specification</secondary></indexterm>
347 <para>The package's name, for use with
348 the <literal>-package</literal> flag and as listed in the
349 <literal>––list-packages</literal> list.
355 <term><literal>import_dirs</literal></term>
356 <indexterm><primary><literal>import_dirs</literal></primary>
357 <secondary>package specification</secondary></indexterm>
359 <para>A list of directories containing interface files
360 (<literal>.hi</literal> files) for this package.</para>
365 <term><literal>source_dirs</literal></term>
366 <indexterm><primary><literal>source_dirs</literal></primary>
367 <secondary>package specification</secondary></indexterm>
369 <para>A list of directories containing Haskell source
370 files for this package. This field isn't used by GHC, but
371 could potentially be used by an all-interpreted system
377 <term><literal>library_dirs</literal></term>
378 <indexterm><primary><literal>library_dirs</literal></primary>
379 <secondary>package specification</secondary></indexterm>
381 <para>A list of directories containing libraries for this
387 <term><literal>hs_libraries</literal></term>
388 <indexterm><primary><literal>hs_libraries</literal></primary>
389 <secondary>package specification</secondary></indexterm>
391 <para>A list of libraries containing Haskell code for this
392 package, with the <literal>.a</literal> or
393 <literal>.dll</literal> suffix omitted. When packages are
394 built as libraries, the
395 <literal>lib</literal> prefix is also omitted.</para>
397 <para>For use with GHCi, each library should have an
398 object file too. The name of the object file does
399 <emphasis>not</emphasis> have a <literal>lib</literal>
400 prefix, and has the normal object suffix for your
403 <para>For example, if we specify a Haskell library as
404 <filename>HSfoo</filename> in the package spec, then the
405 various flavours of library that GHC actually uses will be
409 <term><filename>libHSfoo.a</filename></term>
411 <para>The name of the library on Unix
416 <term><filename>HSfoo.dll</filename></term>
418 <para>The name of the dynamic library on Windows
423 <term><filename>HSfoo.o</filename></term>
424 <term><filename>HSfoo.obj</filename></term>
426 <para>The object version of the library used by
436 <term><literal>extra_libraries</literal></term>
437 <indexterm><primary><literal>extra_libraries</literal></primary>
438 <secondary>package specification</secondary></indexterm>
440 <para>A list of extra libraries for this package. The
441 difference between <literal>hs_libraries</literal> and
442 <literal>extra_libraries</literal> is that
443 <literal>hs_libraries</literal> normally have several
444 versions, to support profiling, parallel and other build
445 options. The various versions are given different
446 suffixes to distinguish them, for example the profiling
447 version of the standard prelude library is named
448 <filename>libHSstd_p.a</filename>, with the
449 <literal>_p</literal> indicating that this is a profiling
450 version. The suffix is added automatically by GHC for
451 <literal>hs_libraries</literal> only, no suffix is added
453 <literal>extra_libraries</literal>.</para>
455 <para>Also, <literal>extra_libraries</literal> are placed
456 on the linker command line after the
457 <literal>hs_libraries</literal> for the same package. If
458 your package has dependencies in the other direction (i.e.
459 <literal>extra_libraries</literal> depends on
460 <literal>hs_libraries</literal>), and the libraries are
461 static, you might need to make two separate
467 <term><literal>include_dirs</literal></term>
468 <indexterm><primary><literal>include_dirs</literal></primary>
469 <secondary>package specification</secondary></indexterm>
471 <para>A list of directories containing C includes for this
472 package (maybe the empty list).</para>
477 <term><literal>c_includes</literal></term>
478 <indexterm><primary><literal>c_includes</literal></primary>
479 <secondary>package specification</secondary></indexterm>
481 <para>A list of files to include for via-C compilations
482 using this package. Typically this include file will
483 contain function prototypes for any C functions used in
484 the package, in case they end up being called as a result
485 of Haskell functions from the package being
491 <term><literal>package_deps</literal></term>
492 <indexterm><primary><literal>package_deps</literal></primary>
493 <secondary>package specification</secondary></indexterm>
495 <para>A list of packages which this package depends
501 <term><literal>extra_ghc_opts</literal></term>
502 <indexterm><primary><literal>extra_ghc_opts</literal></primary>
503 <secondary>package specification</secondary></indexterm>
505 <para>Extra arguments to be added to the GHC command line
506 when this package is being used.</para>
511 <term><literal>extra_cc_opts</literal></term>
512 <indexterm><primary><literal>extra_cc_opts</literal></primary>
513 <secondary>package specification</secondary></indexterm>
515 <para>Extra arguments to be added to the gcc command line
516 when this package is being used (only for via-C
517 compilations).</para>
522 <term><literal>extra_ld_opts</literal></term>
523 <indexterm><primary><literal>extra_ld_opts</literal></primary>
524 <secondary>package specification</secondary></indexterm>
526 <para>Extra arguments to be added to the gcc command line
527 (for linking) when this package is being used.</para>
533 The <literal>ghc-pkg</literal> tool performs expansion of
534 environment variables occurring in input package specifications.
535 So, if the <literal>mypkg</literal> was added to the package
539 $ installdir=/usr/local/lib ghc-pkg -a < mypkg.pkg
543 The occurrence of <literal>${installdir}</literal> is replaced
544 with <literal>/usr/local/lib</literal> in the package data that
545 is added for <literal>mypkg</literal>.
549 This feature enables the distribution of package specification
550 files that can be easily configured when installing.
553 <para>For examples of more package specifications, take a look
554 at the <literal>package.conf</literal> in your GHC
560 ;;; Local Variables: ***
562 ;;; sgml-parent-document: ("using.sgml" "book" "chapter") ***