packages.xml 69.7 KB
Newer Older
1
<?xml version="1.0" encoding="iso-8859-1"?>
2
  <sect1 id="packages">
3 4 5 6
 <title>
Packages
 </title>
  <indexterm><primary>packages</primary></indexterm>
7

8 9 10 11 12 13
  <para>A package is a library of Haskell modules known to the
    compiler.  GHC comes with several packages: see the accompanying
    <ulink url="../libraries/index.html">library
    documentation</ulink>.  More packages to install can be obtained
    from <ulink
    url="http://hackage.haskell.org/packages/hackage.html">HackageDB</ulink>.</para>
14 15

  <para>Using a package couldn't be simpler: if you're using
16
    <option>&ndash;&ndash;make</option> or GHCi, then most of the installed packages will be
17 18 19 20 21 22 23 24
    automatically available to your program without any further options.  The
    exceptions to this rule are covered below in <xref
      linkend="using-packages" />.</para>

  <para>Building your own packages is also quite straightforward: we provide
    the <ulink url="http://www.haskell.org/cabal/">Cabal</ulink> infrastructure which
    automates the process of configuring, building, installing and distributing
    a package.  All you need to do is write a simple configuration file, put a
ross's avatar
ross committed
25 26
    few files in the right places, and you have a package.  See the
    <ulink url="../Cabal/index.html">Cabal documentation</ulink>
27
    for details, and also the Cabal libraries (<ulink url="&libraryCabalLocation;/Distribution-Simple.html">Distribution.Simple</ulink>,
28 29 30 31 32 33 34
    for example).</para>

  <sect2 id="using-packages">
  <title>Using Packages
  </title>
    <indexterm><primary>packages</primary>
      <secondary>using</secondary></indexterm>
35

36 37
    <para>GHC only knows about packages that are
      <emphasis>installed</emphasis>. To see which packages are installed, use
38
      the <literal>ghc-pkg list</literal> command:</para>
39 40 41

<screen>
$ ghc-pkg list
42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102
/usr/lib/ghc-6.12.1/package.conf.d:
    Cabal-1.7.4
    array-0.2.0.1
    base-3.0.3.0
    base-4.2.0.0
    bin-package-db-0.0.0.0
    binary-0.5.0.1
    bytestring-0.9.1.4
    containers-0.2.0.1
    directory-1.0.0.2
    (dph-base-0.4.0)
    (dph-par-0.4.0)
    (dph-prim-interface-0.4.0)
    (dph-prim-par-0.4.0)
    (dph-prim-seq-0.4.0)
    (dph-seq-0.4.0)
    extensible-exceptions-0.1.1.0
    ffi-1.0
    filepath-1.1.0.1
    (ghc-6.12.1)
    ghc-prim-0.1.0.0
    haskeline-0.6.2
    haskell98-1.0.1.0
    hpc-0.5.0.2
    integer-gmp-0.1.0.0
    mtl-1.1.0.2
    old-locale-1.0.0.1
    old-time-1.0.0.1
    pretty-1.0.1.0
    process-1.0.1.1
    random-1.0.0.1
    rts-1.0
    syb-0.1.0.0
    template-haskell-2.4.0.0
    terminfo-0.3.1
    time-1.1.4
    unix-2.3.1.0
    utf8-string-0.3.4
</screen>

    <para>An installed package is either <emphasis>exposed</emphasis>
      or <emphasis>hidden</emphasis> by default.  Packages hidden by
      default are listed in parentheses
      (eg. <literal>(lang-1.0)</literal>), or possibly in blue if your
      terminal supports colour, in the output of <literal>ghc-pkg
      list</literal>.  Command-line flags, described below, allow you
      to expose a hidden package or hide an exposed one.  Only modules
      from exposed packages may be imported by your Haskell code; if
      you try to import a module from a hidden package, GHC will emit
      an error message.
    </para>

    <para>
      Note: if you're using Cabal, then the exposed or hidden status
      of a package is irrelevant: the available packages are instead
      determined by the dependencies listed in
      your <literal>.cabal</literal> specification.  The
      exposed/hidden status of packages is only relevant when
      using <literal>ghc</literal> or <literal>ghci</literal>
      directly.
    </para>
103

104 105 106 107 108 109 110
    <para>Similar to a package's hidden status is a package's trusted
      status. A package can be either trusted or not trusted (distrusted).
      By default packages are distrusted. This property of a package only
      plays a role when compiling code using GHC's Safe Haskell feature
      (see <xref linkend="safe-haskell"/>).
    </para>

111 112
    <para>To see which modules are provided by a package use the
      <literal>ghc-pkg</literal> command (see <xref linkend="package-management"/>):</para>
113

114 115 116 117 118 119 120 121 122
<screen>
$ ghc-pkg field network exposed-modules
exposed-modules: Network.BSD,
                 Network.CGI,
                 Network.Socket,
                 Network.URI,
                 Network
</screen>

123 124 125 126
    <para>The GHC command line options that control packages are:</para>

    <variablelist>
      <varlistentry>
127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166
        <term>
          <option>-package <replaceable>P</replaceable></option>
          <indexterm><primary><option>-package</option></primary></indexterm>
        </term>
        <listitem>
          <para>This option causes the installed
            package <replaceable>P</replaceable> to be exposed.  The
            package <replaceable>P</replaceable> can be specified in
            full with its version number
            (e.g. <literal>network-1.0</literal>) or the version
            number can be omitted if there is only one version of the
            package installed. If there are multiple versions
            of <replaceable>P</replaceable> installed, then all other
            versions will become hidden.</para>

          <para>The <option>-package <replaceable>P</replaceable></option>
            option also causes package <replaceable>P</replaceable> to
            be linked into the resulting executable or shared
            object. Whether a packages' library is linked statically
            or dynamically is controlled by the flag
            pair <option>-static</option>/<option>-dynamic</option>.</para>

          <para>In <option>&ndash;&ndash;make</option> mode
            and <option>&ndash;&ndash;interactive</option> mode (see
            <xref linkend="modes" />), the compiler normally
            determines which packages are required by the current
            Haskell modules, and links only those.  In batch mode
            however, the dependency information isn't available, and
            explicit
            <option>-package</option> options must be given when linking. The one other time you might need to use
            <option>-package</option> to force linking a package is
            when the package does not contain any Haskell modules (it
            might contain a C library only, for example).  In that
            case, GHC will never discover a dependency on it, so it
            has to be mentioned explicitly.</para>

          <para>For example, to link a program consisting of objects
            <filename>Foo.o</filename> and <filename>Main.o</filename>, where
            we made use of the <literal>network</literal> package, we need to
            give GHC the <literal>-package</literal> flag thus:
167

168
<screen>$ ghc -o myprog Foo.o Main.o -package network</screen>
169

170 171
            The same flag is necessary even if we compiled the modules from
            source, because GHC still reckons it's in batch mode:
172

173
<screen>$ ghc -o myprog Foo.hs Main.hs -package network</screen></para>
174
        </listitem>
175
      </varlistentry>
176

177 178
      <varlistentry>
        <term>
179 180 181 182
          <option>-package-id <replaceable>P</replaceable></option>
          <indexterm><primary><option>-package-id</option></primary></indexterm>
        </term>
        <listitem>
