packages.xml 45.7 KB
Newer Older
1
<?xml version="1.0" encoding="iso-8859-1"?>
2
  <sect1 id="packages">
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
 <title>
Packages
 </title>
  <indexterm><primary>packages</primary></indexterm>
  
  <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>.</para>

  <para>Using a package couldn't be simpler: if you're using
    <option>--make</option> or GHCi, then most of the installed packages will be
    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
22
23
    few files in the right places, and you have a package.  See the
    <ulink url="../Cabal/index.html">Cabal documentation</ulink>
24
    for details, and also the Cabal libraries (<ulink url="../libraries/Cabal/Distribution-Simple.html">Distribution.Simple</ulink>,
25
26
27
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>
    
    <para>To see which packages are installed, use the
      <literal>ghc-pkg</literal> command:</para>
35

36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
<screen>
$ ghc-pkg list
/usr/lib/ghc-6.4/package.conf:
    base-1.0, haskell98-1.0, template-haskell-1.0, mtl-1.0, unix-1.0,
    Cabal-1.0, haskell-src-1.0, parsec-1.0, network-1.0,
    QuickCheck-1.0, HUnit-1.1, fgl-1.0, X11-1.1, HGL-3.1, OpenGL-2.0,
    GLUT-2.0, stm-1.0, readline-1.0, (lang-1.0), (concurrent-1.0),
    (posix-1.0), (util-1.0), (data-1.0), (text-1.0), (net-1.0),
    (hssource-1.0), rts-1.0
      </screen>

    <para>Packages are either exposed or hidden.  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>Each package has an exposed flag, which says whether it is exposed by
      default or not.  Packages hidden by default are listed in
      parentheses (eg. <literal>(lang-1.0)</literal>) in the output from
      <literal>ghc-pkg list</literal>.  To expose a package which is hidden by
      default, use the <option>-package</option>
      flag (see below).</para>
58
59
60
    
    <para>To see which modules are exposed by a package:</para>
    
61
62
63
64
65
66
67
68
<screen>
$ ghc-pkg field network exposed-modules
exposed-modules: Network.BSD,
                 Network.CGI,
                 Network.Socket,
                 Network.URI,
                 Network
</screen>
69

70
71
    <para>In general, packages containing hierarchical modules are usually
      exposed by default.  However, it is possible for two packages to contain
72
73
74
      the same module: in this case, only one of the packages should be
      exposed.  It is an error to import a module that belongs to more than one
      exposed package.</para>
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90

    <para>The GHC command line options that control packages are:</para>

    <variablelist>
      <varlistentry>
	<term>
	  <option>-package <replaceable>P</replaceable></option>
	  <indexterm><primary><option>-package</option></primary></indexterm>
	</term>
	<listitem>
	  <para>This option causes 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.</para>
91

92
93
	  <para>If there are multiple versions of <replaceable>P</replaceable>
	    installed, then all other versions will become hidden.</para>
94

95
96
97
98
99
100
101
102
	  <para>The <option>-package <replaceable>P</replaceable></option>
	    option also causes package <replaceable>P</replaceable> to be
	    linked into the resulting executable.  In
	    <option>&ndash;&ndash;make</option> mode and GHCi, 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.</para>
103

104
105
106
107
	  <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:  
108

109
<screen>$ ghc -o myprog Foo.o Main.o -package network</screen>
110

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

114
<screen>$ ghc -o myprog Foo.hs Main.hs -package network</screen>
115

116
117
118
	    In <literal>--make</literal> and <literal>--interactive</literal>
	    modes (<xref linkend="modes" />), however, GHC figures out the
	    packages required for linking without further assistance.</para>
119

120
121
122
123
124
125
126
127
128
	  <para>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>
	</listitem>
      </varlistentry>
      
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
      <varlistentry>
	<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.</para>
	</listitem>
      </varlistentry>

146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
      <varlistentry>
	<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>
      </varlistentry>
161

162
163
164
165
      <varlistentry>
	<term><option>-ignore-package</option> <replaceable>P</replaceable>
	<indexterm><primary><option>-ignore-package</option></primary>
	  </indexterm></term>
166
	<listitem>
167
	  <para>Causes the compiler to behave as if package
168
169
170
171
172
173
174
175
176
177
	    <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>
178
	</listitem>
179
180
181
      </varlistentry>
    </variablelist>
  </sect2>
182

183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
  <sect2 id="package-overlaps">
    <title>The module overlap restriction</title>

    <para>The module names in a Haskell program must be distinct.
      This doesn't sound like a severe restriction, but in a Haskell program
      using multiple packages with interdependencies, difficulties can start to
      arise.  You should be aware of what the module overlap
      restriction means, and how to avoid it.</para>

    <para>GHC knows which packages are <emphasis>in use</emphasis> by your
      program: a package is in use if you imported something from it, or if it
      is a dependency of some other package in use.  There must be no conflicts
      between the packages in use; a conflict is when two packages contain
      a module with the same name.  If
      GHC detects a conflict, it will issue a message stating which packages
      are in conflict, and which modules are overlapping.</para>

    <para>For example, a conflict might arise if you use two packages, say P
      and Q, which respectively depend on two different versions of another
      package, say <literal>R-1.0</literal> and <literal>R-2.0</literal>.  The
      two versions of <literal>R</literal> are likely to contain at least some
      of the same modules, so this situation would be a conflict.</para>
  </sect2>

207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
  <sect2 id="package-databases">
    <title>Package Databases</title>
      
    <para>A package database is a file, normally called
      <literal>package.conf</literal> which contains descriptions of installed
      packages.  GHC usually knows about two package databases:</para>

    <itemizedlist>
      <listitem>
	<para>The global package database, which comes with your GHC
	  installation.</para>
      </listitem>
      <listitem>
	<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</filename>, and on
	  Windows it will be something like
	  <filename>C:\Documents&nbsp;And&nbsp;Settings\<replaceable>user</replaceable>\ghc</filename>.
	  The <literal>ghc-pkg</literal> tool knows where this file should be
226
	  located, and will create it if it doesn't exist (see <xref linkend="package-management" />).</para>
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
      </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>
      flag.</para> 

    <para>Package databases may overlap: for example, packages in the user
      database will override those of the same name in the global
      database.</para> 

    <para>You can control the loading of package databses using the following
      GHC options:</para> 

    <variablelist>
      <varlistentry>
	<term>
	  <option>-package-conf <replaceable>file</replaceable></option>
	  <indexterm><primary><option>-package-conf</option></primary></indexterm>
	</term>
248
	<listitem>
249
250
251
252
253
	  <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>
254
	</listitem>
255
      </varlistentry>
256

257
258
259
260
261
      <varlistentry>
	<term><option>-no-user-package-conf</option>
	  <indexterm><primary><option>-no-user-package-conf</option></primary>
	  </indexterm>
	</term>
262
	<listitem>
263
264
265
266
267
268
269
270
271
272
273
	  <para>Prevent loading of the user's local package database.</para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>To create a new package database, just create
      a new file and put the string
      <quote><literal>[]</literal></quote> in it.  Packages can be
      added to the file using the
      <literal>ghc-pkg</literal> tool, described in <xref
      linkend="package-management"/>.</para>
274
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

    <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
	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>

      <para>If <literal>GHC_PACKAGE_PATH</literal> ends in a separator, then
	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):
