b75a6d8f7e8abe41677aec98568a5d4e48ed4797
[ghc-hetmet.git] / ghc / docs / users_guide / packages.sgml
1   <sect1 id="packages">
2     <title>Packages</title>
3     <indexterm><primary>packages</primary></indexterm>
4
5     <para>Packages are collections of libraries, conveniently grouped
6     together as a single entity.  The package system is flexible: a
7     package may consist of Haskell code, foreign language code (eg. C
8     libraries), or a mixture of the two.  A package is a good way to
9     group together related Haskell modules, and is essential if you
10     intend to make the modules into a Windows DLL (see below).</para>
11
12     <para>Because packages can contain both Haskell and C libraries, they
13     are also a good way to provide convenient access to a Haskell
14     layer over a C library.</para>
15
16     <para>GHC comes with several packages (see <xref
17     linkend="book-hslibs">), and packages can be added to or removed
18     from an existing GHC installation, using the supplied
19     <literal>ghc-pkg</literal><indexterm><primary><literal>ghc-pkg</literal></primary>
20     </indexterm> tool, described in <xref
21     linkend="package-management">.</para>
22
23     <sect2 id="using-packages">
24       <title>Using a package</title>
25       <indexterm><primary>packages</primary>
26         <secondary>using</secondary></indexterm>
27       
28       <para>To use a package, add the <literal>-package</literal> flag
29       to the GHC command line:</para>
30
31       <variablelist>
32         <varlistentry>
33           <term><option>-package <replaceable>lib</replaceable></option></term>
34           <indexterm><primary>-package <replaceable>lib</replaceable> option</primary></indexterm>
35           <listitem>
36             <para>This option brings into scope all the modules from
37             package <literal><replaceable>lib</replaceable></literal> (they still have to
38             be imported in your Haskell source, however).  It also
39             causes the relevant libraries to be linked when linking is
40             being done.</para>
41           </listitem>
42         </varlistentry>
43       </variablelist>
44
45       <para>Some packages depend on other packages, for example the
46       <literal>text</literal> package makes use of some of the modules
47       in the <literal>lang</literal> package.  The package system
48       takes care of all these dependencies, so that when you say
49       <literal>-package text</literal> on the command line, you
50       automatically get <literal>-package lang</literal> too.</para>
51     </sect2>
52
53     <sect2 id="using-local-packages">
54       <title>Maintaining a local set of packages</title>
55       
56       <para>When GHC starts up, it automatically reads the default set
57       of packages from a configuration file, normally named
58       <filename>package.conf</filename> in your GHC installation
59       directory.</para>
60
61       <para>You can load in additional package configuration files
62       using the <option>-package-conf</option> option:</para>
63
64       <variablelist>
65         <varlistentry>
66           <term><option>-package-conf <replaceable>file</replaceable></option></term>
67           <indexterm><primary><option>-package-conf <replaceable>file</replaceable></option></primary>
68           </indexterm>
69           <listitem>
70             <para>Read in the package configuration file
71             <replaceable>file</replaceable> in addition to the system
72             default file.  This allows the user to have a local set of
73             packages in addition to the system-wide ones.</para>
74           </listitem>
75         </varlistentry>
76       </variablelist>
77
78       <para>To create your own package configuration file, just create
79       a new file and put the string
80       <quote><literal>[]</literal></quote> in it.  Packages can be
81       added to the new configuration file using the
82       <literal>ghc-pkg</literal> tool, described in <xref
83       linkend="package-management">.</para>
84     </sect2>
85
86     <sect2 id="building-packages">
87       <title>Building a package from Haskell source</title>
88       <indexterm><primary>packages</primary>
89         <secondary>building</secondary></indexterm>
90
91       <para>It takes some special considerations to build a new
92       package:</para>
93
94       <itemizedlist>
95         <listitem>
96           <para>A package may contain several Haskell modules. A
97           package may span many directories, or many packages may
98           exist in a single directory. Packages may not be mutually
99           recursive.</para>
100         </listitem>
101
102         <listitem>
103           <para>A package has a name
104           (e.g. <filename>std</filename>)</para>
105         </listitem>
106
107         <listitem>
108           <para>The Haskell code in a package may be built into one or
109           more archive libraries (e.g. <filename>libHSfoo.a</filename>),
110           or a single DLL on Windows
111           (e.g. <filename>HSfoo.dll</filename>).  The restriction to a
112           single DLL on Windows is that the package system is used to
113           tell the compiler when it should make an inter-DLL call
114           rather than an intra-DLL call (inter-DLL calls require an
115           extra indirection). <emphasis>Building packages as DLLs
116           doesn't work at the moment; see <XRef
117           LinkEnd="win32-dlls-create"> for the gory details.</emphasis>
118           </para>
119
120           <para>Versions of the Haskell libraries for use with GHCi
121           may also be included: GHCi cannot load <literal>.a</literal>
122           files directly, instead it will look for an object file
123           called <filename>HSfoo.o</filename> and load that.  The
124           <literal>ghc-pkg</literal> tool can automatically build the
125           GHCi version of each library, see <xref
126           linkend="package-management">.  To build these libraries by
127           hand from the <literal>.a</literal> archive, it is possible
128           to use GNU <command>ld</command> as follows:</para>
129
130 <screen>ld -r --whole-archive -o HSfoo.o libHSfoo.a</screen>
131         </listitem>
132
133         <listitem>
134           <para>GHC does not maintain detailed cross-package
135           dependency information.  It does remember which modules in
136           other packages the current module depends on, but not which
137           things within those imported things.</para>
138         </listitem>
139       </itemizedlist>
140
141       <para>To compile a module which is to be part of a new package,
142       use the <literal>-package-name</literal> option:</para>
143
144       <variablelist>
145         <varlistentry>
146           <term><option>-package-name <replaceable>foo</replaceable></option></term>
147           <indexterm><primary><literal>-package-name</literal></primary>
148             <secondary>option</secondary></indexterm>
149           <listitem>
150             <para>This option is added to the command line when
151             compiling a module that is destined to be part of package
152             <literal>foo</literal>.  If this flag is omitted then the
153             default package <literal>Main</literal> is assumed.</para>
154           </listitem>
155         </varlistentry>
156       </variablelist>
157
158       <para>Failure to use the <literal>-package-name</literal> option
159       when compiling a package will result in disaster on Windows, but
160       is relatively harmless on Unix at the moment (it will just cause
161       a few extra dependencies in some interface files).  However,
162       bear in mind that we might add support for Unix shared libraries
163       at some point in the future.</para>
164
165       <para>It is worth noting that on Windows, when each package
166       is built as a DLL, since a reference to a DLL costs an extra
167       indirection, intra-package references are cheaper than
168       inter-package references. Of course, this applies to the
169       <filename>Main</filename> package as well.</para>
170     </sect2>
171
172     <sect2 id="package-management">
173       <title>Package management</title>
174       <indexterm><primary>packages</primary>
175         <secondary>management</secondary></indexterm>
176       
177       <para>The <literal>ghc-pkg</literal> tool allows packages to be
178       added or removed from a package configuration file.  By default,
179       the system-wide configuration file is used, but alternatively
180       packages can be added or removed from a user-specified
181       configuration file using the <option>--config-file</option>
182       option.  An empty package configuration file consists of the
183       string <quote><literal>[]</literal></quote>.</para>
184
185       <para>The <literal>ghc-pkg</literal> program accepts the
186       following options:</para>
187
188       <variablelist>
189         <varlistentry>
190           <term><option>--add-package</option></term>
191           <term><option>-a</option></term>
192           <indexterm><primary><option>--add-package</option></primary>
193               </indexterm>
194           <listitem>
195             <para>Reads a package specification (see below) on stdin,
196             and adds it to the database of installed packages.  The
197             package specification must be a package that isn't already
198             installed.</para>
199           </listitem>
200         </varlistentry>
201
202         <varlistentry>
203           <term><option>--auto-ghci-libs</option></term>
204           <term><option>-g</option></term>
205           <indexterm><primary><option>--auto-ghci-libs</option></primary>
206               </indexterm>
207           <listitem>
208             <para>Automatically generate the GHCi
209             <filename>.o</filename> version of each
210             <filename>.a</filename> Haskell library, using GNU ld (if
211             that is available).  Without this option,
212             <literal>ghc-pkg</literal> will warn if GHCi versions of
213             any Haskell libraries in the package don't exist.</para>
214             
215             <para>GHCi <literal>.o</literal> libraries don't
216             necessarily have to live in the same directory as the
217             corresponding <literal>.a</literal> library.  However,
218             this option will cause the GHCi library to be created in
219             the same directory as the <literal>.a</literal>
220             library.</para>
221           </listitem>
222         </varlistentry>
223
224         <varlistentry>
225           <term><option>--config-file <replaceable>file</replaceable></option></term>
226           <term><option>-f <replaceable>file</replaceable></option></term>
227           <indexterm><primary><option>--config-file</option></primary>
228               </indexterm>
229           <listitem>
230             <para>Use <replaceable>file</replaceable> instead of the
231             default package configuration file.  This, in conjunction
232             with GHC's <option>-package-conf</option> option, allows
233             a user to have a local set of packages in addition to the
234             system-wide installed set.</para>
235           </listitem>
236         </varlistentry>
237
238         <varlistentry>
239           <term><option>--list-packages</option></term>
240           <term><option>-l</option></term>
241           <indexterm><primary><option>--list-packages</option></primary></indexterm>
242           <listitem>
243             <para>This option displays the list of currently installed
244             packages.</para>
245
246 <screen>
247   $ ghc-pkg --list-packages
248   gmp, rts, std, lang, concurrent, data, net, posix, text, util
249 </screen>
250
251             <para>Note that your GHC installation might have a
252             slightly different set of packages installed.</para>
253
254             <para>The <literal>gmp</literal> and
255             <literal>rts</literal> packages are always present, and
256             represent the multi-precision integer and runtime system
257             libraries respectively.  The <literal>std</literal>
258             package contains the Haskell prelude and standard
259             libraries.  The rest of the packages are optional
260             libraries.</para>
261           </listitem>
262         </varlistentry>
263
264         <varlistentry>
265           <term><option>--remove-package <replaceable>foo</replaceable></option></term>
266           <term><option>-r <replaceable>foo</replaceable></option></term>
267           <indexterm><primary><option>--delete-package</option></primary>
268               </indexterm>
269           <listitem>
270             <para>Removes the specified package from the installed
271             configuration.</para>
272           </listitem>
273         </varlistentry>
274       </variablelist>
275
276       <para>When modifying the configuration file
277       <replaceable>file</replaceable>, a copy of the original file is
278       saved in <replaceable>file</replaceable><literal>.old</literal>,
279       so in an emergency you can always restore the old settings by
280       copying the old file back again.</para>
281
282       <para>A package specification looks like this:</para>
283
284 <screen>
285   Package {
286      name            = "mypkg",
287      import_dirs     = ["/usr/local/lib/imports/mypkg"],
288      source_dirs     = [],
289      library_dirs    = ["/usr/local/lib"],
290      hs_libraries    = ["HSmypkg" ],
291      extra_libraries = ["HSmypkg_cbits"],
292      include_dirs    = [],
293      c_includes      = ["HsMyPkg.h"],
294      package_deps    = ["text", "data"],
295      extra_ghc_opts  = [],
296      extra_cc_opts   = [],
297      extra_ld_opts   = ["-lmy_clib"]
298   }
299 </screen>
300
301       <para>Components of a package specification may be specified in
302       any order, and are:</para>
303
304       <variablelist>
305         <varlistentry>
306           <term><literal>name</literal></term>
307           <indexterm><primary><literal>name</literal></primary>
308             <secondary>package specification</secondary></indexterm>
309           <listitem>
310             <para>The package's name, for use with
311             the <literal>-package</literal> flag and as listed in the
312             <literal>--list-packages</literal> list. 
313             </para>
314           </listitem>
315         </varlistentry>
316
317         <varlistentry>
318           <term><literal>import_dirs</literal></term>
319           <indexterm><primary><literal>import_dirs</literal></primary>
320             <secondary>package specification</secondary></indexterm>
321           <listitem>
322             <para>A list of directories containing interface files
323             (<literal>.hi</literal> files) for this package.</para>
324           </listitem>
325         </varlistentry>
326
327         <varlistentry>
328           <term><literal>source_dirs</literal></term>
329           <indexterm><primary><literal>source_dirs</literal></primary>
330             <secondary>package specification</secondary></indexterm>
331           <listitem>
332             <para>A list of directories containing Haskell source
333             files for this package.  This field isn't used by GHC, but
334             could potentially be used by an all-interpreted system
335             like Hugs.</para>
336           </listitem>
337         </varlistentry>
338
339         <varlistentry>
340           <term><literal>library_dirs</literal></term>
341           <indexterm><primary><literal>library_dirs</literal></primary>
342             <secondary>package specification</secondary></indexterm>
343           <listitem>
344             <para>A list of directories containing libraries for this
345             package.</para>
346           </listitem>
347         </varlistentry>
348
349         <varlistentry>
350           <term><literal>hs_libraries</literal></term>
351           <indexterm><primary><literal>hs_libraries</literal></primary>
352             <secondary>package specification</secondary></indexterm>
353           <listitem>
354             <para>A list of libraries containing Haskell code for this
355             package, with the <literal>.a</literal> or
356             <literal>.dll</literal> suffix omitted.  When packages are
357             built as libraries, the
358             <literal>lib</literal> prefix is also omitted.</para>
359
360             <para>For use with GHCi, each library should have an
361             object file too.  The name of the object file does
362             <emphasis>not</emphasis> have a <literal>lib</literal>
363             prefix, and has the normal object suffix for your
364             platform.</para>
365
366             <para>For example, if we specify a Haskell library as
367             <filename>HSfoo</filename> in the package spec, then the
368             various flavours of library that GHC actually uses will be
369             called:</para>
370             <variablelist>
371               <varlistentry>
372                 <term><filename>libHSfoo.a</filename></term>
373                 <listitem>
374                   <para>The name of the library on Unix
375                   systems.</para>
376                 </listitem>
377               </varlistentry>
378               <varlistentry>
379                 <term><filename>HSfoo.dll</filename></term>
380                 <listitem>
381                   <para>The name of the dynamic library on Windows
382                   systems.</para>
383                 </listitem>
384               </varlistentry>
385               <varlistentry>
386                 <term><filename>HSfoo.o</filename></term>
387                 <term><filename>HSfoo.obj</filename></term>
388                 <listitem>
389                   <para>The object version of the library used by
390                   GHCi.</para>
391                 </listitem>
392               </varlistentry>
393             </variablelist>
394
395           </listitem>
396         </varlistentry>
397
398         <varlistentry>
399           <term><literal>extra_libraries</literal></term>
400           <indexterm><primary><literal>extra_libraries</literal></primary>
401             <secondary>package specification</secondary></indexterm>
402           <listitem>
403             <para>A list of extra libraries for this package.  The
404             difference between <literal>hs_libraries</literal> and
405             <literal>extra_libraries</literal> is that
406             <literal>hs_libraries</literal> normally have several
407             versions, to support profiling, parallel and other build
408             options.  The various versions are given different
409             suffixes to distinguish them, for example the profiling
410             version of the standard prelude library is named
411             <filename>libHSstd_p.a</filename>, with the
412             <literal>_p</literal> indicating that this is a profiling
413             version.  The suffix is added automatically by GHC for
414             <literal>hs_libraries</literal> only, no suffix is added
415             for libraries in
416             <literal>extra_libraries</literal>.</para>
417
418             <para>Also, <literal>extra_libraries</literal> are placed
419             on the linker command line after the
420             <literal>hs_libraries</literal> for the same package.  If
421             your package has dependencies in the other direction (i.e.
422             <literal>extra_libraries</literal> depends on
423             <literal>hs_libraries</literal>), and the libraries are
424             static, you might need to make two separate
425             packages.</para>
426           </listitem>
427         </varlistentry>
428
429         <varlistentry>
430           <term><literal>include_dirs</literal></term>
431           <indexterm><primary><literal>include_dirs</literal></primary>
432             <secondary>package specification</secondary></indexterm>
433           <listitem>
434             <para>A list of directories containing C includes for this
435             package (maybe the empty list).</para>
436           </listitem>
437         </varlistentry>
438
439         <varlistentry>
440           <term><literal>c_includes</literal></term>
441           <indexterm><primary><literal>c_includes</literal></primary>
442             <secondary>package specification</secondary></indexterm>
443           <listitem>
444             <para>A list of files to include for via-C compilations
445             using this package.  Typically this include file will
446             contain function prototypes for any C functions used in
447             the package, in case they end up being called as a result
448             of Haskell functions from the package being
449             inlined.</para>
450           </listitem>
451         </varlistentry>
452
453         <varlistentry>
454           <term><literal>package_deps</literal></term>
455           <indexterm><primary><literal>package_deps</literal></primary>
456             <secondary>package specification</secondary></indexterm>
457           <listitem>
458             <para>A list of packages which this package depends
459             on.</para>
460           </listitem>
461         </varlistentry>
462
463         <varlistentry>
464           <term><literal>extra_ghc_opts</literal></term>
465           <indexterm><primary><literal>extra_ghc_opts</literal></primary>
466             <secondary>package specification</secondary></indexterm>
467           <listitem>
468             <para>Extra arguments to be added to the GHC command line
469             when this package is being used.</para>
470           </listitem>
471         </varlistentry>
472
473         <varlistentry>
474           <term><literal>extra_cc_opts</literal></term>
475           <indexterm><primary><literal>extra_cc_opts</literal></primary>
476             <secondary>package specification</secondary></indexterm>
477           <listitem>
478             <para>Extra arguments to be added to the gcc command line
479             when this package is being used (only for via-C
480             compilations).</para>
481           </listitem>
482         </varlistentry>
483
484         <varlistentry>
485           <term><literal>extra_ld_opts</literal></term>
486           <indexterm><primary><literal>extra_ld_opts</literal></primary>
487             <secondary>package specification</secondary></indexterm>
488           <listitem>
489             <para>Extra arguments to be added to the gcc command line
490             (for linking) when this package is being used.</para>
491           </listitem>
492         </varlistentry>
493       </variablelist>
494
495       <para>For examples of more package specifications, take a look
496       at the <literal>package.conf</literal> in your GHC
497       installation.</para>
498     </sect2>
499   </sect1>
500
501 <!-- Emacs stuff:
502      ;;; Local Variables: ***
503      ;;; mode: sgml ***
504      ;;; sgml-parent-document: ("using.sgml" "book" "chapter") ***
505      ;;; End: ***
506  -->