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