1 <?xml version="1.0" encoding="iso-8859-1"?>
6 <indexterm><primary>packages</primary></indexterm>
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
13 url="http://hackage.haskell.org/packages/hackage.html">HackageDB</ulink>.</para>
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>
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>,
30 <sect2 id="using-packages">
33 <indexterm><primary>packages</primary>
34 <secondary>using</secondary></indexterm>
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>
42 /usr/lib/ghc-6.12.1/package.conf.d:
47 bin-package-db-0.0.0.0
54 (dph-prim-interface-0.4.0)
58 extensible-exceptions-0.1.1.0
75 template-haskell-2.4.0.0
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
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>
104 <para>To see which modules are provided by a package use the
105 <literal>ghc-pkg</literal> command (see <xref linkend="package-management"/>):</para>
108 $ ghc-pkg field network exposed-modules
109 exposed-modules: Network.BSD,
116 <para>The GHC command line options that control packages are:</para>
121 <option>-package <replaceable>P</replaceable></option>
122 <indexterm><primary><option>-package</option></primary></indexterm>
125 <para>This option causes the installed
126 package <replaceable>P</replaceable> to be exposed. The
127 package <replaceable>P</replaceable> can be specified in
128 full with its version number
129 (e.g. <literal>network-1.0</literal>) or the version
130 number can be omitted if there is only one version of the
131 package installed. If there are multiple versions
132 of <replaceable>P</replaceable> installed, then all other
133 versions will become hidden.</para>
135 <para>The <option>-package <replaceable>P</replaceable></option>
136 option also causes package <replaceable>P</replaceable> to
137 be linked into the resulting executable or shared
138 object. Whether a packages' library is linked statically
139 or dynamically is controlled by the flag
140 pair <option>-static</option>/<option>-dynamic</option>.</para>
142 <para>In <option>––make</option> mode
143 and <option>––interactive</option> mode (see
144 <xref linkend="modes" />), the compiler normally
145 determines which packages are required by the current
146 Haskell modules, and links only those. In batch mode
147 however, the dependency information isn't available, and
149 <option>-package</option> options must be given when linking. The one other time you might need to use
150 <option>-package</option> to force linking a package is
151 when the package does not contain any Haskell modules (it
152 might contain a C library only, for example). In that
153 case, GHC will never discover a dependency on it, so it
154 has to be mentioned explicitly.</para>
156 <para>For example, to link a program consisting of objects
157 <filename>Foo.o</filename> and <filename>Main.o</filename>, where
158 we made use of the <literal>network</literal> package, we need to
159 give GHC the <literal>-package</literal> flag thus:
161 <screen>$ ghc -o myprog Foo.o Main.o -package network</screen>
163 The same flag is necessary even if we compiled the modules from
164 source, because GHC still reckons it's in batch mode:
166 <screen>$ ghc -o myprog Foo.hs Main.hs -package network</screen></para>
172 <option>-package-id <replaceable>P</replaceable></option>
173 <indexterm><primary><option>-package-id</option></primary></indexterm>
177 Exposes a package like <option>-package</option>, but the
178 package is named by its ID rather than by name. This is a
179 more robust way to name packages, and can be used to
180 select packages that would otherwise be shadowed. Cabal
181 passes <option>-package-id</option> flags to GHC.
187 <term><option>-hide-all-packages</option>
188 <indexterm><primary><option>-hide-package</option></primary>
191 <para>Ignore the exposed flag on installed packages, and hide them
192 all by default. If you use
193 this flag, then any packages you require (including
194 <literal>base</literal>) need to be explicitly exposed using
195 <option>-package</option> options.</para>
197 <para>This is a good way to insulate your program from
198 differences in the globally exposed packages, and being
199 explicit about package dependencies is a Good Thing.
200 Cabal always passes the
201 <option>-hide-all-packages</option> flag to GHC, for
202 exactly this reason.</para>
207 <term><option>-hide-package</option> <replaceable>P</replaceable>
208 <indexterm><primary><option>-hide-package</option></primary>
211 <para>This option does the opposite of <option>-package</option>: it
212 causes the specified package to be <firstterm>hidden</firstterm>,
213 which means that none of its modules will be available for import
214 by Haskell <literal>import</literal> directives.</para>
216 <para>Note that the package might still end up being linked into the
217 final program, if it is a dependency (direct or indirect) of
218 another exposed package.</para>
223 <term><option>-ignore-package</option> <replaceable>P</replaceable>
224 <indexterm><primary><option>-ignore-package</option></primary>
227 <para>Causes the compiler to behave as if package
228 <replaceable>P</replaceable>, and any packages that depend on
229 <literal>P</literal>, are not installed at all.</para>
231 <para>Saying <literal>-ignore-package P</literal> is the same as
232 giving <literal>-hide-package</literal> flags for
233 <literal>P</literal> and all the packages that depend on
234 <literal>P</literal>. Sometimes we don't know ahead of time which
235 packages will be installed that depend on <literal>P</literal>,
236 which is when the <literal>-ignore-package</literal> flag can be
242 <term><option>-no-auto-link-packages</option>
243 <indexterm><primary><option>-no-auto-link-packages</option></primary>
246 <para>By default, GHC will automatically link in the
247 <literal>haskell98</literal> package. This flag disables that
253 <term><option>-package-name</option> <replaceable>foo</replaceable>
254 <indexterm><primary><option>-package-name</option></primary>
257 <para>Tells GHC the the module being compiled forms part of
258 package <replaceable>foo</replaceable>.
259 If this flag is omitted (a very common case) then the
260 default package <literal>main</literal> is assumed.</para>
261 <para>Note: the argument to <option>-package-name</option>
263 package <literal>name-version</literal> for the package.
265 <literal>-package mypkg-1.2</literal>.</para>
271 <sect2 id="package-main">
272 <title>The main package</title>
274 <para>Every complete Haskell program must define <literal>main</literal> in
275 module <literal>Main</literal>
276 in package <literal>main</literal>. (Omitting the <option>-package-name</option> flag compiles
277 code for package <literal>main</literal>.) Failure to do so leads to a somewhat obscure
278 link-time error of the form:
280 /usr/bin/ld: Undefined symbols:
287 <sect2 id="package-overlaps">
288 <title>Consequences of packages for the Haskell language</title>
290 <para>It is possible that by using packages you might end up with
291 a program that contains two modules with the same name: perhaps
292 you used a package P that has a <emphasis>hidden</emphasis> module
293 M, and there is also a module M in your program. Or perhaps the
294 dependencies of packages that you used contain some overlapping
295 modules. Perhaps the program even contains multiple versions of a
296 certain package, due to dependencies from other packages.</para>
298 <para>None of these scenarios gives rise to an error on its
299 own<footnote><para>it used to in GHC 6.4, but not since
300 6.6</para></footnote>, but they may have some interesting
301 consequences. For instance, if you have a type
302 <literal>M.T</literal> from version 1 of package
303 <literal>P</literal>, then this is <emphasis>not</emphasis> the
304 same as the type <literal>M.T</literal> from version 2 of package
305 <literal>P</literal>, and GHC will report an error if you try to
306 use one where the other is expected.</para>
308 <para>Formally speaking, in Haskell 98, an entity (function, type
309 or class) in a program is uniquely identified by the pair of the
310 module name in which it is defined and its name. In GHC, an
311 entity is uniquely defined by a triple: package, module, and
315 <sect2 id="package-databases">
316 <title>Package Databases</title>
319 A package database is where the details about installed packages
320 are stored. It is a directory, usually
321 called <literal>package.conf.d</literal>, that contains a file
322 for each package, together with a binary cache of the package
323 data in the file <literal>package.cache</literal>. Normally
324 you won't need to look at or modify the contents of a package
325 database directly; all management of package databases can be
326 done through the <literal>ghc-pkg</literal> tool (see
327 <xref linkend="package-management" />).
331 GHC knows about two package databases in particular:
336 <para>The global package database, which comes with your GHC
338 e.g. <filename>/usr/lib/ghc-6.12.1/package.conf.d</filename>.</para>
341 <para>A package database private to each user. On Unix
343 <filename>$HOME/.ghc/<replaceable>arch</replaceable>-<replaceable>os</replaceable>-<replaceable>version</replaceable>/package.conf.d</filename>, and on
344 Windows it will be something like
345 <filename>C:\Documents And Settings\<replaceable>user</replaceable>\ghc\package.conf.d</filename>.
346 The <literal>ghc-pkg</literal> tool knows where this file should be
347 located, and will create it if it doesn't exist (see <xref linkend="package-management" />).</para>
351 <para>When GHC starts up, it reads the contents of these two package
352 databases, and builds up a list of the packages it knows about. You can
353 see GHC's package table by running GHC with the <option>-v</option>
356 <para>Package databases may overlap: for example, packages in the
357 user database will override (<emphasis>shadow</emphasis>) those
358 of the same name and version in the global database.</para>
360 <para>You can control the loading of package databases using the following
366 <option>-package-conf <replaceable>file</replaceable></option>
367 <indexterm><primary><option>-package-conf</option></primary></indexterm>
370 <para>Read in the package configuration file
371 <replaceable>file</replaceable> in addition to the system
372 default file and the user's local file. Packages in additional
373 files read this way will override those in the global and user
379 <term><option>-no-user-package-conf</option>
380 <indexterm><primary><option>-no-user-package-conf</option></primary>
384 <para>Prevent loading of the user's local package database.</para>
389 <sect3 id="ghc-package-path">
390 <title>The <literal>GHC_PACKAGE_PATH</literal> environment variable</title>
391 <indexterm><primary>Environment variable</primary><secondary><literal>GHC_PACKAGE_PATH</literal></secondary>
393 <indexterm><primary><literal>GHC_PACKAGE_PATH</literal></primary></indexterm>
394 <para>The <literal>GHC_PACKAGE_PATH</literal> environment variable may be
395 set to a <literal>:</literal>-separated (<literal>;</literal>-separated
396 on Windows) list of files containing package databases. This list of
397 package databases is used by GHC and ghc-pkg, with earlier databases in
398 the list overriding later ones. This order was chosen to match the
399 behaviour of the <literal>PATH</literal> environment variable; think of
400 it as a list of package databases that are searched left-to-right for
403 <para>If <literal>GHC_PACKAGE_PATH</literal> ends in a separator, then
404 the default user and system package databases are appended, in that
405 order. e.g. to augment the usual set of packages with a database of
406 your own, you could say (on Unix):
408 $ export GHC_PACKAGE_PATH=$HOME/.my-ghc-packages.conf:</screen>
409 (use <literal>;</literal> instead of <literal>:</literal> on
412 <para>To check whether your <literal>GHC_PACKAGE_PATH</literal> setting
413 is doing the right thing, <literal>ghc-pkg list</literal> will list all
414 the databases in use, in the reverse order they are searched.</para>
419 <sect2 id="package-ids">
420 <title>Package IDs, dependencies, and broken packages</title>
422 <para>Each installed package has a unique identifier (the
423 “installed package ID”, or just “package
424 ID” for short) , which distinguishes it from all other
425 installed packages on the system. To see the package IDs
426 associated with each installed package, use <literal>ghc-pkg
427 list -v</literal>:</para>
431 using cache: /usr/lib/ghc-6.12.1/package.conf.d/package.cache
432 /usr/lib/ghc-6.12.1/package.conf.d
433 Cabal-1.7.4 (Cabal-1.7.4-48f5247e06853af93593883240e11238)
434 array-0.2.0.1 (array-0.2.0.1-9cbf76a576b6ee9c1f880cf171a0928d)
435 base-3.0.3.0 (base-3.0.3.0-6cbb157b9ae852096266e113b8fac4a2)
436 base-4.2.0.0 (base-4.2.0.0-247bb20cde37c3ef4093ee124e04bc1c)
441 The string in parentheses after the package name is the package
442 ID: it normally begins with the package name and version, and
443 ends in a hash string derived from the compiled package.
444 Dependencies between packages are expressed in terms of package
445 IDs, rather than just packages and versions. For example, take
446 a look at the dependencies of the <literal>haskell98</literal>
451 $ ghc-pkg field haskell98 depends
452 depends: array-0.2.0.1-9cbf76a576b6ee9c1f880cf171a0928d
453 base-4.2.0.0-247bb20cde37c3ef4093ee124e04bc1c
454 directory-1.0.0.2-f51711bc872c35ce4a453aa19c799008
455 old-locale-1.0.0.1-d17c9777c8ee53a0d459734e27f2b8e9
456 old-time-1.0.0.1-1c0d8ea38056e5087ef1e75cb0d139d1
457 process-1.0.1.1-d8fc6d3baf44678a29b9d59ca0ad5780
458 random-1.0.0.1-423d08c90f004795fd10e60384ce6561
462 The purpose of the package ID is to detect problems caused by
463 re-installing a package without also recompiling the packages
464 that depend on it. Recompiling dependencies is necessary,
465 because the newly compiled package may have a differnt ABI
466 (Application Binary Interface) than the previous version, even
467 if both packages were built from the same source code using the
468 same compiler. With package IDs, a recompiled
469 package will have a different package ID from the previous
470 version, so packages that depended on the previous version are
471 now orphaned - one of their dependencies is not satisfied.
472 Packages that are broken in this way are shown in
473 the <literal>ghc-pkg list</literal> output either in red (if
474 possible) or otherwise surrounded by braces. In the following
475 example, we have recompiled and reinstalled
476 the <literal>filepath</literal> package, and this has caused
477 various dependencies including <literal>Cabal</literal> to
482 WARNING: there are broken packages. Run 'ghc-pkg check' for more details.
483 /usr/lib/ghc-6.12.1/package.conf.d:
491 Additionally, <literal>ghc-pkg list</literal> reminds you that
492 there are broken packages and suggests <literal>ghc-pkg
493 check</literal>, which displays more information about the
494 nature of the failure:
499 There are problems in package ghc-6.12.1:
500 dependency "filepath-1.1.0.1-87511764eb0af2bce4db05e702750e63" doesn't exist
501 There are problems in package haskeline-0.6.2:
502 dependency "filepath-1.1.0.1-87511764eb0af2bce4db05e702750e63" doesn't exist
503 There are problems in package Cabal-1.7.4:
504 dependency "filepath-1.1.0.1-87511764eb0af2bce4db05e702750e63" doesn't exist
505 There are problems in package process-1.0.1.1:
506 dependency "filepath-1.1.0.1-87511764eb0af2bce4db05e702750e63" doesn't exist
507 There are problems in package directory-1.0.0.2:
508 dependency "filepath-1.1.0.1-87511764eb0af2bce4db05e702750e63" doesn't exist
510 The following packages are broken, either because they have a problem
511 listed above, or because they depend on a broken package.
517 bin-package-db-0.0.0.0
523 To fix the problem, you need to recompile the broken packages
524 against the new dependencies. The easiest way to do this is to
525 use <literal>cabal-install</literal>, or download the packages
527 url="http://hackage.haskell.org/packages/hackage.html">HackageDB</ulink>
528 and build and install them as normal.</para>
530 <para>Be careful not to recompile any packages that GHC itself
531 depends on, as this may render the <literal>ghc</literal>
532 package itself broken, and <literal>ghc</literal> cannot be
533 simply recompiled. The only way to recover from this would be
534 to re-install GHC.</para>
537 <sect2 id="package-management">
538 <title>Package management (the <literal>ghc-pkg</literal> command)</title>
539 <indexterm><primary>packages</primary>
540 <secondary>management</secondary></indexterm>
542 <para>The <literal>ghc-pkg</literal> tool is for querying and
543 modifying package databases. To see what package databases are
545 <literal>ghc-pkg list</literal>. The stack of databases that
546 <literal>ghc-pkg</literal> knows about can be modified using the
547 <literal>GHC_PACKAGE_PATH</literal> environment variable (see <xref
548 linkend="ghc-package-path" />, and using
549 <literal>--package-conf</literal> options on the
550 <literal>ghc-pkg</literal> command line.</para>
552 <para>When asked to modify a database, <literal>ghc-pkg</literal> modifies
553 the global database by default. Specifying <option>--user</option>
554 causes it to act on the user database, or <option>--package-conf</option>
555 can be used to act on another database entirely. When multiple of these
556 options are given, the rightmost one is used as the database to act
559 <para>Commands that query the package database (list, latest,
560 describe, field, dot) operate on the list of databases specified by
561 the flags <option>--user</option>, <option>--global</option>, and
562 <option>--package-conf</option>. If none of these flags are
563 given, the default is <option>--global</option>
564 <option>--user</option>.</para>
566 <para>If the environment variable <literal>GHC_PACKAGE_PATH</literal> is
567 set, and its value does not end in a separator (<literal>:</literal> on
568 Unix, <literal>;</literal> on Windows), then the last database is
569 considered to be the global database, and will be modified by default by
570 <literal>ghc-pkg</literal>. The intention here is that
571 <literal>GHC_PACKAGE_PATH</literal> can be used to create a virtual
572 package environment into which Cabal packages can be installed without
573 setting anything other than <literal>GHC_PACKAGE_PATH</literal>.</para>
575 <para>The <literal>ghc-pkg</literal> program may be run in the ways listed
576 below. Where a package name is required, the package can be named in
577 full including the version number
578 (e.g. <literal>network-1.0</literal>), or without the version number.
579 Naming a package without the version number matches all versions of the
580 package; the specified action will be applied to all the matching
581 packages. A package specifier that matches all version of the package
582 can also be written <replaceable>pkg</replaceable><literal>-*</literal>,
583 to make it clearer that multiple packages are being matched.</para>
587 <term><literal>ghc-pkg init <replaceable>path</replaceable></literal></term>
589 <para>Creates a new, empty, package database
590 at <replaceable>path</replaceable>, which must not already
596 <term><literal>ghc-pkg register <replaceable>file</replaceable></literal></term>
598 <para>Reads a package specification from
599 <replaceable>file</replaceable> (which may be “<literal>-</literal>”
600 to indicate standard input),
601 and adds it to the database of installed packages. The syntax of
602 <replaceable>file</replaceable> is given in <xref
603 linkend="installed-pkg-info" />.</para>
605 <para>The package specification must be a package that isn't already
611 <term><literal>ghc-pkg update <replaceable>file</replaceable></literal></term>
613 <para>The same as <literal>register</literal>, except that if a
614 package of the same name is already installed, it is
615 replaced by the new one.</para>
620 <term><literal>ghc-pkg unregister <replaceable>P</replaceable></literal></term>
622 <para>Remove the specified package from the database.</para>
627 <term><literal>ghc-pkg expose <replaceable>P</replaceable></literal></term>
629 <para>Sets the <literal>exposed</literal> flag for package
630 <replaceable>P</replaceable> to <literal>True</literal>.</para>
635 <term><literal>ghc-pkg check</literal></term>
637 <para>Check consistency of dependencies in the package
638 database, and report packages that have missing
644 <term><literal>ghc-pkg hide <replaceable>P</replaceable></literal></term>
646 <para>Sets the <literal>exposed</literal> flag for package
647 <replaceable>P</replaceable> to <literal>False</literal>.</para>
652 <term><literal>ghc-pkg list [<replaceable>P</replaceable>] [<option>--simple-output</option>]</literal></term>
654 <para>This option displays the currently installed
655 packages, for each of the databases known to
656 <literal>ghc-pkg</literal>. That includes the global database, the
657 user's local database, and any further files specified using the
658 <option>-f</option> option on the command line.</para>
660 <para>Hidden packages (those for which the <literal>exposed</literal>
661 flag is <literal>False</literal>) are shown in parentheses in the
662 list of packages.</para>
664 <para>If an optional package identifier <replaceable>P</replaceable>
665 is given, then only packages matching that identifier are
668 <para>If the option <option>--simple-output</option> is given, then
669 the packages are listed on a single line separated by spaces, and
670 the database names are not included. This is intended to make it
671 easier to parse the output of <literal>ghc-pkg list</literal> using
677 <term><literal>ghc-pkg find-module <replaceable>M</replaceable> [<option>--simple-output</option>]</literal></term>
679 <para>This option lists registered packages exposing module
680 <replaceable>M</replaceable>. Examples:</para>
682 $ ghc-pkg find-module Var
683 c:/fptools/validate/ghc/driver/package.conf.inplace:
686 $ ghc-pkg find-module Data.Sequence
687 c:/fptools/validate/ghc/driver/package.conf.inplace:
690 <para>Otherwise, it behaves like <literal>ghc-pkg list</literal>,
691 including options.</para>
697 <term><literal>ghc-pkg latest <replaceable>P</replaceable></literal></term>
699 <para>Prints the latest available version of package
700 <replaceable>P</replaceable>.</para>
705 <term><literal>ghc-pkg describe <replaceable>P</replaceable></literal></term>
707 <para>Emit the full description of the specified package. The
708 description is in the form of an
709 <literal>InstalledPackageInfo</literal>, the same as the input file
710 format for <literal>ghc-pkg register</literal>. See <xref
711 linkend="installed-pkg-info" /> for details.</para>
713 <para>If the pattern matches multiple packages, the
714 description for each package is emitted, separated by the
715 string <literal>---</literal> on a line by itself.</para>
720 <term><literal>ghc-pkg field <replaceable>P</replaceable> <replaceable>field</replaceable>[,<replaceable>field</replaceable>]*</literal></term>
722 <para>Show just a single field of the installed package description
723 for <literal>P</literal>. Multiple fields can be selected by separating
724 them with commas</para>
729 <term><literal>ghc-pkg dot</literal></term>
732 Generate a graph of the package dependencies in a form
733 suitable for input for the <ulink url="http://www.graphviz.org/">graphviz</ulink> tools. For example,
734 to generate a PDF of the dependency graph:</para>
736 ghc-pkg dot | tred | dot -Tpdf >pkgs.pdf
742 <term><literal>ghc-pkg dump</literal></term>
744 <para>Emit the full description of every package, in the
745 form of an <literal>InstalledPackageInfo</literal>.
746 Multiple package descriptions are separated by the
747 string <literal>---</literal> on a line by itself.</para>
749 <para>This is almost the same as <literal>ghc-pkg describe '*'</literal>, except that <literal>ghc-pkg dump</literal>
750 is intended for use by tools that parse the results, so
751 for example where <literal>ghc-pkg describe '*'</literal>
752 will emit an error if it can't find any packages that
753 match the pattern, <literal>ghc-pkg dump</literal> will
754 simply emit nothing.</para>
759 <term><literal>ghc-pkg recache</literal></term>
762 Re-creates the binary cache
763 file <filename>package.cache</filename> for the selected
764 database. This may be necessary if the cache has somehow
765 become out-of-sync with the contents of the database
766 (<literal>ghc-pkg</literal> will warn you if this might be
770 The other time when <literal>ghc-pkg recache</literal> is
771 useful is for registering packages manually: it is
772 possible to register a package by simply putting the
773 appropriate file in the package database directory and
774 invoking <literal>ghc-pkg recache</literal> to update the
775 cache. This method of registering packages may be more
776 convenient for automated packaging systems.
783 Substring matching is supported for <replaceable>M</replaceable> in
784 <literal>find-module</literal> and for <replaceable>P</replaceable> in
785 <literal>list</literal>, <literal>describe</literal>, and
786 <literal>field</literal>, where a <literal>'*'</literal> indicates open
787 substring ends (<literal>prefix*</literal>, <literal>*suffix</literal>,
788 <literal>*infix*</literal>). Examples (output omitted):
791 -- list all regex-related packages
792 ghc-pkg list '*regex*' --ignore-case
793 -- list all string-related packages
794 ghc-pkg list '*string*' --ignore-case
795 -- list OpenGL-related packages
796 ghc-pkg list '*gl*' --ignore-case
797 -- list packages exporting modules in the Data hierarchy
798 ghc-pkg find-module 'Data.*'
799 -- list packages exporting Monad modules
800 ghc-pkg find-module '*Monad*'
801 -- list names and maintainers for all packages
802 ghc-pkg field '*' name,maintainer
803 -- list location of haddock htmls for all packages
804 ghc-pkg field '*' haddock-html
805 -- dump the whole database
809 <para>Additionally, the following flags are accepted by
810 <literal>ghc-pkg</literal>:</para>
815 <option>––auto-ghci-libs</option><indexterm><primary><option>––auto-ghci-libs</option></primary>
819 <para>Automatically generate the GHCi
820 <filename>.o</filename> version of each
821 <filename>.a</filename> Haskell library, using GNU ld (if
822 that is available). Without this option,
823 <literal>ghc-pkg</literal> will warn if GHCi versions of
824 any Haskell libraries in the package don't exist.</para>
826 <para>GHCi <literal>.o</literal> libraries don't
827 necessarily have to live in the same directory as the
828 corresponding <literal>.a</literal> library. However,
829 this option will cause the GHCi library to be created in
830 the same directory as the <literal>.a</literal>
837 <option>-f</option> <replaceable>file</replaceable>
838 <indexterm><primary><option>-f</option></primary>
842 <option>-package-conf</option> <replaceable>file</replaceable>
843 <indexterm><primary><option>-package-conf</option></primary>
847 <para>Adds <replaceable>file</replaceable> to the stack of package
848 databases. Additionally, <replaceable>file</replaceable> will
849 also be the database modified by a <literal>register</literal>,
850 <literal>unregister</literal>, <literal>expose</literal> or
851 <literal>hide</literal> command, unless it is overridden by a later
852 <option>--package-conf</option>, <option>--user</option> or
853 <option>--global</option> option.</para>
859 <option>––force</option>
861 <option>––force</option>
862 </primary></indexterm>
865 <para>Causes <literal>ghc-pkg</literal> to ignore missing
866 dependencies, directories and libraries when registering a package,
867 and just go ahead and add it anyway. This might be useful if your
868 package installation system needs to add the package to
869 GHC before building and installing the files.</para>
875 <option>––global</option><indexterm><primary><option>––global</option></primary>
879 <para>Operate on the global package database (this is the default).
880 This flag affects the <literal>register</literal>,
881 <literal>update</literal>, <literal>unregister</literal>,
882 <literal>expose</literal>, and <literal>hide</literal>
889 <option>––help</option><indexterm><primary><option>––help</option></primary>
893 <option>-?</option><indexterm><primary><option>-?</option></primary>
897 <para>Outputs the command-line syntax.</para>
903 <option>––user</option><indexterm><primary><option>––user</option></primary>
907 <para>Operate on the current user's local package database.
908 This flag affects the <literal>register</literal>,
909 <literal>update</literal>, <literal>unregister</literal>,
910 <literal>expose</literal>, and <literal>hide</literal>
917 <option>-v</option><optional><replaceable>n</replaceable></optional><indexterm><primary><option>-v</option></primary><secondary>ghc-pkg
918 option</secondary></indexterm>
921 <option>--verbose</option><optional>=<replaceable>n</replaceable></optional><indexterm><primary><option>--verbose</option></primary><secondary>ghc-pkg option</secondary></indexterm>
925 Control verbosity. Verbosity levels range from 0-2, where
926 the default is 1, and <option>-v</option> alone selects
934 <option>-V</option><indexterm><primary><option>-V</option></primary>
938 <option>––version</option><indexterm><primary><option>––version</option></primary>
942 <para>Output the <literal>ghc-pkg</literal> version number.</para>
949 <sect2 id="building-packages">
950 <title>Building a package from Haskell source</title>
951 <indexterm><primary>packages</primary>
952 <secondary>building</secondary></indexterm>
954 <para>We don't recommend building packages the hard way. Instead, use the
955 <ulink url="../Cabal/index.html">Cabal</ulink> infrastructure
956 if possible. If your package is particularly complicated or requires a
957 lot of configuration, then you might have to fall back to the low-level
958 mechanisms, so a few hints for those brave souls follow.</para>
960 <para>You need to build an "installed package info" file for
961 passing to <literal>ghc-pkg</literal> when installing your
962 package. The contents of this file are described in
963 <xref linkend="installed-pkg-info" />.</para>
965 <para>The Haskell code in a package may be built into one or more
966 archive libraries (e.g. <filename>libHSfoo.a</filename>), or a
968 (e.g. <filename>libHSfoo.dll/.so/.dylib</filename>). The
969 restriction to a single shared object is because the package
970 system is used to tell the compiler when it should make an
971 inter-shared-object call rather than an intra-shared-object-call
972 call (inter-shared-object calls require an extra
975 <listitem><para>Building a static library is done by using the
976 <literal>ar</literal> tool, like so:</para>
978 <screen>ar cqs libHSfoo-1.0.a A.o B.o C.o ...</screen>
980 <para>where <filename>A.o</filename>,
981 <filename>B.o</filename> and so on are the compiled Haskell
982 modules, and <filename>libHSfoo.a</filename> is the library you
983 wish to create. The syntax may differ slightly on your system,
984 so check the documentation if you run into difficulties.</para>
987 <para>Versions of the Haskell libraries for use with GHCi may also
988 abe included: GHCi cannot load <literal>.a</literal> files
989 directly, instead it will look for an object file
990 called <filename>HSfoo.o</filename> and load that. On some
991 systems, the <literal>ghc-pkg</literal> tool can automatically
992 build the GHCi version of each library, see
993 <xref linkend="package-management"/>. To build these libraries
994 by hand from the <literal>.a</literal> archive, it is possible
995 to use GNU <command>ld</command> as follows:</para>
997 <screen>ld -r ––whole-archive -o HSfoo.o libHSfoo.a</screen>
1000 <literal>––whole-archive</literal> with
1001 <literal>–all_load</literal> on MacOS X)</para>
1004 <para>When building the package as shared library, GHC can be used to
1005 perform the link step. This hides some of the details
1006 out the underlying linker and provides a common
1007 interface to all shared object variants that are supported
1008 by GHC (DLLs, ELF DSOs, and Mac OS dylibs). The shared
1009 object must be named in specific way for two reasons: (1)
1010 the name must contain the GHC compiler version, so that two
1011 library variants don't collide that are compiled by
1012 different versions of GHC and that therefore are most likely
1013 incompatible with respect to calling conventions, (2) it
1014 must be different from the static name otherwise we would
1015 not be able to control the linker as precisely as necessary
1017 the <option>-static</option>/<option>-dynamic</option> flags
1018 work, see <xref linkend="options-linker" />.</para>
1020 <screen>ghc -shared libHSfoo-1.0-ghc<replaceable>GHCVersion</replaceable>.so A.o B.o C.o</screen>
1021 <para>Using GHC's version number in the shared object name
1022 allows different library versions compiled by different GHC
1023 versions to be installed in standard system locations,
1024 e.g. under *nix /usr/lib. To obtain the version number of
1025 GHC invoke <literal>ghc --numeric-version</literal> and use
1027 of <replaceable>GHCVersion</replaceable>. See also
1028 <xref linkend="options-codegen" /> on how object files must
1029 be prepared for shared object linking.</para>
1033 <para>To compile a module which is to be part of a new package,
1034 use the <literal>-package-name</literal> option (<xref linkend="using-packages"/>).
1035 Failure to use the <literal>-package-name</literal> option
1036 when compiling a package will probably result in disaster, but
1037 you will only discover later when you attempt to import modules
1038 from the package. At this point GHC will complain that the
1039 package name it was expecting the module to come from is not the
1040 same as the package name stored in the <literal>.hi</literal>
1043 <para>It is worth noting with shared objects, when each package
1044 is built as a single shared object file, since a reference to a shared object costs an extra
1045 indirection, intra-package references are cheaper than
1046 inter-package references. Of course, this applies to the
1047 <filename>main</filename> package as well.</para>
1050 <sect2 id="installed-pkg-info">
1052 <literal>InstalledPackageInfo</literal>: a package specification
1055 <para>A package specification is a Haskell record; in particular, it is the
1057 url="&libraryCabalLocation;/Distribution-InstalledPackageInfo.html#%tInstalledPackageInfo">InstalledPackageInfo</ulink> in the module Distribution.InstalledPackageInfo, which is part of the Cabal package distributed with GHC.</para>
1059 <para>An <literal>InstalledPackageInfo</literal> has a human
1060 readable/writable syntax. The functions
1061 <literal>parseInstalledPackageInfo</literal> and
1062 <literal>showInstalledPackageInfo</literal> read and write this syntax
1063 respectively. Here's an example of the
1064 <literal>InstalledPackageInfo</literal> for the <literal>unix</literal> package:</para>
1067 $ ghc-pkg describe unix
1070 id: unix-2.3.1.0-de7803f1a8cd88d2161b29b083c94240
1073 maintainer: libraries@haskell.org
1077 description: This package gives you access to the set of operating system
1078 services standardised by POSIX 1003.1b (or the IEEE Portable
1079 Operating System Interface for Computing Environments -
1082 The package is not supported under Windows (except under Cygwin).
1086 exposed-modules: System.Posix System.Posix.DynamicLinker.Module
1087 System.Posix.DynamicLinker.Prim System.Posix.Directory
1088 System.Posix.DynamicLinker System.Posix.Env System.Posix.Error
1089 System.Posix.Files System.Posix.IO System.Posix.Process
1090 System.Posix.Process.Internals System.Posix.Resource
1091 System.Posix.Temp System.Posix.Terminal System.Posix.Time
1092 System.Posix.Unistd System.Posix.User System.Posix.Signals
1093 System.Posix.Signals.Exts System.Posix.Semaphore
1094 System.Posix.SharedMem
1096 import-dirs: /usr/lib/ghc-6.12.1/unix-2.3.1.0
1097 library-dirs: /usr/lib/ghc-6.12.1/unix-2.3.1.0
1098 hs-libraries: HSunix-2.3.1.0
1099 extra-libraries: rt util dl
1100 extra-ghci-libraries:
1101 include-dirs: /usr/lib/ghc-6.12.1/unix-2.3.1.0/include
1102 includes: HsUnix.h execvpe.h
1103 depends: base-4.2.0.0-247bb20cde37c3ef4093ee124e04bc1c
1109 haddock-interfaces: /usr/share/doc/ghc/html/libraries/unix/unix.haddock
1110 haddock-html: /usr/share/doc/ghc/html/libraries/unix
1113 <para>Here is a brief description of the syntax of this file:</para>
1115 <para>A package description consists of a number of field/value pairs. A
1116 field starts with the field name in the left-hand column followed by a
1117 “<literal>:</literal>”, and the value continues until the next line that begins in the
1118 left-hand column, or the end of file.</para>
1120 <para>The syntax of the value depends on the field. The various field
1125 <term>freeform</term>
1127 <para>Any arbitrary string, no interpretation or parsing is
1134 <para>A sequence of non-space characters, or a sequence of arbitrary
1135 characters surrounded by quotes <literal>"...."</literal>.</para>
1139 <term>string list</term>
1141 <para>A sequence of strings, separated by commas. The sequence may
1147 <para>In addition, there are some fields with special syntax (e.g. package
1148 names, version, dependencies).</para>
1150 <para>The allowed fields, with their types, are:</para>
1155 <literal>name</literal>
1156 <indexterm><primary><literal>name</literal></primary><secondary>package specification</secondary></indexterm>
1159 <para>The package's name (without the version).</para>
1165 <literal>id</literal>
1166 <indexterm><primary><literal>id</literal></primary><secondary>package specification</secondary></indexterm>
1169 <para>The package ID. It is up to you to choose a suitable
1176 <literal>version</literal>
1177 <indexterm><primary><literal>version</literal></primary><secondary>package specification</secondary></indexterm>
1180 <para>The package's version, usually in the form
1181 <literal>A.B</literal> (any number of components are allowed).</para>
1187 <literal>license</literal>
1188 <indexterm><primary><literal>auto</literal></primary><secondary>package specification</secondary></indexterm>
1191 <para>(string) The type of license under which this package is distributed.
1192 This field is a value of the <ulink
1193 url="&libraryCabalLocation;/Distribution-License.html#t:License"><literal>License</literal></ulink> type.</para>
1199 <literal>license-file</literal>
1200 <indexterm><primary><literal>license-file</literal></primary><secondary>package specification</secondary></indexterm>
1203 <para>(optional string) The name of a file giving detailed license
1204 information for this package.</para>
1210 <literal>copyright</literal>
1211 <indexterm><primary><literal>copyright</literal></primary><secondary>package specification</secondary></indexterm>
1214 <para>(optional freeform) The copyright string.</para>
1220 <literal>maintainer</literal>
1221 <indexterm><primary><literal>maintainer</literal></primary><secondary>package specification</secondary></indexterm>
1224 <para>(optinoal freeform) The email address of the package's maintainer.</para>
1230 <literal>stability</literal>
1231 <indexterm><primary><literal>stability</literal></primary><secondary>package specification</secondary></indexterm>
1234 <para>(optional freeform) A string describing the stability of the package
1235 (eg. stable, provisional or experimental).</para>
1241 <literal>homepage</literal>
1242 <indexterm><primary><literal>homepage</literal></primary><secondary>package specification</secondary></indexterm>
1245 <para>(optional freeform) URL of the package's home page.</para>
1251 <literal>package-url</literal>
1252 <indexterm><primary><literal>package-url</literal></primary><secondary>package specification</secondary></indexterm>
1255 <para>(optional freeform) URL of a downloadable distribution for this
1256 package. The distribution should be a Cabal package.</para>
1262 <literal>description</literal>
1263 <indexterm><primary><literal>description</literal></primary><secondary>package specification</secondary></indexterm>
1266 <para>(optional freeform) Description of the package.</para>
1272 <literal>category</literal>
1273 <indexterm><primary><literal>category</literal></primary><secondary>package specification</secondary></indexterm>
1276 <para>(optinoal freeform) Which category the package belongs to. This field
1277 is for use in conjunction with a future centralised package
1278 distribution framework, tentatively titled Hackage.</para>
1284 <literal>author</literal>
1285 <indexterm><primary><literal>author</literal></primary><secondary>package specification</secondary></indexterm>
1288 <para>(optional freeform) Author of the package.</para>
1294 <literal>exposed</literal>
1295 <indexterm><primary><literal>exposed</literal></primary><secondary>package specification</secondary></indexterm>
1298 <para>(bool) Whether the package is exposed or not.</para>
1304 <literal>exposed-modules</literal>
1305 <indexterm><primary><literal>exposed-modules</literal></primary><secondary>package specification</secondary></indexterm>
1308 <para>(string list) modules exposed by this package.</para>
1314 <literal>hidden-modules</literal>
1315 <indexterm><primary><literal>hidden-modules</literal></primary><secondary>package specification</secondary></indexterm>
1318 <para>(string list) modules provided by this package,
1319 but not exposed to the programmer. These modules cannot be
1320 imported, but they are still subject to the overlapping constraint:
1321 no other package in the same program may provide a module of the
1328 <literal>import-dirs</literal>
1329 <indexterm><primary><literal>import-dirs</literal></primary><secondary>package specification</secondary></indexterm>
1332 <para>(string list) A list of directories containing interface files
1333 (<literal>.hi</literal> files) for this package.</para>
1335 <para>If the package contains profiling libraries, then
1336 the interface files for those library modules should have
1337 the suffix <literal>.p_hi</literal>. So the package can
1338 contain both normal and profiling versions of the same
1339 library without conflict (see also
1340 <literal>library_dirs</literal> below).</para>
1346 <literal>library-dirs</literal>
1347 <indexterm><primary><literal>library-dirs</literal></primary><secondary>package specification</secondary></indexterm>
1350 <para>(string list) A list of directories containing libraries for this
1357 <literal>hs-libraries</literal>
1358 <indexterm><primary><literal>hs-libraries</literal></primary><secondary>package specification</secondary></indexterm>
1361 <para>(string list) A list of libraries containing Haskell code for this
1362 package, with the <literal>.a</literal> or
1363 <literal>.dll</literal> suffix omitted. When packages are
1364 built as libraries, the
1365 <literal>lib</literal> prefix is also omitted.</para>
1367 <para>For use with GHCi, each library should have an
1368 object file too. The name of the object file does
1369 <emphasis>not</emphasis> have a <literal>lib</literal>
1370 prefix, and has the normal object suffix for your
1373 <para>For example, if we specify a Haskell library as
1374 <filename>HSfoo</filename> in the package spec, then the
1375 various flavours of library that GHC actually uses will be
1379 <term><filename>libHSfoo.a</filename></term>
1381 <para>The name of the library on Unix and Windows
1382 (mingw) systems. Note that we don't support
1383 building dynamic libraries of Haskell code on Unix
1388 <term><filename>HSfoo.dll</filename></term>
1390 <para>The name of the dynamic library on Windows
1391 systems (optional).</para>
1395 <term><filename>HSfoo.o</filename></term>
1396 <term><filename>HSfoo.obj</filename></term>
1398 <para>The object version of the library used by
1408 <literal>extra-libraries</literal>
1409 <indexterm><primary><literal>extra-libraries</literal></primary><secondary>package specification</secondary></indexterm>
1412 <para>(string list) A list of extra libraries for this package. The
1413 difference between <literal>hs-libraries</literal> and
1414 <literal>extra-libraries</literal> is that
1415 <literal>hs-libraries</literal> normally have several
1416 versions, to support profiling, parallel and other build
1417 options. The various versions are given different
1418 suffixes to distinguish them, for example the profiling
1419 version of the standard prelude library is named
1420 <filename>libHSbase_p.a</filename>, with the
1421 <literal>_p</literal> indicating that this is a profiling
1422 version. The suffix is added automatically by GHC for
1423 <literal>hs-libraries</literal> only, no suffix is added
1425 <literal>extra-libraries</literal>.</para>
1427 <para>The libraries listed in
1428 <literal>extra-libraries</literal> may be any libraries
1429 supported by your system's linker, including dynamic
1430 libraries (<literal>.so</literal> on Unix,
1431 <literal>.DLL</literal> on Windows).</para>
1433 <para>Also, <literal>extra-libraries</literal> are placed
1434 on the linker command line after the
1435 <literal>hs-libraries</literal> for the same package. If
1436 your package has dependencies in the other direction (i.e.
1437 <literal>extra-libraries</literal> depends on
1438 <literal>hs-libraries</literal>), and the libraries are
1439 static, you might need to make two separate
1446 <literal>include-dirs</literal>
1447 <indexterm><primary><literal>include-dirs</literal></primary><secondary>package specification</secondary></indexterm>
1450 <para>(string list) A list of directories containing C includes for this
1457 <literal>includes</literal>
1458 <indexterm><primary><literal>includes</literal></primary><secondary>package specification</secondary></indexterm>
1461 <para>(string list) A list of files to include for via-C compilations
1462 using this package. Typically the include file(s) will
1463 contain function prototypes for any C functions used in
1464 the package, in case they end up being called as a result
1465 of Haskell functions from the package being
1472 <literal>depends</literal>
1473 <indexterm><primary><literal>depends</literal></primary><secondary>package specification</secondary></indexterm>
1476 <para>(package id list) Packages on which this package
1483 <literal>hugs-options</literal>
1484 <indexterm><primary><literal>hugs-options</literal></primary><secondary>package specification</secondary></indexterm>
1487 <para>(string list) Options to pass to Hugs for this package.</para>
1493 <literal>cc-options</literal>
1494 <indexterm><primary><literal>cc-options</literal></primary><secondary>package specification</secondary></indexterm>
1497 <para>(string list) Extra arguments to be added to the gcc command line
1498 when this package is being used (only for via-C
1499 compilations).</para>
1505 <literal>ld-options</literal>
1506 <indexterm><primary><literal>ld-options</literal></primary><secondary>package specification</secondary></indexterm>
1509 <para>(string list) Extra arguments to be added to the
1510 <command>gcc</command> command line (for linking) when
1511 this package is being used.</para>
1517 <literal>framework-dirs</literal>
1518 <indexterm><primary><literal>framework-dirs</literal></primary><secondary>package specification</secondary></indexterm>
1521 <para>(string list) On Darwin/MacOS X, a list of directories containing
1522 frameworks for this package. This corresponds to the
1523 <option>-framework-path</option> option. It is ignored on all other
1530 <literal>frameworks</literal>
1531 <indexterm><primary><literal>frameworks</literal></primary><secondary>package specification</secondary></indexterm>
1534 <para>(string list) On Darwin/MacOS X, a list of frameworks to link to. This
1535 corresponds to the <option>-framework</option> option. Take a look
1536 at Apple's developer documentation to find out what frameworks
1537 actually are. This entry is ignored on all other platforms.</para>
1543 <literal>haddock-interfaces</literal>
1544 <indexterm><primary><literal>haddock-interfaces</literal></primary><secondary>package specification</secondary></indexterm>
1547 <para>(string list) A list of filenames containing <ulink
1548 url="http://www.haskell.org/haddock/">Haddock</ulink> interface
1549 files (<literal>.haddock</literal> files) for this package.</para>
1555 <literal>haddock-html</literal>
1556 <indexterm><primary><literal>haddock-html</literal></primary><secondary>package specification</secondary></indexterm>
1559 <para>(optional string) The directory containing the Haddock-generated HTML
1560 for this package.</para>
1565 <!-- This isn't true any more. I'm not sure if we still need it -SDM
1567 The <literal>ghc-pkg</literal> tool performs expansion of
1568 environment variables occurring in input package specifications.
1569 So, if the <literal>mypkg</literal> was added to the package
1570 database as follows:
1573 $ installdir=/usr/local/lib ghc-pkg -a < mypkg.pkg
1577 The occurrence of <literal>${installdir}</literal> is replaced
1578 with <literal>/usr/local/lib</literal> in the package data that
1579 is added for <literal>mypkg</literal>.
1583 This feature enables the distribution of package specification
1584 files that can be easily configured when installing.
1587 <para>For examples of more package specifications, take a look
1588 at the <literal>package.conf</literal> in your GHC
1589 installation.</para>
1597 ;;; Local Variables: ***
1598 ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter" "sect1") ***