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.</para>
20 <sect2 id="listing-packages">
21 <title>Listing the available packages</title>
22 <indexterm><primary>packages</primary>
23 <secondary>listing</secondary></indexterm>
25 <para>To see what packages are currently installed, use the
26 <literal>--list-packages</literal> option:</para>
27 <indexterm><primary><literal>--list-packages</literal></primary>
32 gmp, rts, std, lang, concurrent, data, net, posix, text, util
35 <para>Note that your GHC installation might have a slightly
36 different set of packages installed.</para>
38 <para>The <literal>gmp</literal> and <literal>rts</literal>
39 packages are always present, and represent the multi-precision
40 integer and runtime system libraries respectively. The
41 <literal>std</literal> package contains the Haskell prelude.
42 The rest of the packages are optional libraries.</para>
46 <sect2 id="using-packages">
47 <title>Using a package</title>
48 <indexterm><primary>packages</primary>
49 <secondary>using</secondary></indexterm>
51 <para>To use a package, add the <literal>-package</literal> flag
52 to the command line:</para>
56 <term><option>-package <lib></option></term>
57 <indexterm><primary>-package <lib> option</primary></indexterm>
59 <para>This option brings into scope all the modules from
60 package <literal><lib></literal> (they still have to
61 be imported in your Haskell source, however). It also
62 causes the relevant libraries to be linked when linking is
68 <para>Some packages depend on other packages, for example the
69 <literal>text</literal> package makes use of some of the modules
70 in the <literal>lang</literal> package. The package system
71 takes care of all these dependencies, so that when you say
72 <literal>-package text</literal> on the command line, you
73 automatically get <literal>-package lang</literal> too.</para>
76 <sect2 id="building-packages">
77 <title>Building a package from Haskell source</title>
78 <indexterm><primary>packages</primary>
79 <secondary>building</secondary></indexterm>
81 <para>It takes some special considerations to build a new
86 <para>A package may contain several Haskell modules. A
87 package may span many directories, or many packages may
88 exist in a single directory. Packages may not be mutually
93 <para>A package has a name
94 (e.g. <filename>std</filename>)</para>
98 <para>The Haskell code in a package may be built into one or
99 more Unix libraries (e.g. <filename>libHSfoo.a</filename>),
100 or a single DLL on Windows
101 (e.g. <filename>HSfoo.dll</filename>). The restriction to a
102 single DLL on Windows is that the package system is used to
103 tell the compiler when it should make an inter-DLL call
104 rather than an intra-DLL call (inter-DLL calls require an
105 extra indirection).</para>
109 <para>GHC does not maintain detailed cross-package
110 dependency information. It does remember which modules in
111 other packages the current module depends on, but not which
112 things within those imported things.</para>
116 <para>To compile a module which is to be part of a new package,
117 use the <literal>-package-name</literal> option:</para>
121 <term><option>-package-name <foo></option></term>
122 <indexterm><primary><literal>-package-name</literal></primary>
123 <secondary>option</secondary></indexterm>
125 <para>This option is added to the command line when
126 compiling a module that is destined to be part of package
127 <literal>foo</literal>. If this flag is omitted then the
128 default package <literal>Main</literal> is assumed.</para>
133 <para>Failure to use the <literal>-package-name</literal> option
134 when compiling a package will result in disaster on Windows, but
135 is relatively harmless on Unix at the moment (it will just cause
136 a few extra dependencies in some interface files). However,
137 bear in mind that we might add support for Unix shared libraries
138 at some point in the future.</para>
140 <para>It is worth noting that on Windows, because each package
141 is built as a DLL, and a reference to a DLL costs an extra
142 indirection, intra-package references are cheaper than
143 inter-package references. Of course, this applies to the
144 <filename>Main</filename> package as well.</para>
147 <sect2 id="package-management">
148 <title>Package management</title>
149 <indexterm><primary>packages</primary>
150 <secondary>management</secondary></indexterm>
152 <para>GHC uses a package configuration file, called
153 <literal>packages.conf</literal>, which can be found in your GHC
154 install directory. This file isn't intended to be edited
155 directly, instead GHC provides options for adding & removing
160 <term><option>--add-package</option></term>
161 <indexterm><primary><literal>--add-package</literal></primary>
162 <secondary>option</secondary></indexterm>
164 <para>Reads a package specification (see below) on stdin,
165 and adds it to the database of installed packages. The
166 package specification must be a package that isn't already
172 <term><option>--delete-package <foo></option></term>
173 <indexterm><primary><literal>--delete-package</literal></primary>
174 <secondary>option</secondary></indexterm>
176 <para>Removes the specified package from the installed
177 configuration.</para>
182 <para>In both cases, the old package configuration file is saved
183 in <literal>packages.conf.old</literal> in your GHC install
184 directory, so in an emergency you can always copy this file into
185 <literal>package.conf</literal> to restore the old
188 <para>A package specification looks like this:</para>
193 import_dirs = ["/usr/local/lib/imports/mypkg"],
194 library_dirs = ["/usr/local/lib"],
195 hs_libraries = ["HSmypkg" ],
196 extra_libraries = ["HSmypkg_cbits"],
198 c_includes = ["HsMyPkg.h"],
199 package_deps = ["text", "data"],
202 extra_ld_opts = ["-lmy_clib"]
206 <para>Components of a package specification may be specified in
207 any order, and are:</para>
211 <term><literal>name</literal></term>
212 <indexterm><primary><literal>name</literal></primary>
213 <secondary>package specification</secondary></indexterm>
215 <para>The package's name, for use with
216 the <literal>-package</literal> flag and as listed in the
217 <literal>--list-packages</literal> list.
223 <term><literal>import_dirs</literal></term>
224 <indexterm><primary><literal>import_dirs</literal></primary>
225 <secondary>package specification</secondary></indexterm>
227 <para>A list of directories containing interface files
228 (<literal>.hi</literal> files) for this package.</para>
233 <term><literal>library_dirs</literal></term>
234 <indexterm><primary><literal>library_dirs</literal></primary>
235 <secondary>package specification</secondary></indexterm>
237 <para>A list of directories containing libraries for this
243 <term><literal>hs_libraries</literal></term>
244 <indexterm><primary><literal>hs_libraries</literal></primary>
245 <secondary>package specification</secondary></indexterm>
247 <para>A list of libraries containing Haskell code for this
248 package, with the <literal>.a</literal> or
249 <literal>.dll</literal> suffix omitted. On Unix, the
250 <literal>lib</literal> prefix is also omitted.</para>
255 <term><literal>extra_libraries</literal></term>
256 <indexterm><primary><literal>extra_libraries</literal></primary>
257 <secondary>package specification</secondary></indexterm>
259 <para>A list of extra libraries for this package. The
260 difference between <literal>hs_libraries</literal> and
261 <literal>extra_libraries</literal> is that
262 <literal>hs_libraries</literal> normally have several
263 versions, to support profiling, parallel and other build
264 options. The various versions are given different
265 suffixes to distinguish them, for example the profiling
266 version of the standard prelude library is named
267 <filename>libHSstd_p.a</filename>, with the
268 <literal>_p</literal> indicating that this is a profiling
269 version. The suffix is added automatically by GHC for
270 <literal>hs_libraries</literal> only, no suffix is added
272 <literal>extra_libraries</literal>.</para>
274 <para>Also, <literal>extra_libraries</literal> are placed
275 on the linker command line before the
276 <literal>hs_libraries</literal> for the same package. If
277 your package has dependencies in the other direction, you
278 might need to make two separate packages.</para>
283 <term><literal>include_dirs</literal></term>
284 <indexterm><primary><literal>include_dirs</literal></primary>
285 <secondary>package specification</secondary></indexterm>
287 <para>A list of directories containing C includes for this
288 package (maybe the empty list).</para>
293 <term><literal>c_includes</literal></term>
294 <indexterm><primary><literal>c_includes</literal></primary>
295 <secondary>package specification</secondary></indexterm>
297 <para>A list of files to include for via-C compilations
298 using this package. Typically this include file will
299 contain function prototypes for any C functions used in
300 the package, in case they end up being called as a result
301 of Haskell functions from the package being
307 <term><literal>package_deps</literal></term>
308 <indexterm><primary><literal>package_deps</literal></primary>
309 <secondary>package specification</secondary></indexterm>
311 <para>A list of packages which this package depends
317 <term><literal>extra_ghc_opts</literal></term>
318 <indexterm><primary><literal>extra_ghc_opts</literal></primary>
319 <secondary>package specification</secondary></indexterm>
321 <para>Extra arguments to be added to the GHC command line
322 when this package is being used.</para>
327 <term><literal>extra_cc_opts</literal></term>
328 <indexterm><primary><literal>extra_cc_opts</literal></primary>
329 <secondary>package specification</secondary></indexterm>
331 <para>Extra arguments to be added to the gcc command line
332 when this package is being used (only for via-C
333 compilations).</para>
338 <term><literal>extra_ld_opts</literal></term>
339 <indexterm><primary><literal>extra_ld_opts</literal></primary>
340 <secondary>package specification</secondary></indexterm>
342 <para>Extra arguments to be added to the gcc command line
343 (for linking) when this package is being used.</para>
348 <para>For examples of more package specifications, take a look
349 at the <literal>package.conf</literal> in your GHC
355 ;;; Local Variables: ***
357 ;;; sgml-parent-document: ("using.sgml" "book" "chapter") ***