Package keys (for linking/type equality) separated from package IDs.
[ghc.git] / docs / users_guide / packages.xml
1 <?xml version="1.0" encoding="iso-8859-1"?>
2 <sect1 id="packages">
3 <title>
4 Packages
5 </title>
6 <indexterm><primary>packages</primary></indexterm>
7
8 <para>A package is a library of Haskell modules known to the
9 compiler. GHC comes with several packages: see the accompanying
10 <ulink url="../libraries/index.html">library
11 documentation</ulink>. More packages to install can be obtained
12 from <ulink
13 url="http://hackage.haskell.org/packages/hackage.html">HackageDB</ulink>.</para>
14
15 <para>Using a package couldn't be simpler: if you're using
16 <option>--make</option> or GHCi, then most of the installed packages will be
17 automatically available to your program without any further options. The
18 exceptions to this rule are covered below in <xref
19 linkend="using-packages" />.</para>
20
21 <para>Building your own packages is also quite straightforward: we provide
22 the <ulink url="http://www.haskell.org/cabal/">Cabal</ulink> infrastructure which
23 automates the process of configuring, building, installing and distributing
24 a package. All you need to do is write a simple configuration file, put a
25 few files in the right places, and you have a package. See the
26 <ulink url="../Cabal/index.html">Cabal documentation</ulink>
27 for details, and also the Cabal libraries (<ulink url="&libraryCabalLocation;/Distribution-Simple.html">Distribution.Simple</ulink>,
28 for example).</para>
29
30 <sect2 id="using-packages">
31 <title>Using Packages
32 </title>
33 <indexterm><primary>packages</primary>
34 <secondary>using</secondary></indexterm>
35
36 <para>GHC only knows about packages that are
37 <emphasis>installed</emphasis>. To see which packages are installed, use
38 the <literal>ghc-pkg list</literal> command:</para>
39
40 <screen>
41 $ ghc-pkg list
42 /usr/lib/ghc-6.12.1/package.conf.d:
43 Cabal-1.7.4
44 array-0.2.0.1
45 base-3.0.3.0
46 base-4.2.0.0
47 bin-package-db-0.0.0.0
48 binary-0.5.0.1
49 bytestring-0.9.1.4
50 containers-0.2.0.1
51 directory-1.0.0.2
52 (dph-base-0.4.0)
53 (dph-par-0.4.0)
54 (dph-prim-interface-0.4.0)
55 (dph-prim-par-0.4.0)
56 (dph-prim-seq-0.4.0)
57 (dph-seq-0.4.0)
58 extensible-exceptions-0.1.1.0
59 ffi-1.0
60 filepath-1.1.0.1
61 (ghc-6.12.1)
62 ghc-prim-0.1.0.0
63 haskeline-0.6.2
64 haskell98-1.0.1.0
65 hpc-0.5.0.2
66 integer-gmp-0.1.0.0
67 mtl-1.1.0.2
68 old-locale-1.0.0.1
69 old-time-1.0.0.1
70 pretty-1.0.1.0
71 process-1.0.1.1
72 random-1.0.0.1
73 rts-1.0
74 syb-0.1.0.0
75 template-haskell-2.4.0.0
76 terminfo-0.3.1
77 time-1.1.4
78 unix-2.3.1.0
79 utf8-string-0.3.4
80 </screen>
81
82 <para>An installed package is either <emphasis>exposed</emphasis>
83 or <emphasis>hidden</emphasis> by default. Packages hidden by
84 default are listed in parentheses
85 (eg. <literal>(lang-1.0)</literal>), or possibly in blue if your
86 terminal supports colour, in the output of <literal>ghc-pkg
87 list</literal>. Command-line flags, described below, allow you
88 to expose a hidden package or hide an exposed one. Only modules
89 from exposed packages may be imported by your Haskell code; if
90 you try to import a module from a hidden package, GHC will emit
91 an error message.
92 </para>
93
94 <para>
95 Note: if you're using Cabal, then the exposed or hidden status
96 of a package is irrelevant: the available packages are instead
97 determined by the dependencies listed in
98 your <literal>.cabal</literal> specification. The
99 exposed/hidden status of packages is only relevant when
100 using <literal>ghc</literal> or <literal>ghci</literal>
101 directly.
102 </para>
103
104 <para>Similar to a package's hidden status is a package's trusted
105 status. A package can be either trusted or not trusted (distrusted).
106 By default packages are distrusted. This property of a package only
107 plays a role when compiling code using GHC's Safe Haskell feature
108 (see <xref linkend="safe-haskell"/>) with the
109 <option>-fpackage-trust</option> flag enabled.
110 </para>
111
112 <para>To see which modules are provided by a package use the
113 <literal>ghc-pkg</literal> command (see <xref linkend="package-management"/>):</para>
114
115 <screen>
116 $ ghc-pkg field network exposed-modules
117 exposed-modules: Network.BSD,
118 Network.CGI,
119 Network.Socket,
120 Network.URI,
121 Network
122 </screen>
123
124 <para>The GHC command line options that control packages are:</para>
125
126 <variablelist>
127 <varlistentry>
128 <term>
129 <option>-package <replaceable>P</replaceable></option>
130 <indexterm><primary><option>-package</option></primary></indexterm>
131 </term>
132 <listitem>
133 <para>This option causes the installed
134 package <replaceable>P</replaceable> to be exposed. The
135 package <replaceable>P</replaceable> can be specified in
136 full with its version number
137 (e.g. <literal>network-1.0</literal>) or the version
138 number can be omitted if there is only one version of the
139 package installed. If there are multiple versions
140 of <replaceable>P</replaceable> installed, then all other
141 versions will become hidden.</para>
142
143 <para>The <option>-package <replaceable>P</replaceable></option>
144 option also causes package <replaceable>P</replaceable> to
145 be linked into the resulting executable or shared
146 object. Whether a packages' library is linked statically
147 or dynamically is controlled by the flag
148 pair <option>-static</option>/<option>-dynamic</option>.</para>
149
150 <para>In <option>--make</option> mode
151 and <option>--interactive</option> mode (see
152 <xref linkend="modes" />), the compiler normally
153 determines which packages are required by the current
154 Haskell modules, and links only those. In batch mode
155 however, the dependency information isn't available, and
156 explicit
157 <option>-package</option> options must be given when linking. The one other time you might need to use
158 <option>-package</option> to force linking a package is
159 when the package does not contain any Haskell modules (it
160 might contain a C library only, for example). In that
161 case, GHC will never discover a dependency on it, so it
162 has to be mentioned explicitly.</para>
163
164 <para>For example, to link a program consisting of objects
165 <filename>Foo.o</filename> and <filename>Main.o</filename>, where
166 we made use of the <literal>network</literal> package, we need to
167 give GHC the <literal>-package</literal> flag thus:
168
169 <screen>$ ghc -o myprog Foo.o Main.o -package network</screen>
170
171 The same flag is necessary even if we compiled the modules from
172 source, because GHC still reckons it's in batch mode:
173
174 <screen>$ ghc -o myprog Foo.hs Main.hs -package network</screen></para>
175 </listitem>
176 </varlistentry>
177
178 <varlistentry>
179 <term>
180 <option>-package-id <replaceable>P</replaceable></option>
181 <indexterm><primary><option>-package-id</option></primary></indexterm>
182 </term>
183 <listitem>
184 <para>
185 Exposes a package like <option>-package</option>, but the
186 package is named by its installed package ID rather than by name. This is a
187 more robust way to name packages, and can be used to
188 select packages that would otherwise be shadowed. Cabal
189 passes <option>-package-id</option> flags to GHC.
190 </para>
191 </listitem>
192 </varlistentry>
193
194 <varlistentry>
195 <term><option>-hide-all-packages</option>
196 <indexterm><primary><option>-hide-package</option></primary>
197 </indexterm></term>
198 <listitem>
199 <para>Ignore the exposed flag on installed packages, and hide them
200 all by default. If you use
201 this flag, then any packages you require (including
202 <literal>base</literal>) need to be explicitly exposed using
203 <option>-package</option> options.</para>
204
205 <para>This is a good way to insulate your program from
206 differences in the globally exposed packages, and being
207 explicit about package dependencies is a Good Thing.
208 Cabal always passes the
209 <option>-hide-all-packages</option> flag to GHC, for
210 exactly this reason.</para>
211 </listitem>
212 </varlistentry>
213
214 <varlistentry>
215 <term><option>-hide-package</option> <replaceable>P</replaceable>
216 <indexterm><primary><option>-hide-package</option></primary>
217 </indexterm></term>
218 <listitem>
219 <para>This option does the opposite of <option>-package</option>: it
220 causes the specified package to be <firstterm>hidden</firstterm>,
221 which means that none of its modules will be available for import
222 by Haskell <literal>import</literal> directives.</para>
223
224 <para>Note that the package might still end up being linked into the
225 final program, if it is a dependency (direct or indirect) of
226 another exposed package.</para>
227 </listitem>
228 </varlistentry>
229
230 <varlistentry>
231 <term><option>-ignore-package</option> <replaceable>P</replaceable>
232 <indexterm><primary><option>-ignore-package</option></primary>
233 </indexterm></term>
234 <listitem>
235 <para>Causes the compiler to behave as if package
236 <replaceable>P</replaceable>, and any packages that depend on
237 <literal>P</literal>, are not installed at all.</para>
238
239 <para>Saying <literal>-ignore-package P</literal> is the same as
240 giving <literal>-hide-package</literal> flags for
241 <literal>P</literal> and all the packages that depend on
242 <literal>P</literal>. Sometimes we don't know ahead of time which
243 packages will be installed that depend on <literal>P</literal>,
244 which is when the <literal>-ignore-package</literal> flag can be
245 useful.</para>
246 </listitem>
247 </varlistentry>
248
249 <varlistentry>
250 <term><option>-no-auto-link-packages</option>
251 <indexterm><primary><option>-no-auto-link-packages</option></primary>
252 </indexterm></term>
253 <listitem>
254 <para>By default, GHC will automatically link in the
255 <literal>base</literal> and <literal>rts</literal> packages.
256 This flag disables that behaviour.</para>
257 </listitem>
258 </varlistentry>
259
260 <varlistentry>
261 <term><option>-this-package-key</option> <replaceable>foo</replaceable>
262 <indexterm><primary><option>-this-package-key</option></primary>
263 </indexterm></term>
264 <listitem>
265 <para>Tells GHC the the module being compiled forms part of
266 package key <replaceable>foo</replaceable>; internally, these
267 keys are used to determine type equality and linker symbols.
268 If this flag is omitted (a very common case) then the
269 default package <literal>main</literal> is assumed.</para>
270 </listitem>
271 </varlistentry>
272
273 <varlistentry>
274 <term><option>-trust</option> <replaceable>P</replaceable>
275 <indexterm><primary><option>-trust</option></primary>
276 </indexterm></term>
277 <listitem>
278 <para>This option causes the install package <replaceable>P
279 </replaceable> to be both exposed and trusted by GHC. This
280 command functions in the in a very similar way to the <option>
281 -package</option> command but in addition sets the selected
282 packaged to be trusted by GHC, regardless of the contents of
283 the package database. (see <xref linkend="safe-haskell"/>).
284 </para>
285 </listitem>
286 </varlistentry>
287
288 <varlistentry>
289 <term><option>-distrust</option> <replaceable>P</replaceable>
290 <indexterm><primary><option>-distrust</option></primary>
291 </indexterm></term>
292 <listitem>
293 <para>This option causes the install package <replaceable>P
294 </replaceable> to be both exposed and distrusted by GHC. This
295 command functions in the in a very similar way to the <option>
296 -package</option> command but in addition sets the selected
297 packaged to be distrusted by GHC, regardless of the contents of
298 the package database. (see <xref linkend="safe-haskell"/>).
299 </para>
300 </listitem>
301 </varlistentry>
302
303 <varlistentry>
304 <term><option>-distrust-all</option>
305 <indexterm><primary><option>-distrust-all</option></primary>
306 </indexterm></term>
307 <listitem>
308 <para>Ignore the trusted flag on installed packages, and distrust
309 them by default. If you use this flag and Safe Haskell then any
310 packages you require to be trusted (including <literal>base
311 </literal>) need to be explicitly trusted using <option>-trust
312 </option> options. This option does not change the exposed/hidden
313 status of a package, so it isn't equivalent to applying <option>
314 -distrust</option> to all packages on the system. (see
315 <xref linkend="safe-haskell"/>).
316 </para>
317 </listitem>
318 </varlistentry>
319 </variablelist>
320 </sect2>
321
322 <sect2 id="package-main">
323 <title>The main package</title>
324
325 <para>Every complete Haskell program must define <literal>main</literal> in
326 module <literal>Main</literal>
327 in package <literal>main</literal>. (Omitting the <option>-this-package-key</option> flag compiles
328 code for package <literal>main</literal>.) Failure to do so leads to a somewhat obscure
329 link-time error of the form:
330 <programlisting>
331 /usr/bin/ld: Undefined symbols:
332 _ZCMain_main_closure
333 </programlisting>
334 </para>
335
336 </sect2>
337
338 <sect2 id="package-overlaps">
339 <title>Consequences of packages for the Haskell language</title>
340
341 <para>It is possible that by using packages you might end up with
342 a program that contains two modules with the same name: perhaps
343 you used a package P that has a <emphasis>hidden</emphasis> module
344 M, and there is also a module M in your program. Or perhaps the
345 dependencies of packages that you used contain some overlapping
346 modules. Perhaps the program even contains multiple versions of a
347 certain package, due to dependencies from other packages.</para>
348
349 <para>None of these scenarios gives rise to an error on its
350 own<footnote><para>it used to in GHC 6.4, but not since
351 6.6</para></footnote>, but they may have some interesting
352 consequences. For instance, if you have a type
353 <literal>M.T</literal> from version 1 of package
354 <literal>P</literal>, then this is <emphasis>not</emphasis> the
355 same as the type <literal>M.T</literal> from version 2 of package
356 <literal>P</literal>, and GHC will report an error if you try to
357 use one where the other is expected.</para>
358
359 <para>Formally speaking, in Haskell 98, an entity (function, type
360 or class) in a program is uniquely identified by the pair of the
361 module name in which it is defined and its name. In GHC, an
362 entity is uniquely defined by a triple: package, module, and
363 name.</para>
364 </sect2>
365
366 <sect2 id="package-databases">
367 <title>Package Databases</title>
368
369 <para>
370 A package database is where the details about installed packages
371 are stored. It is a directory, usually
372 called <literal>package.conf.d</literal>, that contains a file
373 for each package, together with a binary cache of the package
374 data in the file <literal>package.cache</literal>. Normally
375 you won't need to look at or modify the contents of a package
376 database directly; all management of package databases can be
377 done through the <literal>ghc-pkg</literal> tool (see
378 <xref linkend="package-management" />).
379 </para>
380
381 <para>
382 GHC knows about two package databases in particular:
383 </para>
384
385 <itemizedlist>
386 <listitem>
387 <para>The global package database, which comes with your GHC
388 installation,
389 e.g. <filename>/usr/lib/ghc-6.12.1/package.conf.d</filename>.</para>
390 </listitem>
391 <listitem>
392 <para>A package database private to each user. On Unix
393 systems this will be
394 <filename>$HOME/.ghc/<replaceable>arch</replaceable>-<replaceable>os</replaceable>-<replaceable>version</replaceable>/package.conf.d</filename>, and on
395 Windows it will be something like
396 <filename>C:\Documents&nbsp;And&nbsp;Settings\<replaceable>user</replaceable>\ghc\package.conf.d</filename>.
397 The <literal>ghc-pkg</literal> tool knows where this file should be
398 located, and will create it if it doesn't exist (see <xref linkend="package-management" />).</para>
399 </listitem>
400 </itemizedlist>
401
402 <para>When GHC starts up, it reads the contents of these two package
403 databases, and builds up a list of the packages it knows about. You can
404 see GHC's package table by running GHC with the <option>-v</option>
405 flag.</para>
406
407 <para>Package databases may overlap, and they are arranged in a stack
408 structure. Packages closer to the top of the stack will override
409 (<emphasis>shadow</emphasis>) those below them. By default, the stack
410 contains just the global and the user's package databases, in that
411 order.</para>
412
413 <para>You can control GHC's package database stack using the following
414 options:</para>
415
416 <variablelist>
417 <varlistentry>
418 <term>
419 <option>-package-db <replaceable>file</replaceable></option>
420 <indexterm><primary><option>-package-db</option></primary></indexterm>
421 </term>
422 <listitem>
423 <para>Add the package database <replaceable>file</replaceable> on top
424 of the current stack. Packages in additional databases read this
425 way will override those in the initial stack and those in
426 previously specified databases.</para>
427 </listitem>
428 </varlistentry>
429
430 <varlistentry>
431 <term><option>-no-global-package-db</option>
432 <indexterm><primary><option>-no-global-package-db</option></primary>
433 </indexterm>
434 </term>
435 <listitem>
436 <para>Remove the global package database from the package database
437 stack.</para>
438 </listitem>
439 </varlistentry>
440
441 <varlistentry>
442 <term><option>-no-user-package-db</option>
443 <indexterm><primary><option>-no-user-package-db</option></primary>
444 </indexterm>
445 </term>
446 <listitem>
447 <para>Prevent loading of the user's local package database in the
448 initial stack.</para>
449 </listitem>
450 </varlistentry>
451
452 <varlistentry>
453 <term><option>-clear-package-db</option>
454 <indexterm><primary><option>-clear-package-db</option></primary>
455 </indexterm>
456 </term>
457 <listitem>
458 <para>Reset the current package database stack. This option removes
459 every previously specified package database (including those
460 read from the <literal>GHC_PACKAGE_PATH</literal> environment
461 variable) from the package database stack.</para>
462 </listitem>
463 </varlistentry>
464
465 <varlistentry>
466 <term><option>-global-package-db</option>
467 <indexterm><primary><option>-global-package-db</option></primary>
468 </indexterm>
469 </term>
470 <listitem>
471 <para>Add the global package database on top of the current stack.
472 This option can be used after
473 <literal>-no-global-package-db</literal> to specify the position in
474 the stack where the global package database should be
475 loaded.</para>
476 </listitem>
477 </varlistentry>
478
479 <varlistentry>
480 <term><option>-user-package-db</option>
481 <indexterm><primary><option>-user-package-db</option></primary>
482 </indexterm>
483 </term>
484 <listitem>
485 <para>Add the user's package database on top of the current stack.
486 This option can be used after
487 <literal>-no-user-package-db</literal> to specify the position in
488 the stack where the user's package database should be
489 loaded.</para>
490 </listitem>
491 </varlistentry>
492 </variablelist>
493
494 <sect3 id="ghc-package-path">
495 <title>The <literal>GHC_PACKAGE_PATH</literal> environment variable</title>
496 <indexterm><primary>Environment variable</primary><secondary><literal>GHC_PACKAGE_PATH</literal></secondary>
497 </indexterm>
498 <indexterm><primary><literal>GHC_PACKAGE_PATH</literal></primary></indexterm>
499 <para>The <literal>GHC_PACKAGE_PATH</literal> environment variable may be
500 set to a <literal>:</literal>-separated (<literal>;</literal>-separated
501 on Windows) list of files containing package databases. This list of
502 package databases is used by GHC and ghc-pkg, with earlier databases in
503 the list overriding later ones. This order was chosen to match the
504 behaviour of the <literal>PATH</literal> environment variable; think of
505 it as a list of package databases that are searched left-to-right for
506 packages.</para>
507
508 <para>If <literal>GHC_PACKAGE_PATH</literal> ends in a separator, then
509 the default package database stack (i.e. the user and global
510 package databases, in that order) is appended. For example, to augment
511 the usual set of packages with a database of your own, you could say
512 (on Unix):
513
514 <screen> $ export GHC_PACKAGE_PATH=$HOME/.my-ghc-packages.conf:</screen>
515
516 (use <literal>;</literal> instead of <literal>:</literal> on
517 Windows).</para>
518
519 <para>To check whether your <literal>GHC_PACKAGE_PATH</literal> setting
520 is doing the right thing, <literal>ghc-pkg list</literal> will list all
521 the databases in use, in the reverse order they are searched.</para>
522
523 </sect3>
524 </sect2>
525
526 <sect2 id="package-ids">
527 <title>Installed package IDs, dependencies, and broken packages</title>
528
529 <para>Each installed package has a unique identifier (the
530 &ldquo;installed package ID&rdquo;), which distinguishes it from all other
531 installed packages on the system. To see the installed package IDs
532 associated with each installed package, use <literal>ghc-pkg
533 list -v</literal>:</para>
534
535 <screen>
536 $ ghc-pkg list -v
537 using cache: /usr/lib/ghc-6.12.1/package.conf.d/package.cache
538 /usr/lib/ghc-6.12.1/package.conf.d
539 Cabal-1.7.4 (Cabal-1.7.4-48f5247e06853af93593883240e11238)
540 array-0.2.0.1 (array-0.2.0.1-9cbf76a576b6ee9c1f880cf171a0928d)
541 base-3.0.3.0 (base-3.0.3.0-6cbb157b9ae852096266e113b8fac4a2)
542 base-4.2.0.0 (base-4.2.0.0-247bb20cde37c3ef4093ee124e04bc1c)
543 ...
544 </screen>
545
546 <para>
547 The string in parentheses after the package name is the installed package
548 ID: it normally begins with the package name and version, and
549 ends in a hash string derived from the compiled package.
550 Dependencies between packages are expressed in terms of installed package
551 IDs, rather than just packages and versions. For example, take
552 a look at the dependencies of the <literal>haskell98</literal>
553 package:
554 </para>
555
556 <screen>
557 $ ghc-pkg field haskell98 depends
558 depends: array-0.2.0.1-9cbf76a576b6ee9c1f880cf171a0928d
559 base-4.2.0.0-247bb20cde37c3ef4093ee124e04bc1c
560 directory-1.0.0.2-f51711bc872c35ce4a453aa19c799008
561 old-locale-1.0.0.1-d17c9777c8ee53a0d459734e27f2b8e9
562 old-time-1.0.0.1-1c0d8ea38056e5087ef1e75cb0d139d1
563 process-1.0.1.1-d8fc6d3baf44678a29b9d59ca0ad5780
564 random-1.0.0.1-423d08c90f004795fd10e60384ce6561
565 </screen>
566
567 <para>
568 The purpose of the installed package ID is to detect problems caused by
569 re-installing a package without also recompiling the packages
570 that depend on it. Recompiling dependencies is necessary,
571 because the newly compiled package may have a different ABI
572 (Application Binary Interface) than the previous version, even
573 if both packages were built from the same source code using the
574 same compiler. With installed package IDs, a recompiled
575 package will have a different installed package ID from the previous
576 version, so packages that depended on the previous version are
577 now orphaned - one of their dependencies is not satisfied.
578 Packages that are broken in this way are shown in
579 the <literal>ghc-pkg list</literal> output either in red (if
580 possible) or otherwise surrounded by braces. In the following
581 example, we have recompiled and reinstalled
582 the <literal>filepath</literal> package, and this has caused
583 various dependencies including <literal>Cabal</literal> to
584 break:</para>
585
586 <screen>
587 $ ghc-pkg list
588 WARNING: there are broken packages. Run 'ghc-pkg check' for more details.
589 /usr/lib/ghc-6.12.1/package.conf.d:
590 {Cabal-1.7.4}
591 array-0.2.0.1
592 base-3.0.3.0
593 ... etc ...
594 </screen>
595
596 <para>
597 Additionally, <literal>ghc-pkg list</literal> reminds you that
598 there are broken packages and suggests <literal>ghc-pkg
599 check</literal>, which displays more information about the
600 nature of the failure:
601 </para>
602
603 <screen>
604 $ ghc-pkg check
605 There are problems in package ghc-6.12.1:
606 dependency "filepath-1.1.0.1-87511764eb0af2bce4db05e702750e63" doesn't exist
607 There are problems in package haskeline-0.6.2:
608 dependency "filepath-1.1.0.1-87511764eb0af2bce4db05e702750e63" doesn't exist
609 There are problems in package Cabal-1.7.4:
610 dependency "filepath-1.1.0.1-87511764eb0af2bce4db05e702750e63" doesn't exist
611 There are problems in package process-1.0.1.1:
612 dependency "filepath-1.1.0.1-87511764eb0af2bce4db05e702750e63" doesn't exist
613 There are problems in package directory-1.0.0.2:
614 dependency "filepath-1.1.0.1-87511764eb0af2bce4db05e702750e63" doesn't exist
615
616 The following packages are broken, either because they have a problem
617 listed above, or because they depend on a broken package.
618 ghc-6.12.1
619 haskeline-0.6.2
620 Cabal-1.7.4
621 process-1.0.1.1
622 directory-1.0.0.2
623 bin-package-db-0.0.0.0
624 hpc-0.5.0.2
625 haskell98-1.0.1.0
626 </screen>
627
628 <para>
629 To fix the problem, you need to recompile the broken packages
630 against the new dependencies. The easiest way to do this is to
631 use <literal>cabal-install</literal>, or download the packages
632 from <ulink
633 url="http://hackage.haskell.org/packages/hackage.html">HackageDB</ulink>
634 and build and install them as normal.</para>
635
636 <para>Be careful not to recompile any packages that GHC itself
637 depends on, as this may render the <literal>ghc</literal>
638 package itself broken, and <literal>ghc</literal> cannot be
639 simply recompiled. The only way to recover from this would be
640 to re-install GHC.</para>
641 </sect2>
642
643 <sect2 id="package-management">
644 <title>Package management (the <literal>ghc-pkg</literal> command)</title>
645 <indexterm><primary>packages</primary>
646 <secondary>management</secondary></indexterm>
647
648 <para>The <literal>ghc-pkg</literal> tool is for querying and
649 modifying package databases. To see what package databases are
650 in use, use
651 <literal>ghc-pkg&nbsp;list</literal>. The stack of databases that
652 <literal>ghc-pkg</literal> knows about can be modified using the
653 <literal>GHC_PACKAGE_PATH</literal> environment variable (see <xref
654 linkend="ghc-package-path" />, and using
655 <literal>--package-db</literal> options on the
656 <literal>ghc-pkg</literal> command line.</para>
657
658 <para>When asked to modify a database, <literal>ghc-pkg</literal> modifies
659 the global database by default. Specifying <option>--user</option>
660 causes it to act on the user database, or <option>--package-db</option>
661 can be used to act on another database entirely. When multiple of these
662 options are given, the rightmost one is used as the database to act
663 upon.</para>
664
665 <para>Commands that query the package database (list, latest,
666 describe, field, dot) operate on the list of databases specified by
667 the flags <option>--user</option>, <option>--global</option>, and
668 <option>--package-db</option>. If none of these flags are
669 given, the default is <option>--global</option>
670 <option>--user</option>.</para>
671
672 <para>If the environment variable <literal>GHC_PACKAGE_PATH</literal> is
673 set, and its value does not end in a separator (<literal>:</literal> on
674 Unix, <literal>;</literal> on Windows), then the last database is
675 considered to be the global database, and will be modified by default by
676 <literal>ghc-pkg</literal>. The intention here is that
677 <literal>GHC_PACKAGE_PATH</literal> can be used to create a virtual
678 package environment into which Cabal packages can be installed without
679 setting anything other than <literal>GHC_PACKAGE_PATH</literal>.</para>
680
681 <para>The <literal>ghc-pkg</literal> program may be run in the ways listed
682 below. Where a package name is required, the package can be named in
683 full including the version number
684 (e.g. <literal>network-1.0</literal>), or without the version number.
685 Naming a package without the version number matches all versions of the
686 package; the specified action will be applied to all the matching
687 packages. A package specifier that matches all version of the package
688 can also be written <replaceable>pkg</replaceable><literal>-*</literal>,
689 to make it clearer that multiple packages are being matched. To match
690 against the installed package ID instead of just package name and version,
691 pass the <option>--ipid</option> flag.</para>
692
693 <variablelist>
694 <varlistentry>
695 <term><literal>ghc-pkg init <replaceable>path</replaceable></literal></term>
696 <listitem>
697 <para>Creates a new, empty, package database
698 at <replaceable>path</replaceable>, which must not already
699 exist.</para>
700 </listitem>
701 </varlistentry>
702
703 <varlistentry>
704 <term><literal>ghc-pkg register <replaceable>file</replaceable></literal></term>
705 <listitem>
706 <para>Reads a package specification from
707 <replaceable>file</replaceable> (which may be &ldquo;<literal>-</literal>&rdquo;
708 to indicate standard input),
709 and adds it to the database of installed packages. The syntax of
710 <replaceable>file</replaceable> is given in <xref
711 linkend="installed-pkg-info" />.</para>
712
713 <para>The package specification must be a package that isn't already
714 installed.</para>
715 </listitem>
716 </varlistentry>
717
718 <varlistentry>
719 <term><literal>ghc-pkg update <replaceable>file</replaceable></literal></term>
720 <listitem>
721 <para>The same as <literal>register</literal>, except that if a
722 package of the same name is already installed, it is
723 replaced by the new one.</para>
724 </listitem>
725 </varlistentry>
726
727 <varlistentry>
728 <term><literal>ghc-pkg unregister <replaceable>P</replaceable></literal></term>
729 <listitem>
730 <para>Remove the specified package from the database.</para>
731 </listitem>
732 </varlistentry>
733
734 <varlistentry>
735 <term><literal>ghc-pkg check</literal></term>
736 <listitem>
737 <para>Check consistency of dependencies in the package
738 database, and report packages that have missing
739 dependencies.</para>
740 </listitem>
741 </varlistentry>
742
743 <varlistentry>
744 <term><literal>ghc-pkg expose <replaceable>P</replaceable></literal></term>
745 <listitem>
746 <para>Sets the <literal>exposed</literal> flag for package
747 <replaceable>P</replaceable> to <literal>True</literal>.</para>
748 </listitem>
749 </varlistentry>
750
751 <varlistentry>
752 <term><literal>ghc-pkg hide <replaceable>P</replaceable></literal></term>
753 <listitem>
754 <para>Sets the <literal>exposed</literal> flag for package
755 <replaceable>P</replaceable> to <literal>False</literal>.</para>
756 </listitem>
757 </varlistentry>
758
759 <varlistentry>
760 <term><literal>ghc-pkg trust <replaceable>P</replaceable></literal></term>
761 <listitem>
762 <para>Sets the <literal>trusted</literal> flag for package
763 <replaceable>P</replaceable> to <literal>True</literal>.</para>
764 </listitem>
765 </varlistentry>
766
767 <varlistentry>
768 <term><literal>ghc-pkg distrust <replaceable>P</replaceable></literal></term>
769 <listitem>
770 <para>Sets the <literal>trusted</literal> flag for package
771 <replaceable>P</replaceable> to <literal>False</literal>.</para>
772 </listitem>
773 </varlistentry>
774
775 <varlistentry>
776 <term><literal>ghc-pkg list [<replaceable>P</replaceable>] [<option>--simple-output</option>]</literal></term>
777 <listitem>
778 <para>This option displays the currently installed
779 packages, for each of the databases known to
780 <literal>ghc-pkg</literal>. That includes the global database, the
781 user's local database, and any further files specified using the
782 <option>-f</option> option on the command line.</para>
783
784 <para>Hidden packages (those for which the <literal>exposed</literal>
785 flag is <literal>False</literal>) are shown in parentheses in the
786 list of packages.</para>
787
788 <para>If an optional package identifier <replaceable>P</replaceable>
789 is given, then only packages matching that identifier are
790 shown.</para>
791
792 <para>If the option <option>--simple-output</option> is given, then
793 the packages are listed on a single line separated by spaces, and
794 the database names are not included. This is intended to make it
795 easier to parse the output of <literal>ghc-pkg list</literal> using
796 a script.</para>
797 </listitem>
798 </varlistentry>
799
800 <varlistentry>
801 <term><literal>ghc-pkg find-module <replaceable>M</replaceable> [<option>--simple-output</option>]</literal></term>
802 <listitem>
803 <para>This option lists registered packages exposing module
804 <replaceable>M</replaceable>. Examples:</para>
805 <screen>
806 $ ghc-pkg find-module Var
807 c:/fptools/validate/ghc/driver/package.conf.inplace:
808 (ghc-6.9.20080428)
809
810 $ ghc-pkg find-module Data.Sequence
811 c:/fptools/validate/ghc/driver/package.conf.inplace:
812 containers-0.1
813 </screen>
814 <para>Otherwise, it behaves like <literal>ghc-pkg list</literal>,
815 including options.</para>
816 </listitem>
817 </varlistentry>
818
819
820 <varlistentry>
821 <term><literal>ghc-pkg latest <replaceable>P</replaceable></literal></term>
822 <listitem>
823 <para>Prints the latest available version of package
824 <replaceable>P</replaceable>.</para>
825 </listitem>
826 </varlistentry>
827
828 <varlistentry>
829 <term><literal>ghc-pkg describe <replaceable>P</replaceable></literal></term>
830 <listitem>
831 <para>Emit the full description of the specified package. The
832 description is in the form of an
833 <literal>InstalledPackageInfo</literal>, the same as the input file
834 format for <literal>ghc-pkg register</literal>. See <xref
835 linkend="installed-pkg-info" /> for details.</para>
836
837 <para>If the pattern matches multiple packages, the
838 description for each package is emitted, separated by the
839 string <literal>---</literal> on a line by itself.</para>
840 </listitem>
841 </varlistentry>
842
843 <varlistentry>
844 <term><literal>ghc-pkg field <replaceable>P</replaceable> <replaceable>field</replaceable>[,<replaceable>field</replaceable>]*</literal></term>
845 <listitem>
846 <para>Show just a single field of the installed package description
847 for <literal>P</literal>. Multiple fields can be selected by separating
848 them with commas</para>
849 </listitem>
850 </varlistentry>
851
852 <varlistentry>
853 <term><literal>ghc-pkg dot</literal></term>
854 <listitem>
855 <para>
856 Generate a graph of the package dependencies in a form
857 suitable for input for the <ulink url="http://www.graphviz.org/">graphviz</ulink> tools. For example,
858 to generate a PDF of the dependency graph:</para>
859 <screen>
860 ghc-pkg dot | tred | dot -Tpdf >pkgs.pdf
861 </screen>
862 </listitem>
863 </varlistentry>
864
865 <varlistentry>
866 <term><literal>ghc-pkg dump</literal></term>
867 <listitem>
868 <para>Emit the full description of every package, in the
869 form of an <literal>InstalledPackageInfo</literal>.
870 Multiple package descriptions are separated by the
871 string <literal>---</literal> on a line by itself.</para>
872
873 <para>This is almost the same as <literal>ghc-pkg describe '*'</literal>, except that <literal>ghc-pkg dump</literal>
874 is intended for use by tools that parse the results, so
875 for example where <literal>ghc-pkg describe '*'</literal>
876 will emit an error if it can't find any packages that
877 match the pattern, <literal>ghc-pkg dump</literal> will
878 simply emit nothing.</para>
879 </listitem>
880 </varlistentry>
881
882 <varlistentry>
883 <term><literal>ghc-pkg recache</literal></term>
884 <listitem>
885 <para>
886 Re-creates the binary cache
887 file <filename>package.cache</filename> for the selected
888 database. This may be necessary if the cache has somehow
889 become out-of-sync with the contents of the database
890 (<literal>ghc-pkg</literal> will warn you if this might be
891 the case).</para>
892
893 <para>
894 The other time when <literal>ghc-pkg recache</literal> is
895 useful is for registering packages manually: it is
896 possible to register a package by simply putting the
897 appropriate file in the package database directory and
898 invoking <literal>ghc-pkg recache</literal> to update the
899 cache. This method of registering packages may be more
900 convenient for automated packaging systems.
901 </para>
902 </listitem>
903 </varlistentry>
904 </variablelist>
905
906 <para>
907 Substring matching is supported for <replaceable>M</replaceable> in
908 <literal>find-module</literal> and for <replaceable>P</replaceable> in
909 <literal>list</literal>, <literal>describe</literal>, and
910 <literal>field</literal>, where a <literal>'*'</literal> indicates open
911 substring ends (<literal>prefix*</literal>, <literal>*suffix</literal>,
912 <literal>*infix*</literal>). Examples (output omitted):
913 </para>
914 <screen>
915 -- list all regex-related packages
916 ghc-pkg list '*regex*' --ignore-case
917 -- list all string-related packages
918 ghc-pkg list '*string*' --ignore-case
919 -- list OpenGL-related packages
920 ghc-pkg list '*gl*' --ignore-case
921 -- list packages exporting modules in the Data hierarchy
922 ghc-pkg find-module 'Data.*'
923 -- list packages exporting Monad modules
924 ghc-pkg find-module '*Monad*'
925 -- list names and maintainers for all packages
926 ghc-pkg field '*' name,maintainer
927 -- list location of haddock htmls for all packages
928 ghc-pkg field '*' haddock-html
929 -- dump the whole database
930 ghc-pkg describe '*'
931 </screen>
932
933 <para>Additionally, the following flags are accepted by
934 <literal>ghc-pkg</literal>:</para>
935
936 <variablelist>
937 <varlistentry>
938 <term>
939 <option>-f</option> <replaceable>file</replaceable>
940 <indexterm><primary><option>-f</option></primary>
941 </indexterm>
942 </term>
943 <term>
944 <option>-package-db</option> <replaceable>file</replaceable>
945 <indexterm><primary><option>-package-db</option></primary>
946 </indexterm>
947 </term>
948 <listitem>
949 <para>Adds <replaceable>file</replaceable> to the stack of package
950 databases. Additionally, <replaceable>file</replaceable> will
951 also be the database modified by a <literal>register</literal>,
952 <literal>unregister</literal>, <literal>expose</literal> or
953 <literal>hide</literal> command, unless it is overridden by a later
954 <option>--package-db</option>, <option>--user</option> or
955 <option>--global</option> option.</para>
956 </listitem>
957 </varlistentry>
958
959 <varlistentry>
960 <term>
961 <option>--force</option>
962 <indexterm><primary>
963 <option>--force</option>
964 </primary></indexterm>
965 </term>
966 <listitem>
967 <para>Causes <literal>ghc-pkg</literal> to ignore missing
968 dependencies, directories and libraries when registering a package,
969 and just go ahead and add it anyway. This might be useful if your
970 package installation system needs to add the package to
971 GHC before building and installing the files.</para>
972 </listitem>
973 </varlistentry>
974
975 <varlistentry>
976 <term>
977 <option>--global</option><indexterm><primary><option>--global</option></primary>
978 </indexterm>
979 </term>
980 <listitem>
981 <para>Operate on the global package database (this is the default).
982 This flag affects the <literal>register</literal>,
983 <literal>update</literal>, <literal>unregister</literal>,
984 <literal>expose</literal>, and <literal>hide</literal>
985 commands.</para>
986 </listitem>
987 </varlistentry>
988
989 <varlistentry>
990 <term>
991 <option>--help</option><indexterm><primary><option>--help</option></primary>
992 </indexterm>
993 </term>
994 <term>
995 <option>-?</option><indexterm><primary><option>-?</option></primary>
996 </indexterm>
997 </term>
998 <listitem>
999 <para>Outputs the command-line syntax.</para>
1000 </listitem>
1001 </varlistentry>
1002
1003 <varlistentry>
1004 <term>
1005 <option>--user</option><indexterm><primary><option>--user</option></primary>
1006 </indexterm>
1007 </term>
1008 <listitem>
1009 <para>Operate on the current user's local package database.
1010 This flag affects the <literal>register</literal>,
1011 <literal>update</literal>, <literal>unregister</literal>,
1012 <literal>expose</literal>, and <literal>hide</literal>
1013 commands.</para>
1014 </listitem>
1015 </varlistentry>
1016
1017 <varlistentry>
1018 <term>
1019 <option>-v</option><optional><replaceable>n</replaceable></optional><indexterm><primary><option>-v</option></primary><secondary>ghc-pkg
1020 option</secondary></indexterm>
1021 </term>
1022 <term>
1023 <option>--verbose</option><optional>=<replaceable>n</replaceable></optional><indexterm><primary><option>--verbose</option></primary><secondary>ghc-pkg option</secondary></indexterm>
1024 </term>
1025 <listitem>
1026 <para>
1027 Control verbosity. Verbosity levels range from 0-2, where
1028 the default is 1, and <option>-v</option> alone selects
1029 level 2.
1030 </para>
1031 </listitem>
1032 </varlistentry>
1033
1034 <varlistentry>
1035 <term>
1036 <option>-V</option><indexterm><primary><option>-V</option></primary>
1037 </indexterm>
1038 </term>
1039 <term>
1040 <option>--version</option><indexterm><primary><option>--version</option></primary>
1041 </indexterm>
1042 </term>
1043 <listitem>
1044 <para>Output the <literal>ghc-pkg</literal> version number.</para>
1045 </listitem>
1046 </varlistentry>
1047
1048 <varlistentry>
1049 <term>
1050 <option>--ipid</option>
1051 <indexterm><primary>
1052 <option>--ipid</option>
1053 </primary></indexterm>
1054 </term>
1055 <listitem>
1056 <para>Causes <literal>ghc-pkg</literal> to interpret arguments
1057 as installed package IDs (e.g., an identifier like
1058 <literal>unix-2.3.1.0-de7803f1a8cd88d2161b29b083c94240
1059 </literal>). This is useful if providing just the package
1060 name and version are ambiguous (in old versions of GHC, this
1061 was guaranteed to be unique, but this invariant no longer
1062 necessarily holds).</para>
1063 </listitem>
1064 </varlistentry>
1065 </variablelist>
1066 </sect2>
1067
1068 <sect2 id="building-packages">
1069 <title>Building a package from Haskell source</title>
1070 <indexterm><primary>packages</primary>
1071 <secondary>building</secondary></indexterm>
1072
1073 <para>We don't recommend building packages the hard way. Instead, use the
1074 <ulink url="../Cabal/index.html">Cabal</ulink> infrastructure
1075 if possible. If your package is particularly complicated or requires a
1076 lot of configuration, then you might have to fall back to the low-level
1077 mechanisms, so a few hints for those brave souls follow.</para>
1078
1079 <para>You need to build an "installed package info" file for
1080 passing to <literal>ghc-pkg</literal> when installing your
1081 package. The contents of this file are described in
1082 <xref linkend="installed-pkg-info" />.</para>
1083
1084 <para>The Haskell code in a package may be built into one or more
1085 archive libraries (e.g. <filename>libHSfoo.a</filename>), or a
1086 single shared object
1087 (e.g. <filename>libHSfoo.dll/.so/.dylib</filename>). The
1088 restriction to a single shared object is because the package
1089 system is used to tell the compiler when it should make an
1090 inter-shared-object call rather than an intra-shared-object-call
1091 call (inter-shared-object calls require an extra
1092 indirection).</para>
1093 <itemizedlist>
1094 <listitem><para>Building a static library is done by using the
1095 <literal>ar</literal> tool, like so:</para>
1096
1097 <screen>ar cqs libHSfoo-1.0.a A.o B.o C.o ...</screen>
1098
1099 <para>where <filename>A.o</filename>,
1100 <filename>B.o</filename> and so on are the compiled Haskell
1101 modules, and <filename>libHSfoo.a</filename> is the library you
1102 wish to create. The syntax may differ slightly on your system,
1103 so check the documentation if you run into difficulties.</para>
1104 </listitem>
1105 <listitem>
1106 <para>To load a package <literal>foo</literal>, GHCi can load
1107 its <literal>libHSfoo.a</literal> library directly, but it
1108 can also load a package in the form of a
1109 single <literal>HSfoo.o</literal> file that has been
1110 pre-linked. Loading the <literal>.o</literal> file is
1111 slightly quicker, but at the expense of having another copy
1112 of the compiled package. The rule of thumb is that if the
1113 modules of the package were compiled
1114 with <option>-split-objs</option> then building
1115 the <literal>HSfoo.o</literal> is worthwhile because it
1116 saves time when loading the package into GHCi.
1117 Without <option>-split-objs</option>, there is not much
1118 difference in load time between the <literal>.o</literal>
1119 and <literal>.a</literal> libraries, so it is better to save
1120 the disk space and only keep the <literal>.a</literal>
1121 around. In a GHC distribution we
1122 provide <literal>.o</literal> files for most packages except
1123 the GHC package itself.
1124 </para>
1125
1126 <para>The <literal>HSfoo.o</literal> file is built by Cabal
1127 automatically;
1128 use <option>--disable-library-for-ghci</option> to disable
1129 it. To build one manually, the following
1130 GNU <command>ld</command> command can be used:</para>
1131
1132 <screen>ld -r --whole-archive -o HSfoo.o libHSfoo.a</screen>
1133
1134 <para>(replace
1135 <literal>--whole-archive</literal> with
1136 <literal>-all_load</literal> on MacOS X)</para>
1137 </listitem>
1138 <listitem>
1139 <para>When building the package as shared library, GHC can be used to
1140 perform the link step. This hides some of the details
1141 out the underlying linker and provides a common
1142 interface to all shared object variants that are supported
1143 by GHC (DLLs, ELF DSOs, and Mac OS dylibs). The shared
1144 object must be named in specific way for two reasons: (1)
1145 the name must contain the GHC compiler version, so that two
1146 library variants don't collide that are compiled by
1147 different versions of GHC and that therefore are most likely
1148 incompatible with respect to calling conventions, (2) it
1149 must be different from the static name otherwise we would
1150 not be able to control the linker as precisely as necessary
1151 to make
1152 the <option>-static</option>/<option>-dynamic</option> flags
1153 work, see <xref linkend="options-linker" />.</para>
1154
1155 <screen>ghc -shared libHSfoo-1.0-ghc<replaceable>GHCVersion</replaceable>.so A.o B.o C.o</screen>
1156 <para>Using GHC's version number in the shared object name
1157 allows different library versions compiled by different GHC
1158 versions to be installed in standard system locations,
1159 e.g. under *nix /usr/lib. To obtain the version number of
1160 GHC invoke <literal>ghc --numeric-version</literal> and use
1161 its output in place
1162 of <replaceable>GHCVersion</replaceable>. See also
1163 <xref linkend="options-codegen" /> on how object files must
1164 be prepared for shared object linking.</para>
1165 </listitem>
1166 </itemizedlist>
1167
1168 <para>To compile a module which is to be part of a new package,
1169 use the <literal>-this-package-key</literal> option (<xref linkend="using-packages"/>).
1170 Failure to use the <literal>-this-package-key</literal> option
1171 when compiling a package will probably result in disaster, but
1172 you will only discover later when you attempt to import modules
1173 from the package. At this point GHC will complain that the
1174 package name it was expecting the module to come from is not the
1175 same as the package name stored in the <literal>.hi</literal>
1176 file.</para>
1177
1178 <para>It is worth noting with shared objects, when each package
1179 is built as a single shared object file, since a reference to a shared object costs an extra
1180 indirection, intra-package references are cheaper than
1181 inter-package references. Of course, this applies to the
1182 <filename>main</filename> package as well.</para>
1183 </sect2>
1184
1185 <sect2 id="installed-pkg-info">
1186 <title>
1187 <literal>InstalledPackageInfo</literal>: a package specification
1188 </title>
1189
1190 <para>A package specification is a Haskell record; in particular, it is the
1191 record <ulink
1192 url="&libraryCabalLocation;/Distribution-InstalledPackageInfo.html#%tInstalledPackageInfo">InstalledPackageInfo</ulink> in the module Distribution.InstalledPackageInfo, which is part of the Cabal package distributed with GHC.</para>
1193
1194 <para>An <literal>InstalledPackageInfo</literal> has a human
1195 readable/writable syntax. The functions
1196 <literal>parseInstalledPackageInfo</literal> and
1197 <literal>showInstalledPackageInfo</literal> read and write this syntax
1198 respectively. Here's an example of the
1199 <literal>InstalledPackageInfo</literal> for the <literal>unix</literal> package:</para>
1200
1201 <screen>
1202 $ ghc-pkg describe unix
1203 name: unix
1204 version: 2.3.1.0
1205 id: unix-2.3.1.0-de7803f1a8cd88d2161b29b083c94240
1206 license: BSD3
1207 copyright:
1208 maintainer: libraries@haskell.org
1209 stability:
1210 homepage:
1211 package-url:
1212 description: This package gives you access to the set of operating system
1213 services standardised by POSIX 1003.1b (or the IEEE Portable
1214 Operating System Interface for Computing Environments -
1215 IEEE Std. 1003.1).
1216 .
1217 The package is not supported under Windows (except under Cygwin).
1218 category: System
1219 author:
1220 exposed: True
1221 exposed-modules: System.Posix System.Posix.DynamicLinker.Module
1222 System.Posix.DynamicLinker.Prim System.Posix.Directory
1223 System.Posix.DynamicLinker System.Posix.Env System.Posix.Error
1224 System.Posix.Files System.Posix.IO System.Posix.Process
1225 System.Posix.Process.Internals System.Posix.Resource
1226 System.Posix.Temp System.Posix.Terminal System.Posix.Time
1227 System.Posix.Unistd System.Posix.User System.Posix.Signals
1228 System.Posix.Signals.Exts System.Posix.Semaphore
1229 System.Posix.SharedMem
1230 hidden-modules:
1231 trusted: False
1232 import-dirs: /usr/lib/ghc-6.12.1/unix-2.3.1.0
1233 library-dirs: /usr/lib/ghc-6.12.1/unix-2.3.1.0
1234 hs-libraries: HSunix-2.3.1.0
1235 extra-libraries: rt util dl
1236 extra-ghci-libraries:
1237 include-dirs: /usr/lib/ghc-6.12.1/unix-2.3.1.0/include
1238 includes: HsUnix.h execvpe.h
1239 depends: base-4.2.0.0-247bb20cde37c3ef4093ee124e04bc1c
1240 hugs-options:
1241 cc-options:
1242 ld-options:
1243 framework-dirs:
1244 frameworks:
1245 haddock-interfaces: /usr/share/doc/ghc/html/libraries/unix/unix.haddock
1246 haddock-html: /usr/share/doc/ghc/html/libraries/unix
1247 </screen>
1248
1249 <para>Here is a brief description of the syntax of this file:</para>
1250
1251 <para>A package description consists of a number of field/value pairs. A
1252 field starts with the field name in the left-hand column followed by a
1253 &ldquo;<literal>:</literal>&rdquo;, and the value continues until the next line that begins in the
1254 left-hand column, or the end of file.</para>
1255
1256 <para>The syntax of the value depends on the field. The various field
1257 types are:</para>
1258
1259 <variablelist>
1260 <varlistentry>
1261 <term>freeform</term>
1262 <listitem>
1263 <para>Any arbitrary string, no interpretation or parsing is
1264 done.</para>
1265 </listitem>
1266 </varlistentry>
1267 <varlistentry>
1268 <term>string</term>
1269 <listitem>
1270 <para>A sequence of non-space characters, or a sequence of arbitrary
1271 characters surrounded by quotes <literal>"...."</literal>.</para>
1272 </listitem>
1273 </varlistentry>
1274 <varlistentry>
1275 <term>string list</term>
1276 <listitem>
1277 <para>A sequence of strings, separated by commas. The sequence may
1278 be empty.</para>
1279 </listitem>
1280 </varlistentry>
1281 </variablelist>
1282
1283 <para>In addition, there are some fields with special syntax (e.g. package
1284 names, version, dependencies).</para>
1285
1286 <para>The allowed fields, with their types, are:</para>
1287
1288 <variablelist>
1289 <varlistentry>
1290 <term>
1291 <literal>name</literal>
1292 <indexterm><primary><literal>name</literal></primary><secondary>package specification</secondary></indexterm>
1293 </term>
1294 <listitem>
1295 <para>The package's name (without the version).</para>
1296 </listitem>
1297 </varlistentry>
1298
1299 <varlistentry>
1300 <term>
1301 <literal>id</literal>
1302 <indexterm><primary><literal>id</literal></primary><secondary>package specification</secondary></indexterm>
1303 </term>
1304 <listitem>
1305 <para>The installed package ID. It is up to you to choose a suitable
1306 one.</para>
1307 </listitem>
1308 </varlistentry>
1309
1310 <varlistentry>
1311 <term>
1312 <literal>version</literal>
1313 <indexterm><primary><literal>version</literal></primary><secondary>package specification</secondary></indexterm>
1314 </term>
1315 <listitem>
1316 <para>The package's version, usually in the form
1317 <literal>A.B</literal> (any number of components are allowed).</para>
1318 </listitem>
1319 </varlistentry>
1320
1321 <varlistentry>
1322 <term>
1323 <literal>license</literal>
1324 <indexterm><primary><literal>auto</literal></primary><secondary>package specification</secondary></indexterm>
1325 </term>
1326 <listitem>
1327 <para>(string) The type of license under which this package is distributed.
1328 This field is a value of the <ulink
1329 url="&libraryCabalLocation;/Distribution-License.html#t:License"><literal>License</literal></ulink> type.</para>
1330 </listitem>
1331 </varlistentry>
1332
1333 <varlistentry>
1334 <term>
1335 <literal>license-file</literal>
1336 <indexterm><primary><literal>license-file</literal></primary><secondary>package specification</secondary></indexterm>
1337 </term>
1338 <listitem>
1339 <para>(optional string) The name of a file giving detailed license
1340 information for this package.</para>
1341 </listitem>
1342 </varlistentry>
1343
1344 <varlistentry>
1345 <term>
1346 <literal>copyright</literal>
1347 <indexterm><primary><literal>copyright</literal></primary><secondary>package specification</secondary></indexterm>
1348 </term>
1349 <listitem>
1350 <para>(optional freeform) The copyright string.</para>
1351 </listitem>
1352 </varlistentry>
1353
1354 <varlistentry>
1355 <term>
1356 <literal>maintainer</literal>
1357 <indexterm><primary><literal>maintainer</literal></primary><secondary>package specification</secondary></indexterm>
1358 </term>
1359 <listitem>
1360 <para>(optional freeform) The email address of the package's maintainer.</para>
1361 </listitem>
1362 </varlistentry>
1363
1364 <varlistentry>
1365 <term>
1366 <literal>stability</literal>
1367 <indexterm><primary><literal>stability</literal></primary><secondary>package specification</secondary></indexterm>
1368 </term>
1369 <listitem>
1370 <para>(optional freeform) A string describing the stability of the package
1371 (eg. stable, provisional or experimental).</para>
1372 </listitem>
1373 </varlistentry>
1374
1375 <varlistentry>
1376 <term>
1377 <literal>homepage</literal>
1378 <indexterm><primary><literal>homepage</literal></primary><secondary>package specification</secondary></indexterm>
1379 </term>
1380 <listitem>
1381 <para>(optional freeform) URL of the package's home page.</para>
1382 </listitem>
1383 </varlistentry>
1384
1385 <varlistentry>
1386 <term>
1387 <literal>package-url</literal>
1388 <indexterm><primary><literal>package-url</literal></primary><secondary>package specification</secondary></indexterm>
1389 </term>
1390 <listitem>
1391 <para>(optional freeform) URL of a downloadable distribution for this
1392 package. The distribution should be a Cabal package.</para>
1393 </listitem>
1394 </varlistentry>
1395
1396 <varlistentry>
1397 <term>
1398 <literal>description</literal>
1399 <indexterm><primary><literal>description</literal></primary><secondary>package specification</secondary></indexterm>
1400 </term>
1401 <listitem>
1402 <para>(optional freeform) Description of the package.</para>
1403 </listitem>
1404 </varlistentry>
1405
1406 <varlistentry>
1407 <term>
1408 <literal>category</literal>
1409 <indexterm><primary><literal>category</literal></primary><secondary>package specification</secondary></indexterm>
1410 </term>
1411 <listitem>
1412 <para>(optional freeform) Which category the package belongs to. This field
1413 is for use in conjunction with a future centralised package
1414 distribution framework, tentatively titled Hackage.</para>
1415 </listitem>
1416 </varlistentry>
1417
1418 <varlistentry>
1419 <term>
1420 <literal>author</literal>
1421 <indexterm><primary><literal>author</literal></primary><secondary>package specification</secondary></indexterm>
1422 </term>
1423 <listitem>
1424 <para>(optional freeform) Author of the package.</para>
1425 </listitem>
1426 </varlistentry>
1427
1428 <varlistentry>
1429 <term>
1430 <literal>exposed</literal>
1431 <indexterm><primary><literal>exposed</literal></primary><secondary>package specification</secondary></indexterm>
1432 </term>
1433 <listitem>
1434 <para>(bool) Whether the package is exposed or not.</para>
1435 </listitem>
1436 </varlistentry>
1437
1438 <varlistentry>
1439 <term>
1440 <literal>exposed-modules</literal>
1441 <indexterm><primary><literal>exposed-modules</literal></primary><secondary>package specification</secondary></indexterm>
1442 </term>
1443 <listitem>
1444 <para>(string list) modules exposed by this package.</para>
1445 </listitem>
1446 </varlistentry>
1447
1448 <varlistentry>
1449 <term>
1450 <literal>hidden-modules</literal>
1451 <indexterm><primary><literal>hidden-modules</literal></primary><secondary>package specification</secondary></indexterm>
1452 </term>
1453 <listitem>
1454 <para>(string list) modules provided by this package,
1455 but not exposed to the programmer. These modules cannot be
1456 imported, but they are still subject to the overlapping constraint:
1457 no other package in the same program may provide a module of the
1458 same name.</para>
1459 </listitem>
1460 </varlistentry>
1461
1462 <varlistentry>
1463 <term>
1464 <literal>reexported-modules</literal>
1465 <indexterm><primary><literal>reexported-modules</literal></primary><secondary>reexport specification</secondary></indexterm>
1466 </term>
1467 <listitem>
1468 <para>Modules reexported by this package. This list takes
1469 the form of <literal>pkg:OldName as NewName
1470 (A@orig-pkg-0.1-HASH)</literal>: the first portion of the
1471 string is the user-written reexport specification (possibly
1472 omitting the package qualifier and the renaming), while the
1473 parenthetical is the original package which exposed the
1474 module under are particular name. Reexported modules have
1475 a relaxed overlap constraint: it's permissible for two
1476 packages to reexport the same module as the same name if the
1477 reexported moduleis identical.</para>
1478 </listitem>
1479 </varlistentry>
1480
1481 <varlistentry>
1482 <term>
1483 <literal>trusted</literal>
1484 <indexterm><primary><literal>trusted</literal></primary><secondary>package specification</secondary></indexterm>
1485 </term>
1486 <listitem>
1487 <para>(bool) Whether the package is trusted or not.</para>
1488 </listitem>
1489 </varlistentry>
1490
1491 <varlistentry>
1492 <term>
1493 <literal>import-dirs</literal>
1494 <indexterm><primary><literal>import-dirs</literal></primary><secondary>package specification</secondary></indexterm>
1495 </term>
1496 <listitem>
1497 <para>(string list) A list of directories containing interface files
1498 (<literal>.hi</literal> files) for this package.</para>
1499
1500 <para>If the package contains profiling libraries, then
1501 the interface files for those library modules should have
1502 the suffix <literal>.p_hi</literal>. So the package can
1503 contain both normal and profiling versions of the same
1504 library without conflict (see also
1505 <literal>library_dirs</literal> below).</para>
1506 </listitem>
1507 </varlistentry>
1508
1509 <varlistentry>
1510 <term>
1511 <literal>library-dirs</literal>
1512 <indexterm><primary><literal>library-dirs</literal></primary><secondary>package specification</secondary></indexterm>
1513 </term>
1514 <listitem>
1515 <para>(string list) A list of directories containing libraries for this
1516 package.</para>
1517 </listitem>
1518 </varlistentry>
1519
1520 <varlistentry>
1521 <term>
1522 <literal>hs-libraries</literal>
1523 <indexterm><primary><literal>hs-libraries</literal></primary><secondary>package specification</secondary></indexterm>
1524 </term>
1525 <listitem>
1526 <para>(string list) A list of libraries containing Haskell code for this
1527 package, with the <literal>.a</literal> or
1528 <literal>.dll</literal> suffix omitted. When packages are
1529 built as libraries, the
1530 <literal>lib</literal> prefix is also omitted.</para>
1531
1532 <para>For use with GHCi, each library should have an
1533 object file too. The name of the object file does
1534 <emphasis>not</emphasis> have a <literal>lib</literal>
1535 prefix, and has the normal object suffix for your
1536 platform.</para>
1537
1538 <para>For example, if we specify a Haskell library as
1539 <filename>HSfoo</filename> in the package spec, then the
1540 various flavours of library that GHC actually uses will be
1541 called:</para>
1542 <variablelist>
1543 <varlistentry>
1544 <term><filename>libHSfoo.a</filename></term>
1545 <listitem>
1546 <para>The name of the library on Unix and Windows
1547 (mingw) systems. Note that we don't support
1548 building dynamic libraries of Haskell code on Unix
1549 systems.</para>
1550 </listitem>
1551 </varlistentry>
1552 <varlistentry>
1553 <term><filename>HSfoo.dll</filename></term>
1554 <listitem>
1555 <para>The name of the dynamic library on Windows
1556 systems (optional).</para>
1557 </listitem>
1558 </varlistentry>
1559 <varlistentry>
1560 <term><filename>HSfoo.o</filename></term>
1561 <term><filename>HSfoo.obj</filename></term>
1562 <listitem>
1563 <para>The object version of the library used by
1564 GHCi.</para>
1565 </listitem>
1566 </varlistentry>
1567 </variablelist>
1568 </listitem>
1569 </varlistentry>
1570
1571 <varlistentry>
1572 <term>
1573 <literal>extra-libraries</literal>
1574 <indexterm><primary><literal>extra-libraries</literal></primary><secondary>package specification</secondary></indexterm>
1575 </term>
1576 <listitem>
1577 <para>(string list) A list of extra libraries for this package. The
1578 difference between <literal>hs-libraries</literal> and
1579 <literal>extra-libraries</literal> is that
1580 <literal>hs-libraries</literal> normally have several
1581 versions, to support profiling, parallel and other build
1582 options. The various versions are given different
1583 suffixes to distinguish them, for example the profiling
1584 version of the standard prelude library is named
1585 <filename>libHSbase_p.a</filename>, with the
1586 <literal>_p</literal> indicating that this is a profiling
1587 version. The suffix is added automatically by GHC for
1588 <literal>hs-libraries</literal> only, no suffix is added
1589 for libraries in
1590 <literal>extra-libraries</literal>.</para>
1591
1592 <para>The libraries listed in
1593 <literal>extra-libraries</literal> may be any libraries
1594 supported by your system's linker, including dynamic
1595 libraries (<literal>.so</literal> on Unix,
1596 <literal>.DLL</literal> on Windows).</para>
1597
1598 <para>Also, <literal>extra-libraries</literal> are placed
1599 on the linker command line after the
1600 <literal>hs-libraries</literal> for the same package. If
1601 your package has dependencies in the other direction (i.e.
1602 <literal>extra-libraries</literal> depends on
1603 <literal>hs-libraries</literal>), and the libraries are
1604 static, you might need to make two separate
1605 packages.</para>
1606 </listitem>
1607 </varlistentry>
1608
1609 <varlistentry>
1610 <term>
1611 <literal>include-dirs</literal>
1612 <indexterm><primary><literal>include-dirs</literal></primary><secondary>package specification</secondary></indexterm>
1613 </term>
1614 <listitem>
1615 <para>(string list) A list of directories containing C includes for this
1616 package.</para>
1617 </listitem>
1618 </varlistentry>
1619
1620 <varlistentry>
1621 <term>
1622 <literal>includes</literal>
1623 <indexterm><primary><literal>includes</literal></primary><secondary>package specification</secondary></indexterm>
1624 </term>
1625 <listitem>
1626 <para>(string list) A list of files to include for via-C compilations
1627 using this package. Typically the include file(s) will
1628 contain function prototypes for any C functions used in
1629 the package, in case they end up being called as a result
1630 of Haskell functions from the package being
1631 inlined.</para>
1632 </listitem>
1633 </varlistentry>
1634
1635 <varlistentry>
1636 <term>
1637 <literal>depends</literal>
1638 <indexterm><primary><literal>depends</literal></primary><secondary>package specification</secondary></indexterm>
1639 </term>
1640 <listitem>
1641 <para>(package id list) Packages on which this package
1642 depends.</para>
1643 </listitem>
1644 </varlistentry>
1645
1646 <varlistentry>
1647 <term>
1648 <literal>hugs-options</literal>
1649 <indexterm><primary><literal>hugs-options</literal></primary><secondary>package specification</secondary></indexterm>
1650 </term>
1651 <listitem>
1652 <para>(string list) Options to pass to Hugs for this package.</para>
1653 </listitem>
1654 </varlistentry>
1655
1656 <varlistentry>
1657 <term>
1658 <literal>cc-options</literal>
1659 <indexterm><primary><literal>cc-options</literal></primary><secondary>package specification</secondary></indexterm>
1660 </term>
1661 <listitem>
1662 <para>(string list) Extra arguments to be added to the gcc command line
1663 when this package is being used (only for via-C
1664 compilations).</para>
1665 </listitem>
1666 </varlistentry>
1667
1668 <varlistentry>
1669 <term>
1670 <literal>ld-options</literal>
1671 <indexterm><primary><literal>ld-options</literal></primary><secondary>package specification</secondary></indexterm>
1672 </term>
1673 <listitem>
1674 <para>(string list) Extra arguments to be added to the
1675 <command>gcc</command> command line (for linking) when
1676 this package is being used.</para>
1677 </listitem>
1678 </varlistentry>
1679
1680 <varlistentry>
1681 <term>
1682 <literal>framework-dirs</literal>
1683 <indexterm><primary><literal>framework-dirs</literal></primary><secondary>package specification</secondary></indexterm>
1684 </term>
1685 <listitem>
1686 <para>(string list) On Darwin/MacOS X, a list of directories containing
1687 frameworks for this package. This corresponds to the
1688 <option>-framework-path</option> option. It is ignored on all other
1689 platforms.</para>
1690 </listitem>
1691 </varlistentry>
1692
1693 <varlistentry>
1694 <term>
1695 <literal>frameworks</literal>
1696 <indexterm><primary><literal>frameworks</literal></primary><secondary>package specification</secondary></indexterm>
1697 </term>
1698 <listitem>
1699 <para>(string list) On Darwin/MacOS X, a list of frameworks to link to. This
1700 corresponds to the <option>-framework</option> option. Take a look
1701 at Apple's developer documentation to find out what frameworks
1702 actually are. This entry is ignored on all other platforms.</para>
1703 </listitem>
1704 </varlistentry>
1705
1706 <varlistentry>
1707 <term>
1708 <literal>haddock-interfaces</literal>
1709 <indexterm><primary><literal>haddock-interfaces</literal></primary><secondary>package specification</secondary></indexterm>
1710 </term>
1711 <listitem>
1712 <para>(string list) A list of filenames containing <ulink
1713 url="http://www.haskell.org/haddock/">Haddock</ulink> interface
1714 files (<literal>.haddock</literal> files) for this package.</para>
1715 </listitem>
1716 </varlistentry>
1717
1718 <varlistentry>
1719 <term>
1720 <literal>haddock-html</literal>
1721 <indexterm><primary><literal>haddock-html</literal></primary><secondary>package specification</secondary></indexterm>
1722 </term>
1723 <listitem>
1724 <para>(optional string) The directory containing the Haddock-generated HTML
1725 for this package.</para>
1726 </listitem>
1727 </varlistentry>
1728 </variablelist>
1729
1730 <!-- This isn't true any more. I'm not sure if we still need it -SDM
1731 <para>
1732 The <literal>ghc-pkg</literal> tool performs expansion of
1733 environment variables occurring in input package specifications.
1734 So, if the <literal>mypkg</literal> was added to the package
1735 database as follows:
1736 </para>
1737 <screen>
1738 $ installdir=/usr/local/lib ghc-pkg -a &lt; mypkg.pkg
1739 </screen>
1740
1741 <para>
1742 The occurrence of <literal>${installdir}</literal> is replaced
1743 with <literal>/usr/local/lib</literal> in the package data that
1744 is added for <literal>mypkg</literal>.
1745 </para>
1746
1747 <para>
1748 This feature enables the distribution of package specification
1749 files that can be easily configured when installing.
1750 </para>
1751
1752 <para>For examples of more package specifications, take a look
1753 at the <literal>package.conf</literal> in your GHC
1754 installation.</para>
1755
1756 -->
1757
1758 </sect2>
1759 </sect1>
1760
1761 <!-- Emacs stuff:
1762 ;;; Local Variables: ***
1763 ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter" "sect1") ***
1764 ;;; End: ***
1765 -->