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