183 184 185 186 187 188 189 190 191 192
          <para>
            Exposes a package like <option>-package</option>, but the
            package is named by its ID rather than by name.  This is a
            more robust way to name packages, and can be used to
            select packages that would otherwise be shadowed.  Cabal
            passes <option>-package-id</option> flags to GHC.
          </para>
        </listitem>
      </varlistentry>

193
      <varlistentry>
194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210
        <term><option>-hide-all-packages</option>
        <indexterm><primary><option>-hide-package</option></primary>
          </indexterm></term>
        <listitem>
          <para>Ignore the exposed flag on installed packages, and hide them
            all by default.  If you use
            this flag, then any packages you require (including
            <literal>base</literal>) need to be explicitly exposed using
            <option>-package</option> options.</para>

          <para>This is a good way to insulate your program from
            differences in the globally exposed packages, and being
            explicit about package dependencies is a Good Thing.
            Cabal always passes the
            <option>-hide-all-packages</option> flag to GHC, for
            exactly this reason.</para>
        </listitem>
211 212
      </varlistentry>

213
      <varlistentry>
214 215 216 217 218 219 220 221 222 223 224 225 226
        <term><option>-hide-package</option> <replaceable>P</replaceable>
        <indexterm><primary><option>-hide-package</option></primary>
          </indexterm></term>
        <listitem>
          <para>This option does the opposite of <option>-package</option>: it
            causes the specified package to be <firstterm>hidden</firstterm>,
            which means that none of its modules will be available for import
            by Haskell <literal>import</literal> directives.</para>

          <para>Note that the package might still end up being linked into the
            final program, if it is a dependency (direct or indirect) of
            another exposed package.</para>
        </listitem>
227
      </varlistentry>
228

229
      <varlistentry>
230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245
        <term><option>-ignore-package</option> <replaceable>P</replaceable>
        <indexterm><primary><option>-ignore-package</option></primary>
          </indexterm></term>
        <listitem>
          <para>Causes the compiler to behave as if package
            <replaceable>P</replaceable>, and any packages that depend on
            <literal>P</literal>, are not installed at all.</para>

          <para>Saying <literal>-ignore-package P</literal> is the same as
            giving <literal>-hide-package</literal> flags for
            <literal>P</literal> and all the packages that depend on
            <literal>P</literal>.  Sometimes we don't know ahead of time which
            packages will be installed that depend on <literal>P</literal>,
            which is when the <literal>-ignore-package</literal> flag can be
            useful.</para>
        </listitem>
246
      </varlistentry>
247

248 249 250 251 252 253 254 255 256 257 258
      <varlistentry>
        <term><option>-no-auto-link-packages</option>
        <indexterm><primary><option>-no-auto-link-packages</option></primary>
          </indexterm></term>
        <listitem>
          <para>By default, GHC will automatically link in the
            <literal>haskell98</literal> package. This flag disables that
            behaviour.</para>
        </listitem>
      </varlistentry>

259
      <varlistentry>
260 261 262 263 264 265 266 267
        <term><option>-package-name</option> <replaceable>foo</replaceable>
        <indexterm><primary><option>-package-name</option></primary>
          </indexterm></term>
        <listitem>
          <para>Tells GHC the the module being compiled forms part of
            package <replaceable>foo</replaceable>.
            If this flag is omitted (a very common case) then the
            default package <literal>main</literal> is assumed.</para>
268
            <para>Note: the argument to <option>-package-name</option>
269 270 271
              should be the full
              package <literal>name-version</literal> for the package.
              For example:
272
            <literal>-package mypkg-1.2</literal>.</para>
273
        </listitem>
274
      </varlistentry>
275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321

      <varlistentry>
        <term><option>-trust</option> <replaceable>P</replaceable>
        <indexterm><primary><option>-trust</option></primary>
          </indexterm></term>
        <listitem>
          <para>This option causes the install package <replaceable>P
            </replaceable> to be both exposed and trusted by GHC. This
            command functions in the in a very similar way to the <option>
            -package</option> command but in addition sets the selected
            packaged to be trusted by GHC, regardless of the contents of
            the package database. (see <xref linkend="safe-haskell"/>).
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>-distrust</option> <replaceable>P</replaceable>
        <indexterm><primary><option>-distrust</option></primary>
          </indexterm></term>
        <listitem>
          <para>This option causes the install package <replaceable>P
            </replaceable> to be both exposed and distrusted by GHC. This
            command functions in the in a very similar way to the <option>
            -package</option> command but in addition sets the selected
            packaged to be distrusted by GHC, regardless of the contents of
            the package database. (see <xref linkend="safe-haskell"/>).
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>-distrust-all</option>
        <indexterm><primary><option>-distrust-all</option></primary>
          </indexterm></term>
        <listitem>
          <para>Ignore the trusted flag on installed packages, and distrust
            them by default. If you use this flag and Safe Haskell then any
            packages you require to be trusted (including <literal>base
            </literal>) need to be explicitly trusted using <option>-trust
            </option> options. This option does not change the exposed/hidden
            status of a package, so it isn't equivalent to applying <option>
            -distrust</option> to all packages on the system. (see
            <xref linkend="safe-haskell"/>).
          </para>
        </listitem>
      </varlistentry>
322
    </variablelist>
323 324 325 326 327
  </sect2>

  <sect2 id="package-main">
    <title>The main package</title>

328 329
  <para>Every complete Haskell program must define <literal>main</literal> in
   module <literal>Main</literal>
330 331 332 333 334 335 336 337 338
   in package <literal>main</literal>.   (Omitting the <option>-package-name</option> flag compiles
   code for package <literal>main</literal>.) Failure to do so leads to a somewhat obscure
   link-time error of the form:
<programlisting>
/usr/bin/ld: Undefined symbols:
_ZCMain_main_closure
</programlisting>
</para>

339
  </sect2>
340

341
  <sect2 id="package-overlaps">
342
    <title>Consequences of packages for the Haskell language</title>
Simon Marlow's avatar
Simon Marlow committed
343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366

    <para>It is possible that by using packages you might end up with
    a program that contains two modules with the same name: perhaps
    you used a package P that has a <emphasis>hidden</emphasis> module
    M, and there is also a module M in your program.  Or perhaps the
    dependencies of packages that you used contain some overlapping
    modules.  Perhaps the program even contains multiple versions of a
    certain package, due to dependencies from other packages.</para>

    <para>None of these scenarios gives rise to an error on its
    own<footnote><para>it used to in GHC 6.4, but not since
    6.6</para></footnote>, but they may have some interesting
    consequences.  For instance, if you have a type
    <literal>M.T</literal> from version 1 of package
    <literal>P</literal>, then this is <emphasis>not</emphasis> the
    same as the type <literal>M.T</literal> from version 2 of package
    <literal>P</literal>, and GHC will report an error if you try to
    use one where the other is expected.</para>

    <para>Formally speaking, in Haskell 98, an entity (function, type
    or class) in a program is uniquely identified by the pair of the
    module name in which it is defined and its name.  In GHC, an
    entity is uniquely defined by a triple: package, module, and
    name.</para>
367 368
  </sect2>

369 370
  <sect2 id="package-databases">
    <title>Package Databases</title>
371

372 373 374 375 376 377 378 379 380 381 382 383 384 385 386
    <para>
      A package database is where the details about installed packages
      are stored.  It is a directory, usually
      called <literal>package.conf.d</literal>, that contains a file
      for each package, together with a binary cache of the package
      data in the file <literal>package.cache</literal>.  Normally
      you won't need to look at or modify the contents of a package
      database directly; all management of package databases can be
      done through the <literal>ghc-pkg</literal> tool (see
      <xref linkend="package-management" />).
    </para>

    <para>
      GHC knows about two package databases in particular:
    </para>
