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