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