387 388 389

    <itemizedlist>
      <listitem>
390 391 392
        <para>The global package database, which comes with your GHC
          installation,
          e.g. <filename>/usr/lib/ghc-6.12.1/package.conf.d</filename>.</para>
393 394
      </listitem>
      <listitem>
395 396 397 398 399 400 401
        <para>A package database private to each user.  On Unix
          systems this will be
          <filename>$HOME/.ghc/<replaceable>arch</replaceable>-<replaceable>os</replaceable>-<replaceable>version</replaceable>/package.conf.d</filename>, and on
          Windows it will be something like
          <filename>C:\Documents&nbsp;And&nbsp;Settings\<replaceable>user</replaceable>\ghc\package.conf.d</filename>.
          The <literal>ghc-pkg</literal> tool knows where this file should be
          located, and will create it if it doesn't exist (see <xref linkend="package-management" />).</para>
402 403 404 405 406 407
      </listitem>
    </itemizedlist>

    <para>When GHC starts up, it reads the contents of these two package
      databases, and builds up a list of the packages it knows about.  You can
      see GHC's package table by running GHC with the <option>-v</option>
408
      flag.</para>
409

410 411 412
    <para>Package databases may overlap: for example, packages in the
      user database will override (<emphasis>shadow</emphasis>) those
      of the same name and version in the global database.</para>
413

414
    <para>You can control the loading of package databases using the following
415
      GHC options:</para>
416 417 418

    <variablelist>
      <varlistentry>
419 420 421 422 423 424 425 426 427 428 429
        <term>
          <option>-package-conf <replaceable>file</replaceable></option>
          <indexterm><primary><option>-package-conf</option></primary></indexterm>
        </term>
        <listitem>
          <para>Read in the package configuration file
            <replaceable>file</replaceable> in addition to the system
            default file and the user's local file.  Packages in additional
            files read this way will override those in the global and user
            databases.</para>
        </listitem>
430
      </varlistentry>
431

432
      <varlistentry>
433 434 435 436 437 438 439
        <term><option>-no-user-package-conf</option>
          <indexterm><primary><option>-no-user-package-conf</option></primary>
          </indexterm>
        </term>
        <listitem>
          <para>Prevent loading of the user's local package database.</para>
        </listitem>
440 441 442
      </varlistentry>
    </variablelist>

443 444 445 446 447 448
    <sect3 id="ghc-package-path">
      <title>The <literal>GHC_PACKAGE_PATH</literal> environment variable</title>
      <indexterm><primary>Environment variable</primary><secondary><literal>GHC_PACKAGE_PATH</literal></secondary>
      </indexterm>
      <indexterm><primary><literal>GHC_PACKAGE_PATH</literal></primary></indexterm>
      <para>The <literal>GHC_PACKAGE_PATH</literal> environment variable may be
449 450 451 452 453 454 455
        set to a <literal>:</literal>-separated (<literal>;</literal>-separated
        on Windows) list of files containing package databases.  This list of
        package databases is used by GHC and ghc-pkg, with earlier databases in
        the list overriding later ones.  This order was chosen to match the
        behaviour of the <literal>PATH</literal> environment variable; think of
        it as a list of package databases that are searched left-to-right for
        packages.</para>
456 457

      <para>If <literal>GHC_PACKAGE_PATH</literal> ends in a separator, then
458 459 460
        the default user and system package databases are appended, in that
        order. e.g. to augment the usual set of packages with a database of
        your own, you could say (on Unix):
461 462
<screen>
$ export GHC_PACKAGE_PATH=$HOME/.my-ghc-packages.conf:</screen>
463 464
        (use <literal>;</literal> instead of <literal>:</literal> on
        Windows).</para>
465 466

      <para>To check whether your <literal>GHC_PACKAGE_PATH</literal> setting
467 468 469
        is doing the right thing, <literal>ghc-pkg list</literal> will list all
        the databases in use, in the reverse order they are searched.</para>

470
    </sect3>
471 472
  </sect2>

473 474
  <sect2 id="package-ids">
    <title>Package IDs, dependencies, and broken packages</title>
475

476 477 478 479 480 481
    <para>Each installed package has a unique identifier (the
      &ldquo;installed package ID&rdquo;, or just &ldquo;package
      ID&rdquo; for short) , which distinguishes it from all other
      installed packages on the system.  To see the package IDs
      associated with each installed package, use <literal>ghc-pkg
      list -v</literal>:</para>
482

483 484 485 486 487 488 489 490 491 492
    <screen>
$ ghc-pkg list -v
using cache: /usr/lib/ghc-6.12.1/package.conf.d/package.cache
/usr/lib/ghc-6.12.1/package.conf.d
   Cabal-1.7.4 (Cabal-1.7.4-48f5247e06853af93593883240e11238)
   array-0.2.0.1 (array-0.2.0.1-9cbf76a576b6ee9c1f880cf171a0928d)
   base-3.0.3.0 (base-3.0.3.0-6cbb157b9ae852096266e113b8fac4a2)
   base-4.2.0.0 (base-4.2.0.0-247bb20cde37c3ef4093ee124e04bc1c)
   ...
</screen>
493

494
    <para>
495 496 497 498 499 500 501
      The string in parentheses after the package name is the package
      ID: it normally begins with the package name and version, and
      ends in a hash string derived from the compiled package.
      Dependencies between packages are expressed in terms of package
      IDs, rather than just packages and versions.  For example, take
      a look at the dependencies of the <literal>haskell98</literal>
      package:
502
    </para>
503

504 505 506 507 508 509 510 511 512 513
    <screen>
$ ghc-pkg field haskell98 depends
depends: array-0.2.0.1-9cbf76a576b6ee9c1f880cf171a0928d
         base-4.2.0.0-247bb20cde37c3ef4093ee124e04bc1c
         directory-1.0.0.2-f51711bc872c35ce4a453aa19c799008
         old-locale-1.0.0.1-d17c9777c8ee53a0d459734e27f2b8e9
         old-time-1.0.0.1-1c0d8ea38056e5087ef1e75cb0d139d1
         process-1.0.1.1-d8fc6d3baf44678a29b9d59ca0ad5780
         random-1.0.0.1-423d08c90f004795fd10e60384ce6561
</screen>
514

515
    <para>
516 517 518
      The purpose of the package ID is to detect problems caused by
      re-installing a package without also recompiling the packages
      that depend on it.  Recompiling dependencies is necessary,
daniel.is.fischer's avatar
daniel.is.fischer committed
519
      because the newly compiled package may have a different ABI
520 521 522 523 524 525 526 527 528 529 530 531 532
      (Application Binary Interface) than the previous version, even
      if both packages were built from the same source code using the
      same compiler.  With package IDs, a recompiled
      package will have a different package ID from the previous
      version, so packages that depended on the previous version are
      now orphaned - one of their dependencies is not satisfied.
      Packages that are broken in this way are shown in
      the <literal>ghc-pkg list</literal> output either in red (if
      possible) or otherwise surrounded by braces.  In the following
      example, we have recompiled and reinstalled
      the <literal>filepath</literal> package, and this has caused
      various dependencies including <literal>Cabal</literal> to
      break:</para>