<screen>
$ export GHC_PACKAGE_PATH=$HOME/.my-ghc-packages.conf:</screen>
	(use <literal>;</literal> instead of <literal>:</literal> on
	Windows).</para>

      <para>To check whether your <literal>GHC_PACKAGE_PATH</literal> setting
	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>
301
      
302
    </sect3>
303
304
305
306
307
308
309
310
  </sect2>

  <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
ross's avatar
ross committed
311
      <ulink url="../Cabal/index.html">Cabal</ulink> infrastructure
312
313
314
315
316
317
318
319
320
321
322
323
324
325
      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>
    
    <itemizedlist>
      <listitem>
	<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>
      </listitem>
      
      <listitem>
	<para>The Haskell code in a package may be built into one or
326
327
328
329
330
331
332
333
	  more archive libraries
	  (e.g. <filename>libHSfoo.a</filename>), or a single DLL on
	  Windows (e.g. <filename>HSfoo.dll</filename>).  The
	  restriction to a single DLL on Windows is because the
	  package system is used to tell the compiler when it should
	  make an inter-DLL call rather than an intra-DLL call
	  (inter-DLL calls require an extra
	  indirection). <emphasis>Building packages as DLLs doesn't
334
	  work at the moment; see <xref linkend="win32-dlls-create"/>
