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="../libraries/Cabal/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>
171 <term><option>-hide-all-packages</option>
172 <indexterm><primary><option>-hide-package</option></primary>
175 <para>Ignore the exposed flag on installed packages, and hide them
176 all by default. If you use
177 this flag, then any packages you require (including
178 <literal>base</literal>) need to be explicitly exposed using
179 <option>-package</option> options.</para>
181 <para>This is a good way to insulate your program from
182 differences in the globally exposed packages, and being
183 explicit about package dependencies is a Good Thing.
184 Cabal always passes the
185 <option>-hide-all-packages</option> flag to GHC, for
186 exactly this reason.</para>
191 <term><option>-hide-package</option> <replaceable>P</replaceable>
192 <indexterm><primary><option>-hide-package</option></primary>
195 <para>This option does the opposite of <option>-package</option>: it
196 causes the specified package to be <firstterm>hidden</firstterm>,
197 which means that none of its modules will be available for import
198 by Haskell <literal>import</literal> directives.</para>
200 <para>Note that the package might still end up being linked into the
201 final program, if it is a dependency (direct or indirect) of
202 another exposed package.</para>
207 <term><option>-ignore-package</option> <replaceable>P</replaceable>
208 <indexterm><primary><option>-ignore-package</option></primary>
211 <para>Causes the compiler to behave as if package
212 <replaceable>P</replaceable>, and any packages that depend on
213 <literal>P</literal>, are not installed at all.</para>
215 <para>Saying <literal>-ignore-package P</literal> is the same as
216 giving <literal>-hide-package</literal> flags for
217 <literal>P</literal> and all the packages that depend on
218 <literal>P</literal>. Sometimes we don't know ahead of time which
219 packages will be installed that depend on <literal>P</literal>,
220 which is when the <literal>-ignore-package</literal> flag can be
226 <term><option>-package-name</option> <replaceable>foo</replaceable>
227 <indexterm><primary><option>-package-name</option></primary>
230 <para>Tells GHC the the module being compiled forms part of
231 package <replaceable>foo</replaceable>.
232 If this flag is omitted (a very common case) then the
233 default package <literal>main</literal> is assumed.</para>
234 <para>Note: the argument to <option>-package-name</option>
235 should be the full package identifier for the package,
236 that is it should include the version number. For example:
237 <literal>-package mypkg-1.2</literal>.</para>
243 <sect2 id="package-main">
244 <title>The main package</title>
246 <para>Every complete Haskell program must define <literal>main</literal> in
247 module <literal>Main</literal>
248 in package <literal>main</literal>. (Omitting the <option>-package-name</option> flag compiles
249 code for package <literal>main</literal>.) Failure to do so leads to a somewhat obscure
250 link-time error of the form:
252 /usr/bin/ld: Undefined symbols:
260 <sect2 id="package-overlaps">
261 <title>Consequences of packages for the Haskell language</title>
263 <para>It is possible that by using packages you might end up with
264 a program that contains two modules with the same name: perhaps
265 you used a package P that has a <emphasis>hidden</emphasis> module
266 M, and there is also a module M in your program. Or perhaps the
267 dependencies of packages that you used contain some overlapping
268 modules. Perhaps the program even contains multiple versions of a
269 certain package, due to dependencies from other packages.</para>
271 <para>None of these scenarios gives rise to an error on its
272 own<footnote><para>it used to in GHC 6.4, but not since
273 6.6</para></footnote>, but they may have some interesting
274 consequences. For instance, if you have a type
275 <literal>M.T</literal> from version 1 of package
276 <literal>P</literal>, then this is <emphasis>not</emphasis> the
277 same as the type <literal>M.T</literal> from version 2 of package
278 <literal>P</literal>, and GHC will report an error if you try to
279 use one where the other is expected.</para>
281 <para>Formally speaking, in Haskell 98, an entity (function, type
282 or class) in a program is uniquely identified by the pair of the
283 module name in which it is defined and its name. In GHC, an
284 entity is uniquely defined by a triple: package, module, and
288 <sect2 id="package-databases">
289 <title>Package Databases</title>
292 A package database is where the details about installed packages
293 are stored. It is a directory, usually
294 called <literal>package.conf.d</literal>, that contains a file
295 for each package, together with a binary cache of the package
296 data in the file <literal>package.cache</literal>. Normally
297 you won't need to look at or modify the contents of a package
298 database directly; all management of package databases can be
299 done through the <literal>ghc-pkg</literal> tool (see
300 <xref linkend="package-management" />).
304 GHC knows about two package databases in particular:
309 <para>The global package database, which comes with your GHC
311 e.g. <filename>/usr/lib/ghc-6.12.1/package.conf.d</filename>.</para>
314 <para>A package database private to each user. On Unix
316 <filename>$HOME/.ghc/<replaceable>arch</replaceable>-<replaceable>os</replaceable>-<replaceable>version</replaceable>/package.conf.d</filename>, and on
317 Windows it will be something like
318 <filename>C:\Documents And Settings\<replaceable>user</replaceable>\ghc\package.conf.d</filename>.
319 The <literal>ghc-pkg</literal> tool knows where this file should be
320 located, and will create it if it doesn't exist (see <xref linkend="package-management" />).</para>
324 <para>When GHC starts up, it reads the contents of these two package
325 databases, and builds up a list of the packages it knows about. You can
326 see GHC's package table by running GHC with the <option>-v</option>
329 <para>Package databases may overlap: for example, packages in the
330 user database will override (<emphasis>shadow</emphasis>) those
331 of the same name and version in the global database.</para>
333 <para>You can control the loading of package databases using the following
339 <option>-package-conf <replaceable>file</replaceable></option>
340 <indexterm><primary><option>-package-conf</option></primary></indexterm>
343 <para>Read in the package configuration file
344 <replaceable>file</replaceable> in addition to the system
345 default file and the user's local file. Packages in additional
346 files read this way will override those in the global and user
352 <term><option>-no-user-package-conf</option>
353 <indexterm><primary><option>-no-user-package-conf</option></primary>
357 <para>Prevent loading of the user's local package database.</para>
362 <sect3 id="ghc-package-path">
363 <title>The <literal>GHC_PACKAGE_PATH</literal> environment variable</title>
364 <indexterm><primary>Environment variable</primary><secondary><literal>GHC_PACKAGE_PATH</literal></secondary>
366 <indexterm><primary><literal>GHC_PACKAGE_PATH</literal></primary></indexterm>
367 <para>The <literal>GHC_PACKAGE_PATH</literal> environment variable may be
368 set to a <literal>:</literal>-separated (<literal>;</literal>-separated
369 on Windows) list of files containing package databases. This list of
370 package databases is used by GHC and ghc-pkg, with earlier databases in
371 the list overriding later ones. This order was chosen to match the
372 behaviour of the <literal>PATH</literal> environment variable; think of
373 it as a list of package databases that are searched left-to-right for
376 <para>If <literal>GHC_PACKAGE_PATH</literal> ends in a separator, then
377 the default user and system package databases are appended, in that
378 order. e.g. to augment the usual set of packages with a database of
379 your own, you could say (on Unix):
381 $ export GHC_PACKAGE_PATH=$HOME/.my-ghc-packages.conf:</screen>
382 (use <literal>;</literal> instead of <literal>:</literal> on
385 <para>To check whether your <literal>GHC_PACKAGE_PATH</literal> setting
386 is doing the right thing, <literal>ghc-pkg list</literal> will list all
387 the databases in use, in the reverse order they are searched.</para>
392 <sect2 id="broken-packages">
393 <title>Dependencies and broken packages</title>
395 <para>Each installed package has a unique identifier, which
396 distinguishes it from all other installed packages on the
397 system. To see the identifiers associated with each installed
398 package, use <literal>ghc-pkg list -v</literal>:</para>
402 using cache: /usr/lib/ghc-6.12.1/package.conf.d/package.cache
403 /usr/lib/ghc-6.12.1/package.conf.d
404 Cabal-1.7.4 (Cabal-1.7.4-48f5247e06853af93593883240e11238)
405 array-0.2.0.1 (array-0.2.0.1-9cbf76a576b6ee9c1f880cf171a0928d)
406 base-3.0.3.0 (base-3.0.3.0-6cbb157b9ae852096266e113b8fac4a2)
407 base-4.2.0.0 (base-4.2.0.0-247bb20cde37c3ef4093ee124e04bc1c)
412 The string in parentheses after the package name is the unique
413 identifier: it normally begins with the package name and
414 version, and ends in a hash string derived from the compiled
415 package. Dependencies between packages are expressed in terms
416 of these unique identifiers, rather than just packages and
417 versions. For example, take a look at the dependencies of
418 the <literal>haskell98</literal> package:
422 $ ghc-pkg field haskell98 depends
423 depends: array-0.2.0.1-9cbf76a576b6ee9c1f880cf171a0928d
424 base-4.2.0.0-247bb20cde37c3ef4093ee124e04bc1c
425 directory-1.0.0.2-f51711bc872c35ce4a453aa19c799008
426 old-locale-1.0.0.1-d17c9777c8ee53a0d459734e27f2b8e9
427 old-time-1.0.0.1-1c0d8ea38056e5087ef1e75cb0d139d1
428 process-1.0.1.1-d8fc6d3baf44678a29b9d59ca0ad5780
429 random-1.0.0.1-423d08c90f004795fd10e60384ce6561
433 The purpose of the unique package identifier is to detect
434 problems caused by re-installing a package without also
435 recompiling the packages that depend on it. Recompiling
436 dependencies is necessary, because the newly compiled package
437 may have a differnt ABI (Application Binary Interface) than the
438 previous version, even if both packages were built from the same
439 source code using the same compiler. With unique package
440 identifiers, a recompiled package will have a different unique
441 identifer from the previous version, so packages that depended
442 on the previous version are now orphaned - one of their
443 dependencies is not satisfied. Packages that are broken in this
444 way are shown in the <literal>ghc-pkg list</literal> output
445 either in red (if possible) or otherwise surrounded by
446 braces. In the following example, we have recompiled and
447 reinstalled the <literal>filepath</literal> package, and this
448 has caused various dependencies
449 including <literal>Cabal</literal> to break:</para>
453 WARNING: there are broken packages. Run 'ghc-pkg check' for more details.
454 /usr/lib/ghc-6.12.1/package.conf.d:
462 Additionally, <literal>ghc-pkg list</literal> reminds you that
463 there are broken packages and suggests <literal>ghc-pkg
464 check</literal>, which displays more information about the
465 nature of the failure:
470 There are problems in package ghc-6.12.1:
471 dependency "filepath-1.1.0.1-87511764eb0af2bce4db05e702750e63" doesn't exist
472 There are problems in package haskeline-0.6.2:
473 dependency "filepath-1.1.0.1-87511764eb0af2bce4db05e702750e63" doesn't exist
474 There are problems in package Cabal-1.7.4:
475 dependency "filepath-1.1.0.1-87511764eb0af2bce4db05e702750e63" doesn't exist
476 There are problems in package process-1.0.1.1:
477 dependency "filepath-1.1.0.1-87511764eb0af2bce4db05e702750e63" doesn't exist
478 There are problems in package directory-1.0.0.2:
479 dependency "filepath-1.1.0.1-87511764eb0af2bce4db05e702750e63" doesn't exist
481 The following packages are broken, either because they have a problem
482 listed above, or because they depend on a broken package.
488 bin-package-db-0.0.0.0
494 To fix the problem, you need to recompile the broken packages
495 against the new dependencies. The easiest way to do this is to
496 use <literal>cabal-install</literal>, or download the packages
498 url="http://hackage.haskell.org/packages/hackage.html">HackageDB</ulink>
499 and build and install them as normal.</para>
501 <para>Be careful not to recompile any packages that GHC itself
502 depends on, as this may render the <literal>ghc</literal>
503 package itself broken, and <literal>ghc</literal> cannot be
504 simply recompiled. The only way to recover from this would be
505 to re-install GHC.</para>
508 <sect2 id="package-management">
509 <title>Package management (the <literal>ghc-pkg</literal> command)</title>
510 <indexterm><primary>packages</primary>
511 <secondary>management</secondary></indexterm>
513 <para>The <literal>ghc-pkg</literal> tool is for querying and
514 modifying package databases. To see what package databases are
516 <literal>ghc-pkg list</literal>. The stack of databases that
517 <literal>ghc-pkg</literal> knows about can be modified using the
518 <literal>GHC_PACKAGE_PATH</literal> environment variable (see <xref
519 linkend="ghc-package-path" />, and using
520 <literal>--package-conf</literal> options on the
521 <literal>ghc-pkg</literal> command line.</para>
523 <para>When asked to modify a database, <literal>ghc-pkg</literal> modifies
524 the global database by default. Specifying <option>--user</option>
525 causes it to act on the user database, or <option>--package-conf</option>
526 can be used to act on another database entirely. When multiple of these
527 options are given, the rightmost one is used as the database to act
530 <para>Commands that query the package database (list, latest,
531 describe, field, dot) operate on the list of databases specified by
532 the flags <option>--user</option>, <option>--global</option>, and
533 <option>--package-conf</option>. If none of these flags are
534 given, the default is <option>--global</option>
535 <option>--user</option>.</para>
537 <para>If the environment variable <literal>GHC_PACKAGE_PATH</literal> is
538 set, and its value does not end in a separator (<literal>:</literal> on
539 Unix, <literal>;</literal> on Windows), then the last database is
540 considered to be the global database, and will be modified by default by
541 <literal>ghc-pkg</literal>. The intention here is that
542 <literal>GHC_PACKAGE_PATH</literal> can be used to create a virtual
543 package environment into which Cabal packages can be installed without
544 setting anything other than <literal>GHC_PACKAGE_PATH</literal>.</para>
546 <para>The <literal>ghc-pkg</literal> program may be run in the ways listed
547 below. Where a package name is required, the package can be named in
548 full including the version number
549 (e.g. <literal>network-1.0</literal>), or without the version number.
550 Naming a package without the version number matches all versions of the
551 package; the specified action will be applied to all the matching
552 packages. A package specifier that matches all version of the package
553 can also be written <replaceable>pkg</replaceable><literal>-*</literal>,
554 to make it clearer that multiple packages are being matched.</para>
558 <term><literal>ghc-pkg init <replaceable>path</replaceable></literal></term>
560 <para>Creates a new, empty, package database
561 at <replaceable>path</replaceable>, which must not already
567 <term><literal>ghc-pkg register <replaceable>file</replaceable></literal></term>
569 <para>Reads a package specification from
570 <replaceable>file</replaceable> (which may be “<literal>-</literal>”
571 to indicate standard input),
572 and adds it to the database of installed packages. The syntax of
573 <replaceable>file</replaceable> is given in <xref
574 linkend="installed-pkg-info" />.</para>
576 <para>The package specification must be a package that isn't already
582 <term><literal>ghc-pkg update <replaceable>file</replaceable></literal></term>
584 <para>The same as <literal>register</literal>, except that if a
585 package of the same name is already installed, it is
586 replaced by the new one.</para>
591 <term><literal>ghc-pkg unregister <replaceable>P</replaceable></literal></term>
593 <para>Remove the specified package from the database.</para>
598 <term><literal>ghc-pkg expose <replaceable>P</replaceable></literal></term>
600 <para>Sets the <literal>exposed</literal> flag for package
601 <replaceable>P</replaceable> to <literal>True</literal>.</para>
606 <term><literal>ghc-pkg check</literal></term>
608 <para>Check consistency of dependencies in the package
609 database, and report packages that have missing
615 <term><literal>ghc-pkg hide <replaceable>P</replaceable></literal></term>
617 <para>Sets the <literal>exposed</literal> flag for package
618 <replaceable>P</replaceable> to <literal>False</literal>.</para>
623 <term><literal>ghc-pkg list [<replaceable>P</replaceable>] [<option>--simple-output</option>]</literal></term>
625 <para>This option displays the currently installed
626 packages, for each of the databases known to
627 <literal>ghc-pkg</literal>. That includes the global database, the
628 user's local database, and any further files specified using the
629 <option>-f</option> option on the command line.</para>
631 <para>Hidden packages (those for which the <literal>exposed</literal>
632 flag is <literal>False</literal>) are shown in parentheses in the
633 list of packages.</para>
635 <para>If an optional package identifier <replaceable>P</replaceable>
636 is given, then only packages matching that identifier are
639 <para>If the option <option>--simple-output</option> is given, then
640 the packages are listed on a single line separated by spaces, and
641 the database names are not included. This is intended to make it
642 easier to parse the output of <literal>ghc-pkg list</literal> using
648 <term><literal>ghc-pkg find-module <replaceable>M</replaceable> [<option>--simple-output</option>]</literal></term>
650 <para>This option lists registered packages exposing module
651 <replaceable>M</replaceable>. Examples:</para>
653 $ ghc-pkg find-module Var
654 c:/fptools/validate/ghc/driver/package.conf.inplace:
657 $ ghc-pkg find-module Data.Sequence
658 c:/fptools/validate/ghc/driver/package.conf.inplace:
661 <para>Otherwise, it behaves like <literal>ghc-pkg list</literal>,
662 including options.</para>
668 <term><literal>ghc-pkg latest <replaceable>P</replaceable></literal></term>
670 <para>Prints the latest available version of package
671 <replaceable>P</replaceable>.</para>
676 <term><literal>ghc-pkg describe <replaceable>P</replaceable></literal></term>
678 <para>Emit the full description of the specified package. The
679 description is in the form of an
680 <literal>InstalledPackageInfo</literal>, the same as the input file
681 format for <literal>ghc-pkg register</literal>. See <xref
682 linkend="installed-pkg-info" /> for details.</para>
684 <para>If the pattern matches multiple packages, the
685 description for each package is emitted, separated by the
686 string <literal>---</literal> on a line by itself.</para>
691 <term><literal>ghc-pkg field <replaceable>P</replaceable> <replaceable>field</replaceable>[,<replaceable>field</replaceable>]*</literal></term>
693 <para>Show just a single field of the installed package description
694 for <literal>P</literal>. Multiple fields can be selected by separating
695 them with commas</para>
700 <term><literal>ghc-pkg dot</literal></term>
703 Generate a graph of the package dependencies in a form
704 suitable for input for the <ulink url="http://www.graphviz.org/">graphviz</ulink> tools. For example,
705 to generate a PDF of the dependency graph:</para>
707 ghc-pkg dot | tred | dot -Tpdf >pkgs.pdf
713 <term><literal>ghc-pkg dump</literal></term>
715 <para>Emit the full description of every package, in the
716 form of an <literal>InstalledPackageInfo</literal>.
717 Multiple package descriptions are separated by the
718 string <literal>---</literal> on a line by itself.</para>
720 <para>This is almost the same as <literal>ghc-pkg describe '*'</literal>, except that <literal>ghc-pkg dump</literal>
721 is intended for use by tools that parse the results, so
722 for example where <literal>ghc-pkg describe '*'</literal>
723 will emit an error if it can't find any packages that
724 match the pattern, <literal>ghc-pkg dump</literal> will
725 simply emit nothing.</para>
730 <term><literal>ghc-pkg recache</literal></term>
733 Re-creates the binary cache
734 file <filename>package.cache</filename> for the selected
735 database. This may be necessary if the cache has somehow
736 become out-of-sync with the contents of the database
737 (<literal>ghc-pkg</literal> will warn you if this might be
741 The other time when <literal>ghc-pkg recache</literal> is
742 useful is for registering packages manually: it is
743 possible to register a package by simply putting the
744 appropriate file in the package database directory and
745 invoking <literal>ghc-pkg recache</literal> to update the
746 cache. This method of registering packages may be more
747 convenient for automated packaging systems.
754 Substring matching is supported for <replaceable>M</replaceable> in
755 <literal>find-module</literal> and for <replaceable>P</replaceable> in
756 <literal>list</literal>, <literal>describe</literal>, and
757 <literal>field</literal>, where a <literal>'*'</literal> indicates open
758 substring ends (<literal>prefix*</literal>, <literal>*suffix</literal>,
759 <literal>*infix*</literal>). Examples (output omitted):
762 -- list all regex-related packages
763 ghc-pkg list '*regex*' --ignore-case
764 -- list all string-related packages
765 ghc-pkg list '*string*' --ignore-case
766 -- list OpenGL-related packages
767 ghc-pkg list '*gl*' --ignore-case
768 -- list packages exporting modules in the Data hierarchy
769 ghc-pkg find-module 'Data.*'
770 -- list packages exporting Monad modules
771 ghc-pkg find-module '*Monad*'
772 -- list names and maintainers for all packages
773 ghc-pkg field '*' name,maintainer
774 -- list location of haddock htmls for all packages
775 ghc-pkg field '*' haddock-html
776 -- dump the whole database
780 <para>Additionally, the following flags are accepted by
781 <literal>ghc-pkg</literal>:</para>
786 <option>––auto-ghci-libs</option><indexterm><primary><option>––auto-ghci-libs</option></primary>
790 <para>Automatically generate the GHCi
791 <filename>.o</filename> version of each
792 <filename>.a</filename> Haskell library, using GNU ld (if
793 that is available). Without this option,
794 <literal>ghc-pkg</literal> will warn if GHCi versions of
795 any Haskell libraries in the package don't exist.</para>
797 <para>GHCi <literal>.o</literal> libraries don't
798 necessarily have to live in the same directory as the
799 corresponding <literal>.a</literal> library. However,
800 this option will cause the GHCi library to be created in
801 the same directory as the <literal>.a</literal>
808 <option>-f</option> <replaceable>file</replaceable>
809 <indexterm><primary><option>-f</option></primary>
813 <option>-package-conf</option> <replaceable>file</replaceable>
814 <indexterm><primary><option>-package-conf</option></primary>
818 <para>Adds <replaceable>file</replaceable> to the stack of package
819 databases. Additionally, <replaceable>file</replaceable> will
820 also be the database modified by a <literal>register</literal>,
821 <literal>unregister</literal>, <literal>expose</literal> or
822 <literal>hide</literal> command, unless it is overridden by a later
823 <option>--package-conf</option>, <option>--user</option> or
824 <option>--global</option> option.</para>
830 <option>––force</option>
832 <option>––force</option>
833 </primary></indexterm>
836 <para>Causes <literal>ghc-pkg</literal> to ignore missing
837 dependencies, directories and libraries when registering a package,
838 and just go ahead and add it anyway. This might be useful if your
839 package installation system needs to add the package to
840 GHC before building and installing the files.</para>
846 <option>––global</option><indexterm><primary><option>––global</option></primary>
850 <para>Operate on the global package database (this is the default).
851 This flag affects the <literal>register</literal>,
852 <literal>update</literal>, <literal>unregister</literal>,
853 <literal>expose</literal>, and <literal>hide</literal>
860 <option>––help</option><indexterm><primary><option>––help</option></primary>
864 <option>-?</option><indexterm><primary><option>-?</option></primary>
868 <para>Outputs the command-line syntax.</para>
874 <option>––user</option><indexterm><primary><option>––user</option></primary>
878 <para>Operate on the current user's local package database.
879 This flag affects the <literal>register</literal>,
880 <literal>update</literal>, <literal>unregister</literal>,
881 <literal>expose</literal>, and <literal>hide</literal>
888 <option>-v</option><optional><replaceable>n</replaceable></optional><indexterm><primary><option>-v</option></primary><secondary>ghc-pkg
889 option</secondary></indexterm>
892 <option>--verbose</option><optional>=<replaceable>n</replaceable></optional><indexterm><primary><option>--verbose</option></primary><secondary>ghc-pkg option</secondary></indexterm>
896 Control verbosity. Verbosity levels range from 0-2, where
897 the default is 1, and <option>-v</option> alone selects
905 <option>-V</option><indexterm><primary><option>-V</option></primary>
909 <option>––version</option><indexterm><primary><option>––version</option></primary>
913 <para>Output the <literal>ghc-pkg</literal> version number.</para>
920 <sect2 id="building-packages">
921 <title>Building a package from Haskell source</title>
922 <indexterm><primary>packages</primary>
923 <secondary>building</secondary></indexterm>
925 <para>We don't recommend building packages the hard way. Instead, use the
926 <ulink url="../Cabal/index.html">Cabal</ulink> infrastructure
927 if possible. If your package is particularly complicated or requires a
928 lot of configuration, then you might have to fall back to the low-level
929 mechanisms, so a few hints for those brave souls follow.</para>
931 <para>You need to build an "installed package info" file for
932 passing to <literal>ghc-pkg</literal> when installing your
933 package. The contents of this file are described in
934 <xref linkend="installed-pkg-info" />.</para>
936 <para>The Haskell code in a package may be built into one or more
937 archive libraries (e.g. <filename>libHSfoo.a</filename>), or a
939 (e.g. <filename>libHSfoo.dll/.so/.dylib</filename>). The
940 restriction to a single shared object is because the package
941 system is used to tell the compiler when it should make an
942 inter-shared-object call rather than an intra-shared-object-call
943 call (inter-shared-object calls require an extra
946 <listitem><para>Building a static library is done by using the
947 <literal>ar</literal> tool, like so:</para>
949 <screen>ar cqs libHSfoo-1.0.a A.o B.o C.o ...</screen>
951 <para>where <filename>A.o</filename>,
952 <filename>B.o</filename> and so on are the compiled Haskell
953 modules, and <filename>libHSfoo.a</filename> is the library you
954 wish to create. The syntax may differ slightly on your system,
955 so check the documentation if you run into difficulties.</para>
958 <para>Versions of the Haskell libraries for use with GHCi may also
959 abe included: GHCi cannot load <literal>.a</literal> files
960 directly, instead it will look for an object file
961 called <filename>HSfoo.o</filename> and load that. On some
962 systems, the <literal>ghc-pkg</literal> tool can automatically
963 build the GHCi version of each library, see
964 <xref linkend="package-management"/>. To build these libraries
965 by hand from the <literal>.a</literal> archive, it is possible
966 to use GNU <command>ld</command> as follows:</para>
968 <screen>ld -r ––whole-archive -o HSfoo.o libHSfoo.a</screen>
971 <literal>––whole-archive</literal> with
972 <literal>–all_load</literal> on MacOS X)</para>
975 <para>When building the package as shared library, GHC can be used to
976 perform the link step. This hides some of the details
977 out the underlying linker and provides a common
978 interface to all shared object variants that are supported
979 by GHC (DLLs, ELF DSOs, and Mac OS dylibs). The shared
980 object must be named in specific way for two reasons: (1)
981 the name must contain the GHC compiler version, so that two
982 library variants don't collide that are compiled by
983 different versions of GHC and that therefore are most likely
984 incompatible with respect to calling conventions, (2) it
985 must be different from the static name otherwise we would
986 not be able to control the linker as precisely as necessary
988 the <option>-static</option>/<option>-dynamic</option> flags
989 work, see <xref linkend="options-linker" />.</para>
991 <screen>ghc -shared libHSfoo-1.0-ghc<replaceable>GHCVersion</replaceable>.so A.o B.o C.o</screen>
992 <para>Using GHC's version number in the shared object name
993 allows different library versions compiled by different GHC
994 versions to be installed in standard system locations,
995 e.g. under *nix /usr/lib. To obtain the version number of
996 GHC invoke <literal>ghc --numeric-version</literal> and use
998 of <replaceable>GHCVersion</replaceable>. See also
999 <xref linkend="options-codegen" /> on how object files must
1000 be prepared for shared object linking.</para>
1004 <para>To compile a module which is to be part of a new package,
1005 use the <literal>-package-name</literal> option (<xref linkend="using-packages"/>).
1006 Failure to use the <literal>-package-name</literal> option
1007 when compiling a package will probably result in disaster, but
1008 you will only discover later when you attempt to import modules
1009 from the package. At this point GHC will complain that the
1010 package name it was expecting the module to come from is not the
1011 same as the package name stored in the <literal>.hi</literal>
1014 <para>It is worth noting with shared objects, when each package
1015 is built as a single shared object file, since a reference to a shared object costs an extra
1016 indirection, intra-package references are cheaper than
1017 inter-package references. Of course, this applies to the
1018 <filename>main</filename> package as well.</para>
1021 <sect2 id="installed-pkg-info">
1023 <literal>InstalledPackageInfo</literal>: a package specification
1026 <para>A package specification is a Haskell record; in particular, it is the
1028 url="../libraries/Cabal/Distribution-InstalledPackageInfo.html#%tInstalledPackageInfo">InstalledPackageInfo</ulink> in the module Distribution.InstalledPackageInfo, which is part of the Cabal package distributed with GHC.</para>
1030 <para>An <literal>InstalledPackageInfo</literal> has a human
1031 readable/writable syntax. The functions
1032 <literal>parseInstalledPackageInfo</literal> and
1033 <literal>showInstalledPackageInfo</literal> read and write this syntax
1034 respectively. Here's an example of the
1035 <literal>InstalledPackageInfo</literal> for the <literal>unix</literal> package:</para>
1038 $ ghc-pkg describe unix
1041 id: unix-2.3.1.0-de7803f1a8cd88d2161b29b083c94240
1044 maintainer: libraries@haskell.org
1048 description: This package gives you access to the set of operating system
1049 services standardised by POSIX 1003.1b (or the IEEE Portable
1050 Operating System Interface for Computing Environments -
1053 The package is not supported under Windows (except under Cygwin).
1057 exposed-modules: System.Posix System.Posix.DynamicLinker.Module
1058 System.Posix.DynamicLinker.Prim System.Posix.Directory
1059 System.Posix.DynamicLinker System.Posix.Env System.Posix.Error
1060 System.Posix.Files System.Posix.IO System.Posix.Process
1061 System.Posix.Process.Internals System.Posix.Resource
1062 System.Posix.Temp System.Posix.Terminal System.Posix.Time
1063 System.Posix.Unistd System.Posix.User System.Posix.Signals
1064 System.Posix.Signals.Exts System.Posix.Semaphore
1065 System.Posix.SharedMem
1067 import-dirs: /usr/lib/ghc-6.12.1/unix-2.3.1.0
1068 library-dirs: /usr/lib/ghc-6.12.1/unix-2.3.1.0
1069 hs-libraries: HSunix-2.3.1.0
1070 extra-libraries: rt util dl
1071 extra-ghci-libraries:
1072 include-dirs: /usr/lib/ghc-6.12.1/unix-2.3.1.0/include
1073 includes: HsUnix.h execvpe.h
1074 depends: base-4.2.0.0-247bb20cde37c3ef4093ee124e04bc1c
1080 haddock-interfaces: /usr/share/doc/ghc/html/libraries/unix/unix.haddock
1081 haddock-html: /usr/share/doc/ghc/html/libraries/unix
1084 <para>Here is a brief description of the syntax of this file:</para>
1086 <para>A package description consists of a number of field/value pairs. A
1087 field starts with the field name in the left-hand column followed by a
1088 “<literal>:</literal>”, and the value continues until the next line that begins in the
1089 left-hand column, or the end of file.</para>
1091 <para>The syntax of the value depends on the field. The various field
1096 <term>freeform</term>
1098 <para>Any arbitrary string, no interpretation or parsing is
1105 <para>A sequence of non-space characters, or a sequence of arbitrary
1106 characters surrounded by quotes <literal>"...."</literal>.</para>
1110 <term>string list</term>
1112 <para>A sequence of strings, separated by commas. The sequence may
1118 <para>In addition, there are some fields with special syntax (e.g. package
1119 names, version, dependencies).</para>
1121 <para>The allowed fields, with their types, are:</para>
1126 <literal>name</literal>
1127 <indexterm><primary><literal>name</literal></primary><secondary>package specification</secondary></indexterm>
1130 <para>The package's name (without the version).</para>
1136 <literal>id</literal>
1137 <indexterm><primary><literal>id</literal></primary><secondary>package specification</secondary></indexterm>
1140 <para>The package's unique identifier. It is up to you to
1141 choose a suitable one.</para>
1147 <literal>version</literal>
1148 <indexterm><primary><literal>version</literal></primary><secondary>package specification</secondary></indexterm>
1151 <para>The package's version, usually in the form
1152 <literal>A.B</literal> (any number of components are allowed).</para>
1158 <literal>license</literal>
1159 <indexterm><primary><literal>auto</literal></primary><secondary>package specification</secondary></indexterm>
1162 <para>(string) The type of license under which this package is distributed.
1163 This field is a value of the <ulink
1164 url="../libraries/Cabal/Distribution-License.html#t:License"><literal>License</literal></ulink> type.</para>
1170 <literal>license-file</literal>
1171 <indexterm><primary><literal>license-file</literal></primary><secondary>package specification</secondary></indexterm>
1174 <para>(optional string) The name of a file giving detailed license
1175 information for this package.</para>
1181 <literal>copyright</literal>
1182 <indexterm><primary><literal>copyright</literal></primary><secondary>package specification</secondary></indexterm>
1185 <para>(optional freeform) The copyright string.</para>
1191 <literal>maintainer</literal>
1192 <indexterm><primary><literal>maintainer</literal></primary><secondary>package specification</secondary></indexterm>
1195 <para>(optinoal freeform) The email address of the package's maintainer.</para>
1201 <literal>stability</literal>
1202 <indexterm><primary><literal>stability</literal></primary><secondary>package specification</secondary></indexterm>
1205 <para>(optional freeform) A string describing the stability of the package
1206 (eg. stable, provisional or experimental).</para>
1212 <literal>homepage</literal>
1213 <indexterm><primary><literal>homepage</literal></primary><secondary>package specification</secondary></indexterm>
1216 <para>(optional freeform) URL of the package's home page.</para>
1222 <literal>package-url</literal>
1223 <indexterm><primary><literal>package-url</literal></primary><secondary>package specification</secondary></indexterm>
1226 <para>(optional freeform) URL of a downloadable distribution for this
1227 package. The distribution should be a Cabal package.</para>
1233 <literal>description</literal>
1234 <indexterm><primary><literal>description</literal></primary><secondary>package specification</secondary></indexterm>
1237 <para>(optional freeform) Description of the package.</para>
1243 <literal>category</literal>
1244 <indexterm><primary><literal>category</literal></primary><secondary>package specification</secondary></indexterm>
1247 <para>(optinoal freeform) Which category the package belongs to. This field
1248 is for use in conjunction with a future centralised package
1249 distribution framework, tentatively titled Hackage.</para>
1255 <literal>author</literal>
1256 <indexterm><primary><literal>author</literal></primary><secondary>package specification</secondary></indexterm>
1259 <para>(optional freeform) Author of the package.</para>
1265 <literal>exposed</literal>
1266 <indexterm><primary><literal>exposed</literal></primary><secondary>package specification</secondary></indexterm>
1269 <para>(bool) Whether the package is exposed or not.</para>
1275 <literal>exposed-modules</literal>
1276 <indexterm><primary><literal>exposed-modules</literal></primary><secondary>package specification</secondary></indexterm>
1279 <para>(string list) modules exposed by this package.</para>
1285 <literal>hidden-modules</literal>
1286 <indexterm><primary><literal>hidden-modules</literal></primary><secondary>package specification</secondary></indexterm>
1289 <para>(string list) modules provided by this package,
1290 but not exposed to the programmer. These modules cannot be
1291 imported, but they are still subject to the overlapping constraint:
1292 no other package in the same program may provide a module of the
1299 <literal>import-dirs</literal>
1300 <indexterm><primary><literal>import-dirs</literal></primary><secondary>package specification</secondary></indexterm>
1303 <para>(string list) A list of directories containing interface files
1304 (<literal>.hi</literal> files) for this package.</para>
1306 <para>If the package contains profiling libraries, then
1307 the interface files for those library modules should have
1308 the suffix <literal>.p_hi</literal>. So the package can
1309 contain both normal and profiling versions of the same
1310 library without conflict (see also
1311 <literal>library_dirs</literal> below).</para>
1317 <literal>library-dirs</literal>
1318 <indexterm><primary><literal>library-dirs</literal></primary><secondary>package specification</secondary></indexterm>
1321 <para>(string list) A list of directories containing libraries for this
1328 <literal>hs-libraries</literal>
1329 <indexterm><primary><literal>hs-libraries</literal></primary><secondary>package specification</secondary></indexterm>
1332 <para>(string list) A list of libraries containing Haskell code for this
1333 package, with the <literal>.a</literal> or
1334 <literal>.dll</literal> suffix omitted. When packages are
1335 built as libraries, the
1336 <literal>lib</literal> prefix is also omitted.</para>
1338 <para>For use with GHCi, each library should have an
1339 object file too. The name of the object file does
1340 <emphasis>not</emphasis> have a <literal>lib</literal>
1341 prefix, and has the normal object suffix for your
1344 <para>For example, if we specify a Haskell library as
1345 <filename>HSfoo</filename> in the package spec, then the
1346 various flavours of library that GHC actually uses will be
1350 <term><filename>libHSfoo.a</filename></term>
1352 <para>The name of the library on Unix and Windows
1353 (mingw) systems. Note that we don't support
1354 building dynamic libraries of Haskell code on Unix
1359 <term><filename>HSfoo.dll</filename></term>
1361 <para>The name of the dynamic library on Windows
1362 systems (optional).</para>
1366 <term><filename>HSfoo.o</filename></term>
1367 <term><filename>HSfoo.obj</filename></term>
1369 <para>The object version of the library used by
1379 <literal>extra-libraries</literal>
1380 <indexterm><primary><literal>extra-libraries</literal></primary><secondary>package specification</secondary></indexterm>
1383 <para>(string list) A list of extra libraries for this package. The
1384 difference between <literal>hs-libraries</literal> and
1385 <literal>extra-libraries</literal> is that
1386 <literal>hs-libraries</literal> normally have several
1387 versions, to support profiling, parallel and other build
1388 options. The various versions are given different
1389 suffixes to distinguish them, for example the profiling
1390 version of the standard prelude library is named
1391 <filename>libHSbase_p.a</filename>, with the
1392 <literal>_p</literal> indicating that this is a profiling
1393 version. The suffix is added automatically by GHC for
1394 <literal>hs-libraries</literal> only, no suffix is added
1396 <literal>extra-libraries</literal>.</para>
1398 <para>The libraries listed in
1399 <literal>extra-libraries</literal> may be any libraries
1400 supported by your system's linker, including dynamic
1401 libraries (<literal>.so</literal> on Unix,
1402 <literal>.DLL</literal> on Windows).</para>
1404 <para>Also, <literal>extra-libraries</literal> are placed
1405 on the linker command line after the
1406 <literal>hs-libraries</literal> for the same package. If
1407 your package has dependencies in the other direction (i.e.
1408 <literal>extra-libraries</literal> depends on
1409 <literal>hs-libraries</literal>), and the libraries are
1410 static, you might need to make two separate
1417 <literal>include-dirs</literal>
1418 <indexterm><primary><literal>include-dirs</literal></primary><secondary>package specification</secondary></indexterm>
1421 <para>(string list) A list of directories containing C includes for this
1428 <literal>includes</literal>
1429 <indexterm><primary><literal>includes</literal></primary><secondary>package specification</secondary></indexterm>
1432 <para>(string list) A list of files to include for via-C compilations
1433 using this package. Typically the include file(s) will
1434 contain function prototypes for any C functions used in
1435 the package, in case they end up being called as a result
1436 of Haskell functions from the package being
1443 <literal>depends</literal>
1444 <indexterm><primary><literal>depends</literal></primary><secondary>package specification</secondary></indexterm>
1447 <para>(package id list) Packages on which this package
1454 <literal>hugs-options</literal>
1455 <indexterm><primary><literal>hugs-options</literal></primary><secondary>package specification</secondary></indexterm>
1458 <para>(string list) Options to pass to Hugs for this package.</para>
1464 <literal>cc-options</literal>
1465 <indexterm><primary><literal>cc-options</literal></primary><secondary>package specification</secondary></indexterm>
1468 <para>(string list) Extra arguments to be added to the gcc command line
1469 when this package is being used (only for via-C
1470 compilations).</para>
1476 <literal>ld-options</literal>
1477 <indexterm><primary><literal>ld-options</literal></primary><secondary>package specification</secondary></indexterm>
1480 <para>(string list) Extra arguments to be added to the
1481 <command>gcc</command> command line (for linking) when
1482 this package is being used.</para>
1488 <literal>framework-dirs</literal>
1489 <indexterm><primary><literal>framework-dirs</literal></primary><secondary>package specification</secondary></indexterm>
1492 <para>(string list) On Darwin/MacOS X, a list of directories containing
1493 frameworks for this package. This corresponds to the
1494 <option>-framework-path</option> option. It is ignored on all other
1501 <literal>frameworks</literal>
1502 <indexterm><primary><literal>frameworks</literal></primary><secondary>package specification</secondary></indexterm>
1505 <para>(string list) On Darwin/MacOS X, a list of frameworks to link to. This
1506 corresponds to the <option>-framework</option> option. Take a look
1507 at Apple's developer documentation to find out what frameworks
1508 actually are. This entry is ignored on all other platforms.</para>
1514 <literal>haddock-interfaces</literal>
1515 <indexterm><primary><literal>haddock-interfaces</literal></primary><secondary>package specification</secondary></indexterm>
1518 <para>(string list) A list of filenames containing <ulink
1519 url="http://www.haskell.org/haddock/">Haddock</ulink> interface
1520 files (<literal>.haddock</literal> files) for this package.</para>
1526 <literal>haddock-html</literal>
1527 <indexterm><primary><literal>haddock-html</literal></primary><secondary>package specification</secondary></indexterm>
1530 <para>(optional string) The directory containing the Haddock-generated HTML
1531 for this package.</para>
1536 <!-- This isn't true any more. I'm not sure if we still need it -SDM
1538 The <literal>ghc-pkg</literal> tool performs expansion of
1539 environment variables occurring in input package specifications.
1540 So, if the <literal>mypkg</literal> was added to the package
1541 database as follows:
1544 $ installdir=/usr/local/lib ghc-pkg -a < mypkg.pkg
1548 The occurrence of <literal>${installdir}</literal> is replaced
1549 with <literal>/usr/local/lib</literal> in the package data that
1550 is added for <literal>mypkg</literal>.
1554 This feature enables the distribution of package specification
1555 files that can be easily configured when installing.
1558 <para>For examples of more package specifications, take a look
1559 at the <literal>package.conf</literal> in your GHC
1560 installation.</para>
1568 ;;; Local Variables: ***
1570 ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter" "sect1") ***