533

534 535 536 537 538 539 540 541 542
    <screen>
$ ghc-pkg list
WARNING: there are broken packages.  Run 'ghc-pkg check' for more details.
/usr/lib/ghc-6.12.1/package.conf.d:
    {Cabal-1.7.4}
    array-0.2.0.1
    base-3.0.3.0
    ... etc ...
</screen>
543

544 545 546 547 548 549
    <para>
      Additionally, <literal>ghc-pkg list</literal> reminds you that
      there are broken packages and suggests <literal>ghc-pkg
      check</literal>, which displays more information about the
      nature of the failure:
    </para>
550

551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574
    <screen>
$ ghc-pkg check
There are problems in package ghc-6.12.1:
  dependency "filepath-1.1.0.1-87511764eb0af2bce4db05e702750e63" doesn't exist
There are problems in package haskeline-0.6.2:
  dependency "filepath-1.1.0.1-87511764eb0af2bce4db05e702750e63" doesn't exist
There are problems in package Cabal-1.7.4:
  dependency "filepath-1.1.0.1-87511764eb0af2bce4db05e702750e63" doesn't exist
There are problems in package process-1.0.1.1:
  dependency "filepath-1.1.0.1-87511764eb0af2bce4db05e702750e63" doesn't exist
There are problems in package directory-1.0.0.2:
  dependency "filepath-1.1.0.1-87511764eb0af2bce4db05e702750e63" doesn't exist

The following packages are broken, either because they have a problem
listed above, or because they depend on a broken package.
ghc-6.12.1
haskeline-0.6.2
Cabal-1.7.4
process-1.0.1.1
directory-1.0.0.2
bin-package-db-0.0.0.0
hpc-0.5.0.2
haskell98-1.0.1.0
</screen>
Simon Marlow's avatar
Simon Marlow committed
575

576 577 578 579 580 581 582 583 584 585 586 587 588 589
    <para>
      To fix the problem, you need to recompile the broken packages
      against the new dependencies.  The easiest way to do this is to
      use <literal>cabal-install</literal>, or download the packages
      from <ulink
    url="http://hackage.haskell.org/packages/hackage.html">HackageDB</ulink>
      and build and install them as normal.</para>

    <para>Be careful not to recompile any packages that GHC itself
      depends on, as this may render the <literal>ghc</literal>
      package itself broken, and <literal>ghc</literal> cannot be
      simply recompiled.  The only way to recover from this would be
      to re-install GHC.</para>
  </sect2>
590

591 592 593 594
  <sect2 id="package-management">
    <title>Package management (the <literal>ghc-pkg</literal> command)</title>
    <indexterm><primary>packages</primary>
      <secondary>management</secondary></indexterm>
595

596 597 598
    <para>The <literal>ghc-pkg</literal> tool is for querying and
      modifying package databases.  To see what package databases are
      in use, use
