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/removed from an
18 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="building-packages">
54 <title>Building a package from Haskell source</title>
55 <indexterm><primary>packages</primary>
56 <secondary>building</secondary></indexterm>
58 <para>It takes some special considerations to build a new
63 <para>A package may contain several Haskell modules. A
64 package may span many directories, or many packages may
65 exist in a single directory. Packages may not be mutually
70 <para>A package has a name
71 (e.g. <filename>std</filename>)</para>
75 <para>The Haskell code in a package may be built into one or
76 more Unix libraries (e.g. <filename>libHSfoo.a</filename>),
77 or a single DLL on Windows
78 (e.g. <filename>HSfoo.dll</filename>). The restriction to a
79 single DLL on Windows is that the package system is used to
80 tell the compiler when it should make an inter-DLL call
81 rather than an intra-DLL call (inter-DLL calls require an
82 extra indirection). <Strong>Building packages as DLLs
83 doesn't work at the moment; see <XRef
84 LinkEnd="win32-dlls-create"> for the gory details.</Strong>
87 <para>Versions of the Haskell libraries for use with GHCi
88 may also be included: GHCi cannot load <literal>.a</literal>
89 files directly, instead it will look for an object file
90 called <filename>HSfoo.o</filename> (the object suffix
91 varies between platforms, as usual) and load that. An
92 object file can be built from a <literal>.a</literal>
93 archive as follows (using GNU <command>ld</command> on
97 ld -r --whole-archive -o HSfoo.o libHSfoo.a
102 <para>GHC does not maintain detailed cross-package
103 dependency information. It does remember which modules in
104 other packages the current module depends on, but not which
105 things within those imported things.</para>
109 <para>To compile a module which is to be part of a new package,
110 use the <literal>-package-name</literal> option:</para>
114 <term><option>-package-name <replaceable>foo</replaceable></option></term>
115 <indexterm><primary><literal>-package-name</literal></primary>
116 <secondary>option</secondary></indexterm>
118 <para>This option is added to the command line when
119 compiling a module that is destined to be part of package
120 <literal>foo</literal>. If this flag is omitted then the
121 default package <literal>Main</literal> is assumed.</para>
126 <para>Failure to use the <literal>-package-name</literal> option
127 when compiling a package will result in disaster on Windows, but
128 is relatively harmless on Unix at the moment (it will just cause
129 a few extra dependencies in some interface files). However,
130 bear in mind that we might add support for Unix shared libraries
131 at some point in the future.</para>
133 <para>It is worth noting that on Windows, when each package
134 is built as a DLL, since a reference to a DLL costs an extra
135 indirection, intra-package references are cheaper than
136 inter-package references. Of course, this applies to the
137 <filename>Main</filename> package as well.</para>
140 <sect2 id="package-management">
141 <title>Package management</title>
142 <indexterm><primary>packages</primary>
143 <secondary>management</secondary></indexterm>
145 <para>GHC uses a package configuration file, called
146 <literal>packages.conf</literal>, which can be found in your GHC
147 install directory. This file isn't intended to be edited
148 directly, instead packages can be added or removed using GHC's
149 package management tool, <literal>ghc-pkg</literal>.</para>
153 <term><option>--list-packages</option></term>
154 <term><option>-l</option></term>
155 <indexterm><primary><option>--list-packages</option></primary></indexterm>
157 <para>This option displays the list of currently installed
161 $ ghc-pkg --list-packages
162 gmp, rts, std, lang, concurrent, data, net, posix, text, util
165 <para>Note that your GHC installation might have a
166 slightly different set of packages installed.</para>
168 <para>The <literal>gmp</literal> and
169 <literal>rts</literal> packages are always present, and
170 represent the multi-precision integer and runtime system
171 libraries respectively. The <literal>std</literal>
172 package contains the Haskell prelude and standard
173 libraries. The rest of the packages are optional
179 <term><option>--add-package</option></term>
180 <term><option>-a</option></term>
181 <indexterm><primary><option>--add-package</option></primary>
184 <para>Reads a package specification (see below) on stdin,
185 and adds it to the database of installed packages. The
186 package specification must be a package that isn't already
192 <term><option>--remove-package <replaceable>foo</replaceable></option></term>
193 <term><option>-r <replaceable>foo</replaceable></option></term>
194 <indexterm><primary><option>--delete-package</option></primary>
197 <para>Removes the specified package from the installed
198 configuration.</para>
203 <para>In both cases, the old package configuration file is saved
204 in <literal>packages.conf.old</literal> in your GHC install
205 directory, so in an emergency you can always copy this file into
206 <literal>package.conf</literal> to restore the old
209 <para>A package specification looks like this:</para>
214 import_dirs = ["/usr/local/lib/imports/mypkg"],
216 library_dirs = ["/usr/local/lib"],
217 hs_libraries = ["HSmypkg" ],
218 extra_libraries = ["HSmypkg_cbits"],
220 c_includes = ["HsMyPkg.h"],
221 package_deps = ["text", "data"],
224 extra_ld_opts = ["-lmy_clib"]
228 <para>Components of a package specification may be specified in
229 any order, and are:</para>
233 <term><literal>name</literal></term>
234 <indexterm><primary><literal>name</literal></primary>
235 <secondary>package specification</secondary></indexterm>
237 <para>The package's name, for use with
238 the <literal>-package</literal> flag and as listed in the
239 <literal>--list-packages</literal> list.
245 <term><literal>import_dirs</literal></term>
246 <indexterm><primary><literal>import_dirs</literal></primary>
247 <secondary>package specification</secondary></indexterm>
249 <para>A list of directories containing interface files
250 (<literal>.hi</literal> files) for this package.</para>
255 <term><literal>source_dirs</literal></term>
256 <indexterm><primary><literal>source_dirs</literal></primary>
257 <secondary>package specification</secondary></indexterm>
259 <para>A list of directories containing Haskell source
260 files for this package. This field isn't used by GHC, but
261 could potentially be used by an all-interpreted system
267 <term><literal>library_dirs</literal></term>
268 <indexterm><primary><literal>library_dirs</literal></primary>
269 <secondary>package specification</secondary></indexterm>
271 <para>A list of directories containing libraries for this
277 <term><literal>hs_libraries</literal></term>
278 <indexterm><primary><literal>hs_libraries</literal></primary>
279 <secondary>package specification</secondary></indexterm>
281 <para>A list of libraries containing Haskell code for this
282 package, with the <literal>.a</literal> or
283 <literal>.dll</literal> suffix omitted. When packages are
284 built as libraries, the
285 <literal>lib</literal> prefix is also omitted.</para>
287 <para>For use with GHCi, each library should have an
288 object file too. The name of the object file does
289 <emphasis>not</emphasis> have a <literal>lib</literal>
290 prefix, and has the normal object suffix for your
293 <para>For example, if we specify a Haskell library as
294 <filename>HSfoo</filename> in the package spec, then the
295 various flavours of library that GHC actually uses will be
299 <term><filename>libHSfoo.a</filename></term>
301 <para>The name of the library on Unix
306 <term><filename>HSfoo.dll</filename></term>
308 <para>The name of the dynamic library on Windows
313 <term><filename>HSfoo.o</filename></term>
314 <term><filename>HSfoo.obj</filename></term>
316 <para>The object version of the library used by
326 <term><literal>extra_libraries</literal></term>
327 <indexterm><primary><literal>extra_libraries</literal></primary>
328 <secondary>package specification</secondary></indexterm>
330 <para>A list of extra libraries for this package. The
331 difference between <literal>hs_libraries</literal> and
332 <literal>extra_libraries</literal> is that
333 <literal>hs_libraries</literal> normally have several
334 versions, to support profiling, parallel and other build
335 options. The various versions are given different
336 suffixes to distinguish them, for example the profiling
337 version of the standard prelude library is named
338 <filename>libHSstd_p.a</filename>, with the
339 <literal>_p</literal> indicating that this is a profiling
340 version. The suffix is added automatically by GHC for
341 <literal>hs_libraries</literal> only, no suffix is added
343 <literal>extra_libraries</literal>.</para>
345 <para>Also, <literal>extra_libraries</literal> are placed
346 on the linker command line after the
347 <literal>hs_libraries</literal> for the same package. If
348 your package has dependencies in the other direction (i.e.
349 <literal>extra_libraries</literal> depends on
350 <literal>hs_libraries</literal>), and the libraries are
351 static, you might need to make two separate
357 <term><literal>include_dirs</literal></term>
358 <indexterm><primary><literal>include_dirs</literal></primary>
359 <secondary>package specification</secondary></indexterm>
361 <para>A list of directories containing C includes for this
362 package (maybe the empty list).</para>
367 <term><literal>c_includes</literal></term>
368 <indexterm><primary><literal>c_includes</literal></primary>
369 <secondary>package specification</secondary></indexterm>
371 <para>A list of files to include for via-C compilations
372 using this package. Typically this include file will
373 contain function prototypes for any C functions used in
374 the package, in case they end up being called as a result
375 of Haskell functions from the package being
381 <term><literal>package_deps</literal></term>
382 <indexterm><primary><literal>package_deps</literal></primary>
383 <secondary>package specification</secondary></indexterm>
385 <para>A list of packages which this package depends
391 <term><literal>extra_ghc_opts</literal></term>
392 <indexterm><primary><literal>extra_ghc_opts</literal></primary>
393 <secondary>package specification</secondary></indexterm>
395 <para>Extra arguments to be added to the GHC command line
396 when this package is being used.</para>
401 <term><literal>extra_cc_opts</literal></term>
402 <indexterm><primary><literal>extra_cc_opts</literal></primary>
403 <secondary>package specification</secondary></indexterm>
405 <para>Extra arguments to be added to the gcc command line
406 when this package is being used (only for via-C
407 compilations).</para>
412 <term><literal>extra_ld_opts</literal></term>
413 <indexterm><primary><literal>extra_ld_opts</literal></primary>
414 <secondary>package specification</secondary></indexterm>
416 <para>Extra arguments to be added to the gcc command line
417 (for linking) when this package is being used.</para>
422 <para>For examples of more package specifications, take a look
423 at the <literal>package.conf</literal> in your GHC
429 ;;; Local Variables: ***
431 ;;; sgml-parent-document: ("using.sgml" "book" "chapter") ***