335
	  for the gory details.</emphasis>
rrt's avatar
rrt committed
336
	  </para>
337

338
	<para>Building a static library is done by using the
339
340
341
342
	  <literal>ar</literal> tool, like so:</para>

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

343
	<para>where <filename>A.o</filename>,
344
345
346
347
348
349
	  <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>

350
	<para>Versions of the Haskell libraries for use with GHCi
351
352
	  may also be included: GHCi cannot load <literal>.a</literal>
	  files directly, instead it will look for an object file
353
354
355
	  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
356
	  <xref linkend="package-management"/>.  To build these
357
358
359
	  libraries by hand from the <literal>.a</literal> archive, it
	  is possible to use GNU <command>ld</command> as
	  follows:</para>
360

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

363
	<para>(replace
364
365
          <literal>&ndash;&ndash;--whole-archive</literal> with
          <literal>&ndash;all_load</literal> on MacOS X)</para>
366
	
367
368
369
370
	  <para>GHC does not maintain detailed cross-package
          dependency information.  It does remember which modules in
          other packages the current module depends on, but not which
          things within those imported things.</para>
371
372
373
374
      </listitem>
    </itemizedlist>
    
    <para>It is worth noting that on Windows, when each package
rrt's avatar
rrt committed
375
      is built as a DLL, since a reference to a DLL costs an extra
376
377
378
379
      indirection, intra-package references are cheaper than
      inter-package references. Of course, this applies to the
      <filename>Main</filename> package as well.</para>
    </sect2>
380

381
382
383
384
385
386
387
  <sect2 id="package-management">
    <title>Package management (the <literal>ghc-pkg</literal> command)</title>
    <indexterm><primary>packages</primary>
      <secondary>management</secondary></indexterm>
    
    <para>The <literal>ghc-pkg</literal> tool allows packages to be
      added or removed from a package database.  By default,
388
      the system-wide package database is modified, but alternatively
389
390
391
      the user's local package database or another specified
      file can be used.</para>

392
393
394
395
396
397
398
399
400
401
402
403
404
405
    <para>To see what package databases are in use, say
      <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
	linkend="ghc-package-path" />, and using
	<literal>--package-conf</literal> options on the
	<literal>ghc-pkg</literal> command line.</para>

    <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>
406

407
408
409
410
411
412
413
414
415
    <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>

416
417
418
    <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
      full including the version number 