599 600 601
      <literal>ghc-pkg&nbsp;list</literal>.  The stack of databases that
      <literal>ghc-pkg</literal> knows about can be modified using the
      <literal>GHC_PACKAGE_PATH</literal> environment variable (see <xref
602 603 604
        linkend="ghc-package-path" />, and using
        <literal>--package-conf</literal> options on the
        <literal>ghc-pkg</literal> command line.</para>
605 606 607 608 609 610 611

    <para>When asked to modify a database, <literal>ghc-pkg</literal> modifies
      the global database by default.  Specifying <option>--user</option>
      causes it to act on the user database, or <option>--package-conf</option>
      can be used to act on another database entirely.  When multiple of these
      options are given, the rightmost one is used as the database to act
      upon.</para>
612

613
   <para>Commands that query the package database (list, latest,
614
     describe, field, dot) operate on the list of databases specified by
615 616 617 618 619
     the flags <option>--user</option>, <option>--global</option>, and
     <option>--package-conf</option>.  If none of these flags are
     given, the default is <option>--global</option>
     <option>--user</option>.</para>

620 621 622 623 624 625 626 627 628
    <para>If the environment variable <literal>GHC_PACKAGE_PATH</literal> is
      set, and its value does not end in a separator (<literal>:</literal> on
      Unix, <literal>;</literal> on Windows), then the last database is
      considered to be the global database, and will be modified by default by
      <literal>ghc-pkg</literal>.  The intention here is that
      <literal>GHC_PACKAGE_PATH</literal> can be used to create a virtual
      package environment into which Cabal packages can be installed without
      setting anything other than <literal>GHC_PACKAGE_PATH</literal>.</para>

629 630
    <para>The <literal>ghc-pkg</literal> program may be run in the ways listed
      below.  Where a package name is required, the package can be named in
631
      full including the version number
632 633 634 635 636 637
      (e.g. <literal>network-1.0</literal>), or without the version number.
      Naming a package without the version number matches all versions of the
      package; the specified action will be applied to all the matching
      packages.  A package specifier that matches all version of the package
      can also be written <replaceable>pkg</replaceable><literal>-*</literal>,
      to make it clearer that multiple packages are being matched.</para>
638 639

    <variablelist>
640 641 642 643 644 645 646 647 648
      <varlistentry>
        <term><literal>ghc-pkg init <replaceable>path</replaceable></literal></term>
        <listitem>
          <para>Creates a new, empty, package database
            at <replaceable>path</replaceable>, which must not already
            exist.</para>
        </listitem>
      </varlistentry>

649
      <varlistentry>
650 651 652 653 654 655 656 657 658 659 660 661
        <term><literal>ghc-pkg register <replaceable>file</replaceable></literal></term>
        <listitem>
          <para>Reads a package specification from
            <replaceable>file</replaceable> (which may be &ldquo;<literal>-</literal>&rdquo;
            to indicate standard input),
            and adds it to the database of installed packages.  The syntax of
            <replaceable>file</replaceable> is given in <xref
              linkend="installed-pkg-info" />.</para>

          <para>The package specification must be a package that isn't already
            installed.</para>
        </listitem>
662
      </varlistentry>
663

664
      <varlistentry>
665 666 667 668 669 670
        <term><literal>ghc-pkg update <replaceable>file</replaceable></literal></term>
        <listitem>
          <para>The same as <literal>register</literal>, except that if a
            package of the same name is already installed, it is
            replaced by the new one.</para>
        </listitem>
671
      </varlistentry>
sof's avatar
sof committed
672

673
      <varlistentry>
674 675 676 677
        <term><literal>ghc-pkg unregister <replaceable>P</replaceable></literal></term>
        <listitem>
          <para>Remove the specified package from the database.</para>
        </listitem>
678 679
      </varlistentry>

680 681 682 683 684 685 686 687 688
      <varlistentry>
        <term><literal>ghc-pkg check</literal></term>
        <listitem>
          <para>Check consistency of dependencies in the package
          database, and report packages that have missing
          dependencies.</para>
        </listitem>
      </varlistentry>

689
      <varlistentry>
690 691 692 693 694
        <term><literal>ghc-pkg expose <replaceable>P</replaceable></literal></term>
        <listitem>
          <para>Sets the <literal>exposed</literal> flag for package
            <replaceable>P</replaceable> to <literal>True</literal>.</para>
        </listitem>
695 696
      </varlistentry>

697
      <varlistentry>
698
        <term><literal>ghc-pkg hide <replaceable>P</replaceable></literal></term>
699
        <listitem>
700 701
          <para>Sets the <literal>exposed</literal> flag for package
            <replaceable>P</replaceable> to <literal>False</literal>.</para>
702 703 704
        </listitem>
      </varlistentry>

705
      <varlistentry>
706
        <term><literal>ghc-pkg trust <replaceable>P</replaceable></literal></term>
707
        <listitem>
708 709 710 711 712 713 714 715 716
          <para>Sets the <literal>trusted</literal> flag for package
            <replaceable>P</replaceable> to <literal>True</literal>.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><literal>ghc-pkg distrust <replaceable>P</replaceable></literal></term>
        <listitem>
          <para>Sets the <literal>trusted</literal> flag for package
717 718
            <replaceable>P</replaceable> to <literal>False</literal>.</para>
        </listitem>
719 720 721
      </varlistentry>

      <varlistentry>
722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743
        <term><literal>ghc-pkg list [<replaceable>P</replaceable>] [<option>--simple-output</option>]</literal></term>
        <listitem>
          <para>This option displays the currently installed
            packages, for each of the databases known to
            <literal>ghc-pkg</literal>.  That includes the global database, the
            user's local database, and any further files specified using the
            <option>-f</option> option on the command line.</para>

          <para>Hidden packages (those for which the <literal>exposed</literal>
            flag is <literal>False</literal>) are shown in parentheses in the
            list of packages.</para>

          <para>If an optional package identifier <replaceable>P</replaceable>
            is given, then only packages matching that identifier are
            shown.</para>

          <para>If the option <option>--simple-output</option> is given, then
            the packages are listed on a single line separated by spaces, and
            the database names are not included.  This is intended to make it
            easier to parse the output of <literal>ghc-pkg list</literal> using
            a script.</para>
        </listitem>
744 745
      </varlistentry>

746
      <varlistentry>
747 748 749
        <term><literal>ghc-pkg find-module <replaceable>M</replaceable> [<option>--simple-output</option>]</literal></term>
        <listitem>
    <para>This option lists registered packages exposing module
750 751 752 753 754 755 756 757 758 759 760 761
      <replaceable>M</replaceable>. Examples:</para>
<screen>
$ ghc-pkg find-module Var
c:/fptools/validate/ghc/driver/package.conf.inplace:
    (ghc-6.9.20080428)

$ ghc-pkg find-module Data.Sequence
c:/fptools/validate/ghc/driver/package.conf.inplace:
    containers-0.1
</screen>
  <para>Otherwise, it behaves like <literal>ghc-pkg list</literal>,
  including options.</para>
762
        </listitem>
763 764 765
      </varlistentry>


766
      <varlistentry>
767 768 769 770 771
        <term><literal>ghc-pkg latest <replaceable>P</replaceable></literal></term>
        <listitem>
          <para>Prints the latest available version of package
            <replaceable>P</replaceable>.</para>
        </listitem>
772 773 774
      </varlistentry>

      <varlistentry>
775 776 777 778 779 780 781
        <term><literal>ghc-pkg describe <replaceable>P</replaceable></literal></term>
        <listitem>
          <para>Emit the full description of the specified package.  The
            description is in the form of an
            <literal>InstalledPackageInfo</literal>, the same as the input file
            format for <literal>ghc-pkg register</literal>.  See <xref
              linkend="installed-pkg-info" /> for details.</para>
782 783 784 785

          <para>If the pattern matches multiple packages, the
            description for each package is emitted, separated by the
            string <literal>---</literal> on a line by itself.</para>
786
        </listitem>
787 788 789
      </varlistentry>

      <varlistentry>
790 791 792 793
        <term><literal>ghc-pkg field <replaceable>P</replaceable> <replaceable>field</replaceable>[,<replaceable>field</replaceable>]*</literal></term>
        <listitem>
          <para>Show just a single field of the installed package description
      for <literal>P</literal>. Multiple fields can be selected by separating
794
      them with commas</para>
795
        </listitem>
796
      </varlistentry>
797

798 799 800 801 802 803 804 805 806 807 808 809 810
      <varlistentry>
        <term><literal>ghc-pkg dot</literal></term>
        <listitem>
          <para>
            Generate a graph of the package dependencies in a form
            suitable for input for the <ulink url="http://www.graphviz.org/">graphviz</ulink> tools.  For example,
            to generate a PDF of the dependency graph:</para>
<screen>
ghc-pkg dot | tred | dot -Tpdf >pkgs.pdf
</screen>
        </listitem>
      </varlistentry>

811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826
      <varlistentry>
        <term><literal>ghc-pkg dump</literal></term>
        <listitem>
          <para>Emit the full description of every package, in the
            form of an <literal>InstalledPackageInfo</literal>.
            Multiple package descriptions are separated by the
            string <literal>---</literal> on a line by itself.</para>

          <para>This is almost the same as <literal>ghc-pkg describe '*'</literal>, except that <literal>ghc-pkg dump</literal>
            is intended for use by tools that parse the results, so
            for example where <literal>ghc-pkg describe '*'</literal>
            will emit an error if it can't find any packages that
            match the pattern, <literal>ghc-pkg dump</literal> will
            simply emit nothing.</para>
        </listitem>
      </varlistentry>
827 828 829 830 831 832 833 834 835 836 837

      <varlistentry>
        <term><literal>ghc-pkg recache</literal></term>
        <listitem>
          <para>
            Re-creates the binary cache
            file <filename>package.cache</filename> for the selected
            database.  This may be necessary if the cache has somehow
            become out-of-sync with the contents of the database
            (<literal>ghc-pkg</literal> will warn you if this might be
            the case).</para>
838

839 840 841 842 843 844 845 846 847 848 849
          <para>
            The other time when <literal>ghc-pkg recache</literal> is
            useful is for registering packages manually: it is
            possible to register a package by simply putting the
            appropriate file in the package database directory and
            invoking <literal>ghc-pkg recache</literal> to update the
            cache.  This method of registering packages may be more
            convenient for automated packaging systems.
          </para>
        </listitem>
      </varlistentry>
850 851
    </variablelist>

852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876
    <para>
      Substring matching is supported for <replaceable>M</replaceable> in
      <literal>find-module</literal> and for <replaceable>P</replaceable> in
      <literal>list</literal>, <literal>describe</literal>, and
      <literal>field</literal>, where a <literal>'*'</literal> indicates open
      substring ends (<literal>prefix*</literal>, <literal>*suffix</literal>,
      <literal>*infix*</literal>). Examples (output omitted):
    </para>
    <screen>
    -- list all regex-related packages
    ghc-pkg list '*regex*' --ignore-case
    -- list all string-related packages
    ghc-pkg list '*string*' --ignore-case
    -- list OpenGL-related packages
    ghc-pkg list '*gl*' --ignore-case
    -- list packages exporting modules in the Data hierarchy
    ghc-pkg find-module 'Data.*'
    -- list packages exporting Monad modules
    ghc-pkg find-module '*Monad*'
    -- list names and maintainers for all packages
    ghc-pkg field '*' name,maintainer
    -- list location of haddock htmls for all packages
    ghc-pkg field '*' haddock-html
    -- dump the whole database
    ghc-pkg describe '*'
877
</screen>
878

879 880 881 882 883
    <para>Additionally, the following flags are accepted by
      <literal>ghc-pkg</literal>:</para>

    <variablelist>
      <varlistentry>
884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902
        <term>
          <option>&ndash;&ndash;auto-ghci-libs</option><indexterm><primary><option>&ndash;&ndash;auto-ghci-libs</option></primary>
          </indexterm>
        </term>
        <listitem>
          <para>Automatically generate the GHCi
            <filename>.o</filename> version of each
            <filename>.a</filename> Haskell library, using GNU ld (if
            that is available).  Without this option,
            <literal>ghc-pkg</literal> will warn if GHCi versions of
            any Haskell libraries in the package don't exist.</para>

            <para>GHCi <literal>.o</literal> libraries don't
            necessarily have to live in the same directory as the
            corresponding <literal>.a</literal> library.  However,
            this option will cause the GHCi library to be created in
            the same directory as the <literal>.a</literal>
            library.</para>
        </listitem>
903 904 905
      </varlistentry>

      <varlistentry>
906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924
        <term>
          <option>-f</option> <replaceable>file</replaceable>
          <indexterm><primary><option>-f</option></primary>
          </indexterm>
        </term>
        <term>
          <option>-package-conf</option> <replaceable>file</replaceable>
          <indexterm><primary><option>-package-conf</option></primary>
          </indexterm>
        </term>
        <listitem>
          <para>Adds <replaceable>file</replaceable> to the stack of package
            databases.  Additionally, <replaceable>file</replaceable> will
            also be the database modified by a <literal>register</literal>,
            <literal>unregister</literal>, <literal>expose</literal> or
            <literal>hide</literal> command, unless it is overridden by a later
            <option>--package-conf</option>, <option>--user</option> or
            <option>--global</option> option.</para>
        </listitem>
925 926 927
      </varlistentry>

      <varlistentry>
928 929 930 931 932 933 934 935 936 937 938 939 940
        <term>
          <option>&ndash;&ndash;force</option>
          <indexterm><primary>
              <option>&ndash;&ndash;force</option>
            </primary></indexterm>
        </term>
        <listitem>
          <para>Causes <literal>ghc-pkg</literal> to ignore missing
            dependencies, directories and libraries when registering a package,
            and just go ahead and add it anyway.  This might be useful if your
            package installation system needs to add the package to
            GHC before building and installing the files.</para>
        </listitem>
941 942 943
      </varlistentry>

      <varlistentry>
944 945 946 947 948 949 950 951 952 953 954
        <term>
          <option>&ndash;&ndash;global</option><indexterm><primary><option>&ndash;&ndash;global</option></primary>
          </indexterm>
        </term>
        <listitem>
          <para>Operate on the global package database (this is the default).
            This flag affects the <literal>register</literal>,
            <literal>update</literal>, <literal>unregister</literal>,
            <literal>expose</literal>, and <literal>hide</literal>
            commands.</para>
        </listitem>
955 956 957
      </varlistentry>

      <varlistentry>
958 959 960 961 962 963 964 965 966 967 968
        <term>
          <option>&ndash;&ndash;help</option><indexterm><primary><option>&ndash;&ndash;help</option></primary>
          </indexterm>
        </term>
        <term>
          <option>-?</option><indexterm><primary><option>-?</option></primary>
          </indexterm>
        </term>
        <listitem>
          <para>Outputs the command-line syntax.</para>
        </listitem>
969 970 971
      </varlistentry>

      <varlistentry>
972 973 974 975 976 977 978 979 980 981 982
        <term>
          <option>&ndash;&ndash;user</option><indexterm><primary><option>&ndash;&ndash;user</option></primary>
          </indexterm>
        </term>
        <listitem>
          <para>Operate on the current user's local package database.
            This flag affects the <literal>register</literal>,
            <literal>update</literal>, <literal>unregister</literal>,
            <literal>expose</literal>, and <literal>hide</literal>
            commands.</para>
        </listitem>
983 984
      </varlistentry>

985 986
      <varlistentry>
        <term>
987
          <option>-v</option><optional><replaceable>n</replaceable></optional><indexterm><primary><option>-v</option></primary><secondary>ghc-pkg
988 989 990 991 992 993 994 995 996 997 998 999
              option</secondary></indexterm>
        </term>
        <term>
          <option>--verbose</option><optional>=<replaceable>n</replaceable></optional><indexterm><primary><option>--verbose</option></primary><secondary>ghc-pkg option</secondary></indexterm>
        </term>
        <listitem>
          <para>
            Control verbosity.  Verbosity levels range from 0-2, where
            the default is 1, and <option>-v</option> alone selects
            level 2.
          </para>
        </listitem>
1000
      </varlistentry>
1001

1002
      <varlistentry>
1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013
        <term>
          <option>-V</option><indexterm><primary><option>-V</option></primary>
          </indexterm>
        </term>
        <term>
          <option>&ndash;&ndash;version</option><indexterm><primary><option>&ndash;&ndash;version</option></primary>
          </indexterm>
        </term>
        <listitem>
          <para>Output the <literal>ghc-pkg</literal> version number.</para>
        </listitem>
1014 1015 1016 1017
      </varlistentry>
    </variablelist>

  </sect2>
1018

1019 1020 1021 1022 1023 1024 1025 1026 1027 1028
  <sect2 id="building-packages">
    <title>Building a package from Haskell source</title>
    <indexterm><primary>packages</primary>
      <secondary>building</secondary></indexterm>

    <para>We don't recommend building packages the hard way.  Instead, use the
      <ulink url="../Cabal/index.html">Cabal</ulink> infrastructure
      if possible.  If your package is particularly complicated or requires a
      lot of configuration, then you might have to fall back to the low-level
      mechanisms, so a few hints for those brave souls follow.</para>
1029

1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045
    <para>You need to build an "installed package info" file for
      passing to <literal>ghc-pkg</literal> when installing your
      package.  The contents of this file are described in
      <xref linkend="installed-pkg-info" />.</para>

    <para>The Haskell code in a package may be built into one or more
      archive libraries (e.g. <filename>libHSfoo.a</filename>), or a
      single shared object
      (e.g. <filename>libHSfoo.dll/.so/.dylib</filename>).  The
      restriction to a single shared object is because the package
      system is used to tell the compiler when it should make an
      inter-shared-object call rather than an intra-shared-object-call
      call (inter-shared-object calls require an extra
      indirection).</para>
    <itemizedlist>
      <listitem><para>Building a static library is done by using the
1046
          <literal>ar</literal> tool, like so:</para>
1047 1048 1049

<screen>ar cqs libHSfoo-1.0.a A.o B.o C.o ...</screen>

1050 1051 1052 1053 1054
          <para>where <filename>A.o</filename>,
            <filename>B.o</filename> and so on are the compiled Haskell
            modules, and <filename>libHSfoo.a</filename> is the library you
            wish to create.  The syntax may differ slightly on your system,
            so check the documentation if you run into difficulties.</para>
1055 1056
      </listitem>
      <listitem>
1057
        <para>Versions of the Haskell libraries for use with GHCi may also
daniel.is.fischer's avatar
daniel.is.fischer committed
1058
          be included: GHCi cannot load <literal>.a</literal> files
1059 1060 1061 1062 1063 1064 1065
          directly, instead it will look for an object file
          called <filename>HSfoo.o</filename> and load that.  On some
          systems, the <literal>ghc-pkg</literal> tool can automatically
          build the GHCi version of each library, see
          <xref linkend="package-management"/>.  To build these libraries
          by hand from the <literal>.a</literal> archive, it is possible
          to use GNU <command>ld</command> as follows:</para>
1066 1067 1068

<screen>ld -r &ndash;&ndash;whole-archive -o HSfoo.o libHSfoo.a</screen>

1069 1070 1071
        <para>(replace
          <literal>&ndash;&ndash;whole-archive</literal> with
          <literal>&ndash;all_load</literal> on MacOS X)</para>
1072 1073
      </listitem>
      <listitem>
1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088
        <para>When building the package as shared library, GHC can be used to
          perform the link step. This hides some of the details
          out the underlying linker and provides a common
          interface to all shared object variants that are supported
          by GHC (DLLs, ELF DSOs, and Mac OS dylibs). The shared
          object must be named in specific way for two reasons: (1)
          the name must contain the GHC compiler version, so that two
          library variants don't collide that are compiled by
          different versions of GHC and that therefore are most likely
          incompatible with respect to calling conventions, (2) it
          must be different from the static name otherwise we would
          not be able to control the linker as precisely as necessary
          to make
          the <option>-static</option>/<option>-dynamic</option> flags
          work, see <xref linkend="options-linker" />.</para>
1089 1090

<screen>ghc -shared libHSfoo-1.0-ghc<replaceable>GHCVersion</replaceable>.so A.o B.o C.o</screen>
1091 1092 1093 1094 1095 1096 1097 1098 1099
        <para>Using GHC's version number in the shared object name
          allows different library versions compiled by different GHC
          versions to be installed in standard system locations,
          e.g. under *nix /usr/lib. To obtain the version number of
          GHC invoke <literal>ghc --numeric-version</literal> and use
          its output in place
          of <replaceable>GHCVersion</replaceable>. See also
          <xref linkend="options-codegen" /> on how object files must
          be prepared for shared object linking.</para>
1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119
      </listitem>
    </itemizedlist>

     <para>To compile a module which is to be part of a new package,
      use the <literal>-package-name</literal> option (<xref linkend="using-packages"/>).
      Failure to use the <literal>-package-name</literal> option
      when compiling a package will probably result in disaster, but
      you will only discover later when you attempt to import modules
      from the package.  At this point GHC will complain that the
      package name it was expecting the module to come from is not the
      same as the package name stored in the <literal>.hi</literal>
      file.</para>

    <para>It is worth noting with shared objects, when each package
      is built as a single shared object file, since a reference to a shared object costs an extra
      indirection, intra-package references are cheaper than
      inter-package references. Of course, this applies to the
      <filename>main</filename> package as well.</para>
    </sect2>

1120 1121 1122 1123 1124 1125 1126
  <sect2 id="installed-pkg-info">
    <title>
      <literal>InstalledPackageInfo</literal>: a package specification
    </title>

    <para>A package specification is a Haskell record; in particular, it is the
      record <ulink
1127
        url="&libraryCabalLocation;/Distribution-InstalledPackageInfo.html#%tInstalledPackageInfo">InstalledPackageInfo</ulink> in the module Distribution.InstalledPackageInfo, which is part of the Cabal package distributed with GHC.</para>
1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138

    <para>An <literal>InstalledPackageInfo</literal> has a human
      readable/writable syntax.  The functions
      <literal>parseInstalledPackageInfo</literal> and
      <literal>showInstalledPackageInfo</literal> read and write this syntax
      respectively.  Here's an example of the
      <literal>InstalledPackageInfo</literal> for the <literal>unix</literal> package:</para>

<screen>
$ ghc-pkg describe unix
name: unix
1139 1140
version: 2.3.1.0
id: unix-2.3.1.0-de7803f1a8cd88d2161b29b083c94240
1141 1142 1143 1144 1145 1146
license: BSD3
copyright:
maintainer: libraries@haskell.org
stability:
homepage:
package-url:
1147 1148 1149 1150 1151 1152 1153
description: This package gives you access to the set of operating system
             services standardised by POSIX 1003.1b (or the IEEE Portable
             Operating System Interface for Computing Environments -
             IEEE Std. 1003.1).
             .
             The package is not supported under Windows (except under Cygwin).
category: System
1154 1155
author:
exposed: True
1156 1157 1158 1159 1160 1161 1162 1163 1164 1165
exposed-modules: System.Posix System.Posix.DynamicLinker.Module
                 System.Posix.DynamicLinker.Prim System.Posix.Directory
                 System.Posix.DynamicLinker System.Posix.Env System.Posix.Error
                 System.Posix.Files System.Posix.IO System.Posix.Process
                 System.Posix.Process.Internals System.Posix.Resource
                 System.Posix.Temp System.Posix.Terminal System.Posix.Time
                 System.Posix.Unistd System.Posix.User System.Posix.Signals
                 System.Posix.Signals.Exts System.Posix.Semaphore
                 System.Posix.SharedMem
hidden-modules:
1166
trusted: False
1167 1168 1169 1170 1171 1172 1173 1174 1175 1176 1177 1178 1179 1180 1181
import-dirs: /usr/lib/ghc-6.12.1/unix-2.3.1.0
library-dirs: /usr/lib/ghc-6.12.1/unix-2.3.1.0
hs-libraries: HSunix-2.3.1.0
extra-libraries: rt util dl
extra-ghci-libraries:
include-dirs: /usr/lib/ghc-6.12.1/unix-2.3.1.0/include
includes: HsUnix.h execvpe.h
depends: base-4.2.0.0-247bb20cde37c3ef4093ee124e04bc1c
hugs-options:
cc-options:
ld-options:
framework-dirs:
frameworks:
haddock-interfaces: /usr/share/doc/ghc/html/libraries/unix/unix.haddock
haddock-html: /usr/share/doc/ghc/html/libraries/unix
1182 1183
</screen>

1184
    <para>Here is a brief description of the syntax of this file:</para>
1185 1186 1187 1188 1189 1190 1191 1192 1193 1194 1195

    <para>A package description consists of a number of field/value pairs.  A
      field starts with the field name in the left-hand column followed by a
      &ldquo;<literal>:</literal>&rdquo;, and the value continues until the next line that begins in the
      left-hand column, or the end of file.</para>

    <para>The syntax of the value depends on the field.   The various field
      types are:</para>

    <variablelist>
      <varlistentry>
1196 1197 1198 1199 1200
        <term>freeform</term>
        <listitem>
          <para>Any arbitrary string, no interpretation or parsing is
            done.</para>
        </listitem>
1201 1202
      </varlistentry>
      <varlistentry>
1203 1204 1205 1206 1207
        <term>string</term>
        <listitem>
          <para>A sequence of non-space characters, or a sequence of arbitrary
            characters surrounded by quotes <literal>"...."</literal>.</para>
        </listitem>
1208 1209
      </varlistentry>
      <varlistentry>
1210 1211 1212 1213 1214
        <term>string list</term>
        <listitem>
          <para>A sequence of strings, separated by commas.  The sequence may
            be empty.</para>
        </listitem>
1215 1216 1217 1218 1219 1220 1221
      </varlistentry>
    </variablelist>

    <para>In addition, there are some fields with special syntax (e.g. package
      names, version, dependencies).</para>

    <para>The allowed fields, with their types, are:</para>
1222

1223 1224
    <variablelist>
      <varlistentry>
1225 1226 1227 1228 1229 1230 1231
        <term>
          <literal>name</literal>
          <indexterm><primary><literal>name</literal></primary><secondary>package specification</secondary></indexterm>
        </term>
        <listitem>
          <para>The package's name (without the version).</para>
        </listitem>
1232
      </varlistentry>
1233

1234
      <varlistentry>
1235 1236 1237 1238 1239 1240 1241 1242
        <term>
          <literal>id</literal>
          <indexterm><primary><literal>id</literal></primary><secondary>package specification</secondary></indexterm>
        </term>
        <listitem>
          <para>The package ID.  It is up to you to choose a suitable
          one.</para>
        </listitem>
1243
      </varlistentry>
1244

1245
      <varlistentry>
1246 1247 1248 1249 1250 1251 1252 1253
        <term>
          <literal>version</literal>
          <indexterm><primary><literal>version</literal></primary><secondary>package specification</secondary></indexterm>
        </term>
        <listitem>
          <para>The package's version, usually in the form
            <literal>A.B</literal> (any number of components are allowed).</para>
        </listitem>
1254
      </varlistentry>
1255

1256
      <varlistentry>
1257 1258 1259 1260 1261 1262 1263 1264 1265
        <term>
          <literal>license</literal>
          <indexterm><primary><literal>auto</literal></primary><secondary>package specification</secondary></indexterm>
        </term>
        <listitem>
          <para>(string) The type of license under which this package is distributed.
            This field is a value of the <ulink
        url="&libraryCabalLocation;/Distribution-License.html#t:License"><literal>License</literal></ulink> type.</para>
        </listitem>
1266
      </varlistentry>
1267

1268 1269
        <varlistentry>
          <term>
1270 1271
            <literal>license-file</literal>
            <indexterm><primary><literal>license-file</literal></primary><secondary>package specification</secondary></indexterm>
1272
          </term>
1273 1274 1275 1276 1277 1278 1279 1280
          <listitem>
            <para>(optional string) The name of a file giving detailed license
            information for this package.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
1281 1282
            <literal>copyright</literal>
            <indexterm><primary><literal>copyright</literal></primary><secondary>package specification</secondary></indexterm>
1283
          </term>
1284 1285 1286 1287
          <listitem>
            <para>(optional freeform) The copyright string.</para>
          </listitem>
        </varlistentry>
1288

1289 1290
        <varlistentry>
          <term>
1291 1292
            <literal>maintainer</literal>
            <indexterm><primary><literal>maintainer</literal></primary><secondary>package specification</secondary></indexterm>
1293
          </term>
1294
          <listitem>
daniel.is.fischer's avatar
daniel.is.fischer committed
1295
            <para>(optional freeform) The email address of the package's maintainer.</para>
1296 1297
          </listitem>
        </varlistentry>
1298

1299 1300
        <varlistentry>
          <term>
1301 1302
            <literal>stability</literal>
            <indexterm><primary><literal>stability</literal></primary><secondary>package specification</secondary></indexterm>
1303
          </term>
1304 1305 1306 1307 1308 1309 1310 1311
          <listitem>
            <para>(optional freeform) A string describing the stability of the package
            (eg. stable, provisional or experimental).</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
1312 1313
            <literal>homepage</literal>
            <indexterm><primary><literal>homepage</literal></primary><secondary>package specification</secondary></indexterm>
1314
          </term>
1315 1316 1317 1318
          <listitem>
            <para>(optional freeform) URL of the package's home page.</para>
          </listitem>
        </varlistentry>
1319 1320

      <varlistentry>
1321
        <term>
1322 1323
            <literal>package-url</literal>
            <indexterm><primary><literal>package-url</literal></primary><secondary>package specification</secondary></indexterm>
1324
          </term>
1325 1326 1327 1328 1329 1330 1331 1332
          <listitem>
            <para>(optional freeform) URL of a downloadable distribution for this
            package.  The distribution should be a Cabal package.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
1333 1334
            <literal>description</literal>
            <indexterm><primary><literal>description</literal></primary><secondary>package specification</secondary></indexterm>
1335
          </term>
1336 1337 1338 1339
          <listitem>
            <para>(optional freeform) Description of the package.</para>
          </listitem>
        </varlistentry>
1340 1341

      <varlistentry>
1342
          <term>
1343 1344
            <literal>category</literal>
            <indexterm><primary><literal>category</literal></primary><secondary>package specification</secondary></indexterm>
1345
          </term>
1346
          <listitem>
daniel.is.fischer's avatar
daniel.is.fischer committed
1347
            <para>(optional freeform) Which category the package belongs to.  This field
1348 1349 1350 1351 1352 1353 1354
            is for use in conjunction with a future centralised package
            distribution framework, tentatively titled Hackage.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
1355 1356
            <literal>author</literal>
            <indexterm><primary><literal>author</literal></primary><secondary>package specification</secondary></indexterm>
1357
          </term>
1358 1359 1360 1361
          <listitem>
            <para>(optional freeform) Author of the package.</para>
          </listitem>
        </varlistentry>
1362

1363 1364
        <varlistentry>
          <term>
1365 1366
            <literal>exposed</literal>
            <indexterm><primary><literal>exposed</literal></primary><secondary>package specification</secondary></indexterm>
1367
          </term>
1368 1369 1370 1371
          <listitem>
            <para>(bool) Whether the package is exposed or not.</para>
          </listitem>
        </varlistentry>
1372

1373 1374
        <varlistentry>
          <term>
1375 1376
            <literal>exposed-modules</literal>
            <indexterm><primary><literal>exposed-modules</literal></primary><secondary>package specification</secondary></indexterm>
1377
          </term>
1378 1379 1380 1381
          <listitem>
            <para>(string list) modules exposed by this package.</para>
          </listitem>
        </varlistentry>
1382

1383 1384
        <varlistentry>
          <term>
1385 1386
            <literal>hidden-modules</literal>
            <indexterm><primary><literal>hidden-modules</literal></primary><secondary>package specification</secondary></indexterm>
1387
          </term>
1388 1389 1390 1391 1392 1393 1394 1395 1396
          <listitem>
            <para>(string list) modules provided by this package,
            but not exposed to the programmer.  These modules cannot be
            imported, but they are still subject to the overlapping constraint:
            no other package in the same program may provide a module of the
            same name.</para>
        </listitem>
        </varlistentry>

1397 1398 1399 1400 1401 1402 1403 1404 1405 1406
        <varlistentry>
          <term>
            <literal>trusted</literal>
            <indexterm><primary><literal>trusted</literal></primary><secondary>package specification</secondary></indexterm>
          </term>
          <listitem>
            <para>(bool) Whether the package is trusted or not.</para>
          </listitem>
        </varlistentry>

1407 1408
        <varlistentry>
          <term>
1409 1410
            <literal>import-dirs</literal>
            <indexterm><primary><literal>import-dirs</literal></primary><secondary>package specification</secondary></indexterm>
1411
          </term>
1412 1413 1414 1415 1416 1417 1418 1419 1420 1421 1422 1423 1424 1425 1426
          <listitem>
            <para>(string list) A list of directories containing interface files
            (<literal>.hi</literal> files) for this package.</para>

            <para>If the package contains profiling libraries, then
            the interface files for those library modules should have
            the suffix <literal>.p_hi</literal>.  So the package can
            contain both normal and profiling versions of the same
            library without conflict (see also
            <literal>library_dirs</literal> below).</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
1427 1428
            <literal>library-dirs</literal>
            <indexterm><primary><literal>library-dirs</literal></primary><secondary>package specification</secondary></indexterm>