419
420
421
422
423
424
      (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>
425
426
427
428
429
430
431
432
433
434
435
436
437

    <variablelist>
      <varlistentry>
	<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
438
	    installed.</para>
439
440
	</listitem>
      </varlistentry>
441

442
443
444
445
446
447
448
449
      <varlistentry>
	<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>
      </varlistentry>
sof's avatar
sof committed
450

451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
      <varlistentry>
	<term><literal>ghc-pkg unregister <replaceable>P</replaceable></literal></term>
	<listitem>
	  <para>Remove the specified package from the database.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<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>
      </varlistentry>

      <varlistentry>
	<term><literal>ghc-pkg hide <replaceable>P</replaceable></literal></term>
	<listitem>
	  <para>Sets the <literal>exposed</literal> flag for package
	    <replaceable>P</replaceable> to <literal>False</literal>.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
475
	<term><literal>ghc-pkg list [<replaceable>P</replaceable>] [<option>--simple-output</option>]</literal></term>
476
477
478
479
	<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
480
481
	    user's local database, and any further files specified using the
	    <option>-f</option> option on the command line.</para>
482
483
484
485

	  <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>
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503

	  <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>
      </varlistentry>

      <varlistentry>
	<term><literal>ghc-pkg latest <replaceable>P</replaceable></literal></term>
	<listitem>
	  <para>Prints the latest available version of package
	    <replaceable>P</replaceable>.</para>
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
	</listitem>
      </varlistentry>

      <varlistentry>
	<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>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><literal>ghc-pkg field <replaceable>P</replaceable> <replaceable>field</replaceable></literal></term>
	<listitem>
	  <para>Show just a single field of the installed package description
	    for <literal>P</literal>.</para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>Additionally, the following flags are accepted by
      <literal>ghc-pkg</literal>:</para>

    <variablelist>
      <varlistentry>
	<term>
533
	  <option>&ndash;&ndash;auto-ghci-libs</option><indexterm><primary><option>&ndash;&ndash;auto-ghci-libs</option></primary>
534
535
536
537
	  </indexterm>
	</term>
	<listitem>
	  <para>Automatically generate the GHCi
538
539
540
541
542
543
544
545
546
547
548
549
	    <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>
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
	</listitem>
      </varlistentry>

      <varlistentry>
	<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>
565
566
567
568
569
570
571
	  <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 overriden by a later
	    <option>--package-conf</option>, <option>--user</option> or
	    <option>--global</option> option.</para>
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
	</listitem>
      </varlistentry>

      <varlistentry>
	<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>
      </varlistentry>

      <varlistentry>
	<term>
593
	  <option>&ndash;&ndash;global</option><indexterm><primary><option>&ndash;&ndash;global</option></primary>
594
595
596
597
598
599
600
601
602
603
604
605
606
	  </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>
      </varlistentry>

      <varlistentry>
	<term>
607
	  <option>&ndash;&ndash;help</option><indexterm><primary><option>&ndash;&ndash;help</option></primary>
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
	  </indexterm>
	</term>
	<term>
	  <option>-?</option><indexterm><primary><option>-?</option></primary>
	  </indexterm>
	</term>
	<listitem>
	  <para>Outputs the command-line syntax.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<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>
      </varlistentry>

      <varlistentry>
	<term>
	  <option>-V</option><indexterm><primary><option>-V</option></primary>
	  </indexterm>
	</term>
	<term>
639
	  <option>&ndash;&ndash;version</option><indexterm><primary><option>&ndash;&ndash;version</option></primary>
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
	  </indexterm>
	</term>
	<listitem>
	  <para>Output the <literal>ghc-pkg</literal> version number.</para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>When modifying the package database
      <replaceable>file</replaceable>, a copy of the original file is
      saved in <replaceable>file</replaceable><literal>.old</literal>,
      so in an emergency you can always restore the old settings by
      copying the old file back again.</para>

  </sect2>
  
  <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
663
	url="../libraries/Cabal/Distribution-InstalledPackageInfo.html#%tInstalledPackageInfo">InstalledPackageInfo</ulink> in the module Distribution.InstalledPackageInfo, which is part of the Cabal package distributed with GHC.</para>
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705

    <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
version: 1.0
license: BSD3
copyright:
maintainer: libraries@haskell.org
stability:
homepage:
package-url:
description:
category:
author:
exposed: True
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.Resource,
                 System.Posix.Temp,
                 System.Posix.Terminal,
                 System.Posix.Time,
                 System.Posix.Unistd,
                 System.Posix.User,
                 System.Posix.Signals.Exts
import-dirs: /usr/lib/ghc-6.4/libraries/unix
library-dirs: /usr/lib/ghc-6.4/libraries/unix
hs-libraries: HSunix
706
extra-libraries: HSunix_cbits, dl
707
708
709
710
711
include-dirs: /usr/lib/ghc-6.4/libraries/unix/include
includes: HsUnix.h
depends: base-1.0
</screen>

ross's avatar
ross committed
712
713
714
    <para>The full <ulink url="../Cabal/index.html">Cabal documentation</ulink>
      is still in preparation (at time of writing), so in the meantime
      here is a brief description of the syntax of this file:</para>
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782

    <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>
	<term>freeform</term>
	<listitem>
	  <para>Any arbitrary string, no interpretation or parsing is
	    done.</para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>string</term>
	<listitem>
	  <para>A sequence of non-space characters, or a sequence of arbitrary
	    characters surrounded by quotes <literal>"...."</literal>.</para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>string list</term>
	<listitem>
	  <para>A sequence of strings, separated by commas.  The sequence may
	    be empty.</para>
	</listitem>
      </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>
	
    <variablelist>
      <varlistentry>
	<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>
      </varlistentry>
      
      <varlistentry>
	<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>
      </varlistentry>
      
      <varlistentry>
	<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
783
	url="../libraries/Cabal/Distribution-License.html#t:License"><literal>License</literal></ulink> type.</para>
784
785
	</listitem>
      </varlistentry>
786

787
	<varlistentry>
788
	  <term>
789
790
            <literal>license-file</literal>
            <indexterm><primary><literal>license-file</literal></primary><secondary>package specification</secondary></indexterm>
791
          </term>
792
793
794
795
796
797
798
	  <listitem>
	    <para>(optional string) The name of a file giving detailed license
	    information for this package.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
799
	  <term>
800
801
            <literal>copyright</literal>
            <indexterm><primary><literal>copyright</literal></primary><secondary>package specification</secondary></indexterm>
802
          </term>
803
	  <listitem>
804
	    <para>(optional freeform) The copyright string.</para>
805
806
807
	  </listitem>
	</varlistentry>

808
	<varlistentry>
809
	  <term>
810
811
            <literal>maintainer</literal>
            <indexterm><primary><literal>maintainer</literal></primary><secondary>package specification</secondary></indexterm>
812
          </term>
813
814
815
816
817
818
	  <listitem>
	    <para>(optinoal freeform) The email address of the package's maintainer.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
819
	  <term>
820
821
            <literal>stability</literal>
            <indexterm><primary><literal>stability</literal></primary><secondary>package specification</secondary></indexterm>
822
          </term>
823
	  <listitem>
824
825
	    <para>(optional freeform) A string describing the stability of the package
	    (eg. stable, provisional or experimental).</para>
826
827
828
	  </listitem>
	</varlistentry>

829
	<varlistentry>
830
	  <term>
831
832
            <literal>homepage</literal>
            <indexterm><primary><literal>homepage</literal></primary><secondary>package specification</secondary></indexterm>
833
          </term>
834
835
836
837
838
839
840
841
842
	  <listitem>
	    <para>(optional freeform) URL of the package's home page.</para>
	  </listitem>
	</varlistentry>

      <varlistentry>
	<term>
            <literal>package-url</literal>
            <indexterm><primary><literal>package-url</literal></primary><secondary>package specification</secondary></indexterm>
843
          </term>
844
	  <listitem>
845
846
	    <para>(optional freeform) URL of a downloadable distribution for this
	    package.  The distribution should be a Cabal package.</para>
847
848
849
	  </listitem>
	</varlistentry>

850
	<varlistentry>
851
	  <term>
852
853
            <literal>description</literal>
            <indexterm><primary><literal>description</literal></primary><secondary>package specification</secondary></indexterm>
854
          </term>
855
856
857
858
859
860
	  <listitem>
	    <para>(optional freeform) Description of the package.</para>
	  </listitem>
	</varlistentry>

      <varlistentry>
861
	  <term>
862
863
            <literal>category</literal>
            <indexterm><primary><literal>category</literal></primary><secondary>package specification</secondary></indexterm>
864
          </term>
865
	  <listitem>
866
867
868
	    <para>(optinoal freeform) Which category the package belongs to.  This field
	    is for use in conjunction with a future centralised package
	    distribution framework, tentatively titled Hackage.</para>
869
870
	  </listitem>
	</varlistentry>
871

sof's avatar
sof committed
872
	<varlistentry>
873
	  <term>
874
875
            <literal>author</literal>
            <indexterm><primary><literal>author</literal></primary><secondary>package specification</secondary></indexterm>
876
          </term>
sof's avatar
sof committed
877
	  <listitem>
878
	    <para>(optional freeform) Author of the package.</para>
sof's avatar
sof committed
879
880
	  </listitem>
	</varlistentry>
881

882
	<varlistentry>
883
	  <term>
884
885
            <literal>exposed</literal>
            <indexterm><primary><literal>exposed</literal></primary><secondary>package specification</secondary></indexterm>
886
          </term>
887
	  <listitem>
888
	    <para>(bool) Whether the package is exposed or not.</para>
889
890
	  </listitem>
	</varlistentry>
891
892

	<varlistentry>
893
	  <term>
894
895
            <literal>exposed-modules</literal>
            <indexterm><primary><literal>exposed-modules</literal></primary><secondary>package specification</secondary></indexterm>
896
          </term>
897
	  <listitem>
898
	    <para>(string list) modules exposed by this package.</para>
899
900
901
	  </listitem>
	</varlistentry>

902
	<varlistentry>
903
	  <term>
904
905
            <literal>hidden-modules</literal>
            <indexterm><primary><literal>hidden-modules</literal></primary><secondary>package specification</secondary></indexterm>
906
          </term>
907
	  <listitem>
908
909
910
911
912
913
	    <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>
914
915
	</varlistentry>

916
	<varlistentry>
917
	  <term>
918
919
            <literal>import-dirs</literal>
            <indexterm><primary><literal>import-dirs</literal></primary><secondary>package specification</secondary></indexterm>
920
          </term>
921
	  <listitem>
922
	    <para>(string list) A list of directories containing interface files
923
	    (<literal>.hi</literal> files) for this package.</para>
924
925
926
927
928
929
930

	    <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>
931
932
933
	  </listitem>
	</varlistentry>

934
	<varlistentry>
935
	  <term>
936
937
            <literal>library-dirs</literal>
            <indexterm><primary><literal>library-dirs</literal></primary><secondary>package specification</secondary></indexterm>
938
          </term>
939
	  <listitem>
940
	    <para>(string list) A list of directories containing libraries for this
941
942
943
944
945
	    package.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
946
	  <term>
947
948
            <literal>hs-libraries</literal>
            <indexterm><primary><literal>hs-libraries</literal></primary><secondary>package specification</secondary></indexterm>
949
          </term>
950
	  <listitem>
951
	    <para>(string list) A list of libraries containing Haskell code for this
952
	    package, with the <literal>.a</literal> or
rrt's avatar
rrt committed
953
954
	    <literal>.dll</literal> suffix omitted.  When packages are
	    built as libraries, the
955
	    <literal>lib</literal> prefix is also omitted.</para>
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970

	    <para>For use with GHCi, each library should have an
	    object file too.  The name of the object file does
	    <emphasis>not</emphasis> have a <literal>lib</literal>
	    prefix, and has the normal object suffix for your
	    platform.</para>

	    <para>For example, if we specify a Haskell library as
	    <filename>HSfoo</filename> in the package spec, then the
	    various flavours of library that GHC actually uses will be
	    called:</para>
	    <variablelist>
	      <varlistentry>
		<term><filename>libHSfoo.a</filename></term>
		<listitem>
971
972
973
		  <para>The name of the library on Unix and Windows
		  (mingw) systems.  Note that we don't support
		  building dynamic libraries of Haskell code on Unix
974
975
976
977
978
979
980
		  systems.</para>
		</listitem>
	      </varlistentry>
	      <varlistentry>
		<term><filename>HSfoo.dll</filename></term>
		<listitem>
		  <para>The name of the dynamic library on Windows
981
		  systems (optional).</para>
982
983
984
985
986
987
988
989
990
991
992
		</listitem>
	      </varlistentry>
	      <varlistentry>
		<term><filename>HSfoo.o</filename></term>
		<term><filename>HSfoo.obj</filename></term>
		<listitem>
		  <para>The object version of the library used by
		  GHCi.</para>
		</listitem>
	      </varlistentry>
	    </variablelist>
993
994
995
996
	  </listitem>
	</varlistentry>

	<varlistentry>
997
	  <term>
998
999
            <literal>extra-libraries</literal>
            <indexterm><primary><literal>extra-libraries</literal></primary><secondary>package specification</secondary></indexterm>
1000
          </term>
For faster browsing, not all history is shown. View entire blame