Cabal.xml 122 KB
Newer Older
ijones's avatar
ijones committed
1
2
<?xml version="1.0" encoding="US-ASCII"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3
  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
4
  [
5
6
7
8
    <!ENTITY Simple    '<ulink url="../libraries/Cabal/Distribution-Simple.html">Distribution.Simple</ulink>'>
    <!ENTITY Make      '<ulink url="../libraries/Cabal/Distribution-Make.html">Distribution.Make</ulink>'>
    <!ENTITY License   '<ulink url="../libraries/Cabal/Distribution-License.html#t:License"><literal>License</literal></ulink>'>
    <!ENTITY Extension '<ulink url="../libraries/Cabal/Language-Haskell-Extension.html#t:Extension"><literal>Extension</literal></ulink>'>
9
    <!ENTITY BuildType '<ulink url="../libraries/Cabal/Distribution-PackageDescription.html#t:BuildType"><literal>BuildType</literal></ulink>'>
ijones's avatar
ijones committed
10
11
12
13
    <!ENTITY Alex '<ulink url="http://www.haskell.org/alex/"><command>alex</command></ulink>'>
    <!ENTITY Autoconf '<ulink url="http://www.gnu.org/software/autoconf/"><command>autoconf</command></ulink>'>
    <!ENTITY C2hs '<ulink url="http://www.cse.unsw.edu.au/~chak/haskell/c2hs/"><command>c2hs</command></ulink>'>
    <!ENTITY Cpphs '<ulink url="http://www.haskell.org/cpphs/"><command>cpphs</command></ulink>'>
14
    <!ENTITY Greencard '<ulink url="http://www.haskell.org/greencard/"><command>greencard</command></ulink>'>
ijones's avatar
ijones committed
15
    <!ENTITY Haddock '<ulink url="http://www.haskell.org/haddock/"><command>haddock</command></ulink>'>
Roberto Zunino's avatar
Roberto Zunino committed
16
    <!ENTITY HsColour '<ulink url="http://www.cs.york.ac.uk/fp/darcs/hscolour/"><command>HsColour</command></ulink>'>
ijones's avatar
ijones committed
17
    <!ENTITY Happy '<ulink url="http://www.haskell.org/happy/"><command>happy</command></ulink>'>
18
    <!ENTITY HackageDB '<ulink url="http://hackage.haskell.org/">HackageDB</ulink>'>
19
    <!ENTITY PkgConfig '<ulink url="http://pkg-config.freedesktop.org/">pkg-config</ulink>'>
ijones's avatar
ijones committed
20
21
22
  ]>

<article>
ijones's avatar
ijones committed
23
  <title>Common Architecture for Building Applications and Libraries</title>
ijones's avatar
ijones committed
24
25
26
  <subtitle>User's Guide</subtitle>

  <abstract>
27
    <para><firstterm>Cabal</firstterm> aims to simplify the
ijones's avatar
ijones committed
28
29
30
31
      distribution of <ulink url="http://www.haskell.org/">Haskell</ulink>
      software.  It does this by specifying a number of interfaces between
      package authors, builders and users, as well as providing a library
      implementing these interfaces.</para>
ijones's avatar
ijones committed
32
33
  </abstract>

34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
  <sect1 id="intro">
    <title>Introduction</title>
    <para>
      Developers write Cabal packages. These can be for libraries or
      executables. This involves writing the code obviously and also creating a
      <literal>.cabal</literal> file. The .cabal file contains some information
      about the package. Some of this information is needed to actually build
      the package and some is just useful for identifying the package when it
      comes to distribution.
    </para>
    <programlisting>
name:     Foo
version:  1.0

library
  build-depends:   base
  exposed-modules: Foo
    </programlisting>
    <para>
      Users install Cabal packages so they can use them. It is not expected
      that users will have to modify any of the information in the
      <literal>.cabal</literal> file. Cabal does provide a number of ways for
      a user to customise how and where a package is installed. They can decide
      where a package will be installed, which Haskell implementation to use
      and whether to build optimised code or build with the ability to profile
      code.
    </para>
    <programlisting>
tar -xzf Foo-1.0.tar.gz
cd Foo-1.0
64
cabal-setup configure --with-compiler=ghc-6.4.2 --user
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
cabal-setup build
cabal-setup install
    </programlisting>
    <para>
      One of the purposes of Cabal is to make it easier to build a package with
      different Haskell implementations. So it provides abstractions of
      features present in different Haskell implementations and wherever
      possible it is best to take advantage of these to increase portability.
      Where necessary however it is possible to use specific features of
      specific implementations. For example one of the pieces of information a
      package author can put in the package's <literal>.cabal</literal> file is
      what language extensions the code uses. This is far preferable to
      specifying flags for a specific compiler as it allows Cabal to pick the
      right flags for the Haskell implementation that the user picks. It also
      allows Cabal to figure out if the language extension is even supported by
      the Haskell implementation that the user picks. Where compiler-specific
      options are needed however, there is an "escape hatch" available. The
      developer can specify implementation-specific options and more generally
      there is a configuration mechanism to custoimise many aspects of how a
      package is built depending on the Haskell implementation, the Operating
      system, computer architecture and user-specified configuration flags.
    </para>
    <programlisting>
name:     Foo
version:  1.0

library
  build-depends:   base
  exposed-modules: Foo
  extensions:	   ForeignFunctionInterface
  ghc-options:     -Wall
  nhc98-options:   -K4m
  if os(windows)
    build-depends: Win32
    </programlisting>
  </sect1>

ijones's avatar
ijones committed
102
  <sect1 id="packages">
ijones's avatar
ijones committed
103
104
105
106
107
108
109
110
111
112
    <title>Packages</title>

    <para>A <firstterm>package</firstterm> is the unit of distribution
      for the Cabal.  Its purpose, when installed, is to make available
      either or both of:</para>
    <itemizedlist>
      <listitem>
        <para>A library, exposing a number of Haskell modules.  A library
          may also contain <firstterm>hidden</firstterm> modules, which
          are used internally but not available to clients.<footnote>
113
            <para>Hugs doesn't support module hiding.</para>
ijones's avatar
ijones committed
114
115
116
117
118
119
120
121
122
          </footnote>
          </para>
      </listitem>

      <listitem>
        <para>One or more Haskell programs.</para>
      </listitem>
    </itemizedlist>
    <para>However having both a library and executables in a package
123
124
125
      does not work very well; if the executables depend on the library,
      they must explicitly list all the modules they directly or
      indirectly import from that library.</para>
ijones's avatar
ijones committed
126

ijones's avatar
ijones committed
127
128
129
130
    <para>Internally, the package may consist of much more than a
    bunch of Haskell modules: it may also have C source code and
    header files, source code meant for preprocessing, documentation,
    test cases, auxiliary tools etc.</para>
ijones's avatar
ijones committed
131
132

    <para>A package is identified by a globally-unique
ijones's avatar
ijones committed
133
134
135
136
      <firstterm>package name</firstterm>, which consists of one or
      more alphanumeric words separated by hyphens.  To avoid ambiguity,
      each of these words should contain at least one letter.
      Chaos will result if two distinct packages with the
ijones's avatar
ijones committed
137
138
139
140
      same name are installed on the same system, but there is not
      yet a mechanism for allocating these names.
      A particular version of the package is distinguished by a
      <firstterm>version number</firstterm>, consisting of a sequence
ijones's avatar
ijones committed
141
142
143
144
      of one or more integers separated by dots.  These can be combined
      to form a single text string called the <firstterm>package
      ID</firstterm>, using a hyphen to separate the name from the
      version, e.g. <quote><literal>HUnit-1.1</literal></quote>.</para>
ijones's avatar
ijones committed
145
146
147
148

    <note>
      <para>Packages are not part of the Haskell language;
        they simply populate the hierarchical space of module names.
149
150
151
152
        In GHC 6.6 and later a program may contain multiple modules
        with the same name if they come from separate packages; in all
        other current Haskell systems packages may not overlap in the
        modules they provide, including hidden modules.</para>
ijones's avatar
ijones committed
153
    </note>
ijones's avatar
ijones committed
154
  </sect1>
ijones's avatar
ijones committed
155

ijones's avatar
ijones committed
156
  <sect1 id="authors">
ijones's avatar
ijones committed
157
    <title>Creating a package</title>
158
159
160
161

    <para>Suppose you have a directory hierarchy containing the source
      files that make up your package.  You will need to add two more
      files to the root directory of the package:</para>
ijones's avatar
ijones committed
162
163
    <variablelist>
      <varlistentry>
164
165
166
        <term>
          <filename><replaceable>package</replaceable>.cabal</filename>
        </term>
ijones's avatar
ijones committed
167
168
169
        <listitem>
          <para>a text file containing a package description
            (for details of the syntax of this file, see
170
            <xref linkend="pkg-descr"/>), and</para>
ijones's avatar
ijones committed
171
172
173
174
        </listitem>
      </varlistentry>

      <varlistentry>
175
176
177
178
        <term>
          <filename>Setup.hs</filename> or
          <filename>Setup.lhs</filename>
        </term>
ijones's avatar
ijones committed
179
        <listitem>
ijones's avatar
ijones committed
180
181
182
183
184
185
186
          <para>a single-module Haskell program to perform various
            setup tasks (with the interface described in
            <xref linkend="builders"/>).  This module should import only
            modules that will be present in all Haskell implementations,
            including modules of the Cabal library.  In most cases it
            will be trivial, calling on the Cabal library to do most of
            the work.</para>
ijones's avatar
ijones committed
187
188
189
190
191
192
193
194
195
196
197
198
        </listitem>
      </varlistentry>
    </variablelist>
    <para>Once you have these, you can create a source bundle of this
      directory for distribution.  Building of the package is discussed in
      <xref linkend="builders"/>.</para>

    <example id="simple-library-example">
      <title>A package containing a simple library</title>
      <para>The HUnit package contains a file <filename>HUnit.cabal</filename>
        containing:</para>
      <programlisting>
199
200
201
202
203
204
205
206
207
208
Name:		HUnit
Version:	1.1.1
Cabal-Version:  >= 1.2
License:	BSD3
License-File:	LICENSE
Author:		Dean Herington
Homepage:	http://hunit.sourceforge.net/
Category:	Testing
Synopsis:	A unit testing framework for Haskell

209
Library
210
211
212
213
214
  Build-Depends:	base
  Exposed-modules:
    Test.HUnit.Base, Test.HUnit.Lang, Test.HUnit.Terminal,
    Test.HUnit.Text, Test.HUnit
  Extensions:	CPP
215
</programlisting>
ijones's avatar
ijones committed
216
217
218
219
220
221
222
      <para>and the following <filename>Setup.hs</filename>:</para>
      <programlisting>
import Distribution.Simple
main = defaultMain</programlisting>
    </example>

    <example id="simple-executable-example">
223
224
225
226
      <title>A package containing executable programs</title>
      <programlisting>
Name:           TestPackage
Version:        0.0
227
Cabal-Version:  >= 1.2
228
229
License:        BSD3
Author:         Angela Author
ijones's avatar
ijones committed
230
Synopsis:       Small package with two programs
231
Build-Type:     Simple
232

233
Executable program1
234
235
236
237
  Build-Depends:  HUnit
  Main-Is:        Main.hs
  Hs-Source-Dirs: prog1

238
Executable program2
239
240
241
242
  Main-Is:        Main.hs
  Build-Depends:  HUnit
  Hs-Source-Dirs: prog2
  Other-Modules:  Utils
243
</programlisting>
244
245
246
247
      <para>with <filename>Setup.hs</filename> the same as above.</para>
    </example>

    <example id="simple-library-executable-example">
ijones's avatar
ijones committed
248
      <title>A package containing a library and executable programs</title>
ijones's avatar
ijones committed
249
      <programlisting>
ijones's avatar
ijones committed
250
251
Name:            TestPackage
Version:         0.0
252
Cabal-Version:   >= 1.2
ijones's avatar
ijones committed
253
254
License:         BSD3
Author:          Angela Author
ijones's avatar
ijones committed
255
Synopsis:        Package with library and two programs
256
Build-Type:      Simple
257

258
Library
259
260
261
  Build-Depends:   HUnit
  Exposed-Modules: A, B, C

262
Executable program1
263
264
265
266
  Main-Is:         Main.hs
  Hs-Source-Dirs:  prog1
  Other-Modules:   A, B

267
Executable program2
268
269
270
  Main-Is:         Main.hs
  Hs-Source-Dirs:  prog2
  Other-Modules:   A, C, Utils
271
</programlisting>
ijones's avatar
ijones committed
272
273
274
      <para>with <filename>Setup.hs</filename> the same as above.
      Note that any library modules required (directly or indirectly)
      by an executable must be listed again.</para>
ijones's avatar
ijones committed
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
    </example>

    <para>The trivial setup script used in these examples uses
      the <firstterm>simple build infrastructure</firstterm>
      provided by the Cabal library (see &Simple;).
      The simplicity lies in its interface rather that its implementation.
      It automatically handles preprocessing with standard preprocessors,
      and builds packages for all the Haskell implementations (except
      nhc98, for now).</para>

    <para>The simple build infrastructure can also handle packages
      where building is governed by system-dependent parameters,
      if you specify a little more (see <xref linkend="system-dependent"/>).
      A few packages require more elaborate solutions
      (see <xref linkend="complex-packages"/>).</para>

ijones's avatar
ijones committed
291
    <sect2 id="pkg-descr">
ijones's avatar
ijones committed
292
      <title>Package descriptions</title>
ijones's avatar
ijones committed
293
294
295

      <para>The package description file should have a name ending in
        <quote><literal>.cabal</literal></quote>.  There must be exactly
ijones's avatar
ijones committed
296
        one such file in the directory.  The first part of the name is
297
298
        usually the package name, and some of the tools that operate
        on Cabal packages require this.</para>
ijones's avatar
ijones committed
299

ijones's avatar
ijones committed
300
      <para>In the package description file, lines beginning with
301
302
303
304
305
      <quote><literal>--</literal></quote> are treated as comments
      and ignored.</para>

      <para>This file should contain of a number global property
      descriptions and several sections.</para>
ijones's avatar
ijones committed
306
307

      <itemizedlist>
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
	<listitem>
	  <para>The global properties describe the package as a whole,
	  such as name, license, author, etc.  (see <xref
	  linkend="general-fields"/>).</para>
	</listitem>
	<listitem>
	  <para>Optionally, a number of <firstterm>configuration
	  flags</firstterm> can be declared.  These can be used to
	  enable or disable certain features of a package. (see <xref
	  linkend="configurations"/>).</para>
	</listitem>
	<listitem>
	  <para>The (optional) library section specifies the library
	  properties (see <xref linkend="library"/>) and relevant build
	  information (see <xref linkend="buildinfo"/>).</para>
	</listitem>
	<listitem>
	  <para>Following is an arbitrary number of executable sections
	  which describe an executable program and (see <xref
	  linkend="executable"/>) relevant build information (see <xref
	  linkend="buildinfo"/>).</para>
ijones's avatar
ijones committed
329
330
331
	</listitem>
      </itemizedlist>

332
333
334
      <para>Each section consists of a number of property descriptions
      in the form of field/value pairs, with a syntax roughly like mail
      message headers.</para>
335
      <itemizedlist>
ijones's avatar
ijones committed
336
	<listitem>
337
338
339
340
341
342
343
344
345
346
          <para>Case is not significant in field names,
            but is significant in field values.</para>
	</listitem>
	<listitem>
          <para>To continue a field value, indent the next line
          relative to the field name.</para>
	</listitem>
	<listitem>
          <para>Field names may be indented, but all field values in
          the same section must use the same indentation.</para>
ijones's avatar
ijones committed
347
348
	</listitem>
	<listitem>
349
350
351
          <para>Tabs are <emphasis>not</emphasis> allowed as
          indentation characters due to a missing standard
          interpretation of tab width.</para>
ijones's avatar
ijones committed
352
353
	</listitem>
	<listitem>
354
          <para>To get a blank line in a field value, use an indented
ijones's avatar
ijones committed
355
356
            <quote><literal>.</literal></quote></para>
	</listitem>
357
      </itemizedlist>
ijones's avatar
ijones committed
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
      <para>The syntax of the value depends on the field.  Field types
        include:</para>

      <variablelist>
        <varlistentry>
          <term>
            <replaceable>token</replaceable>
          </term>
          <term>
            <replaceable>filename</replaceable>
          </term>
          <term>
            <replaceable>directory</replaceable>
          </term>
          <listitem>
            <para>Either a sequence of one or more non-space non-comma
ijones's avatar
ijones committed
374
375
376
              characters, or a quoted string in Haskell 98 lexical syntax.
              Unless otherwise stated, relative filenames and directories
              are interpreted from the package root directory.</para>
ijones's avatar
ijones committed
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <replaceable>freeform</replaceable>
          </term>
          <term>
            <replaceable>URL</replaceable>
          </term>
          <term>
            <replaceable>address</replaceable>
          </term>
          <listitem>
            <para>An arbitrary, uninterpreted string.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <replaceable>identifier</replaceable>
          </term>
          <listitem>
            <para>A letter followed by zero or more alphanumerics
              or underscores.</para>
          </listitem>
        </varlistentry>
      </variablelist>

ijones's avatar
ijones committed
406
      <note>
ijones's avatar
ijones committed
407
408
409
410
411
412
413
414
415
        <title>Modules and preprocessors</title>
        <para>Haskell module names listed in the
          <literal>exposed-modules</literal> and
          <literal>other-modules</literal> fields may
          correspond to Haskell source files, i.e. with names
          ending in <quote><literal>.hs</literal></quote> or
          <quote><literal>.lhs</literal></quote>, or to inputs for
          various Haskell preprocessors.
          The simple build infrastructure understands the extensions
ijones's avatar
ijones committed
416
417
          <quote><literal>.gc</literal></quote> (&Greencard;),
          <quote><literal>.chs</literal></quote> (&C2hs;),
ijones's avatar
ijones committed
418
419
          <quote><literal>.hsc</literal></quote> (<command>hsc2hs</command>),
          <quote><literal>.y</literal></quote> and
ijones's avatar
ijones committed
420
421
          <quote><literal>.ly</literal></quote> (&Happy;),
          <quote><literal>.x</literal></quote> (&Alex;)
ijones's avatar
ijones committed
422
          and
ijones's avatar
ijones committed
423
          <quote><literal>.cpphs</literal></quote> (&Cpphs;).
ijones's avatar
ijones committed
424
425
          When building, Cabal will automatically run the appropriate
          preprocessor and compile the Haskell module it produces.</para>
ijones's avatar
ijones committed
426
427
      </note>

ijones's avatar
ijones committed
428
429
430
431
432
      <para>Some fields take lists of values, which
        are optionally separated by commas, except for the
        <literal>build-depends</literal> field, where the commas are
        mandatory.</para>

ijones's avatar
ijones committed
433
434
435
      <para>Some fields are marked as required.  All others are optional,
        and unless otherwise specified have empty default values.</para>

ijones's avatar
ijones committed
436
437
      <sect3 id="general-fields">
        <title>Package properties</title>
ijones's avatar
ijones committed
438

439
440
        <para>These fields may occur in the first top-level properties
        section and describe the package as a whole:</para>
ijones's avatar
ijones committed
441

ijones's avatar
ijones committed
442
443
444
445
446
447
448
449
450
451
452
453
        <variablelist>
          <varlistentry>
            <term>
              <literal>name:</literal> <replaceable>package-name</replaceable>
              (required)
            </term>
            <listitem>
              <para>The unique name of the package
                (see <xref linkend="packages"/>), without the version
                number.</para>
            </listitem>
          </varlistentry>
ijones's avatar
ijones committed
454

ijones's avatar
ijones committed
455
456
457
458
459
460
461
462
463
464
          <varlistentry>
            <term>
              <literal>version:</literal> <replaceable>numbers</replaceable>
              (required)
            </term>
            <listitem>
              <para>The package version number, usually consisting of a
                sequence of natural numbers separated by dots.</para>
            </listitem>
          </varlistentry>
ijones's avatar
ijones committed
465

ijones's avatar
ijones committed
466
          <varlistentry>
ijones's avatar
ijones committed
467
            <term>
468
              <literal>cabal-version:</literal> <replaceable>&gt;, &lt;=, etc. &amp; numbers</replaceable>
ijones's avatar
ijones committed
469
470
471
            </term>
            <listitem>
              <para>The version of Cabal required for this package.
472
473
474
475
476
477
478
479
480
481
482
483
              Since, with Cabal version 1.2 the syntax of package
              descriptions has changed, this is now a required field.
              List the field early in your <literal>.cabal</literal>
              file so that it will appear as a syntax error before any
              others, since old versions of Cabal unfortunately do not
              recognize this field.</para>
	      <para>For compatibility, files written in the old syntax
	      are still recognized.  Thus if you don't require
	      features introduced with or after Cabal version 1.2, you
	      may write your package description file using the old
	      syntax.  Please consult the user's guide of that Cabal
	      version for a description of that syntax.</para>
ijones's avatar
ijones committed
484
485
486
            </listitem>
          </varlistentry>

487
488
489
490
491
492
493
494
495
          <varlistentry>
            <term>
              <literal>build-type:</literal> <replaceable>identifier</replaceable>
            </term>
            <listitem>
              <para>The type of build used by this package.
                Build types are the constructors of the &BuildType; type,
                defaulting to <literal>Custom</literal>.
                If this field is given a value other than
496
497
498
499
500
                <literal>Custom</literal>, some tools such as
                <literal>cabal-setup</literal> will be able to
                build the package without using the setup script. So if you are
                just using the default <literal>Setup.hs</literal> then set
                the build type as <literal>Simple</literal>.</para>
501
502
503
            </listitem>
          </varlistentry>

ijones's avatar
ijones committed
504
           <varlistentry>
ijones's avatar
ijones committed
505
506
507
508
509
510
511
512
513
514
            <term>
              <literal>license:</literal> <replaceable>identifier</replaceable>
              (default: <literal>AllRightsReserved</literal>)
            </term>
            <listitem>
              <para>The type of license under which this package is
                distributed.  License names are the constants of the
                &License; type.</para>
            </listitem>
          </varlistentry>
ijones's avatar
ijones committed
515

ijones's avatar
ijones committed
516
517
518
519
520
521
522
          <varlistentry>
            <term>
              <literal>license-file:</literal>
              <replaceable>filename</replaceable>
            </term>
            <listitem>
              <para>The name of a file containing the precise license
523
524
                for this package. It will be installed with the package.
              </para>
ijones's avatar
ijones committed
525
526
            </listitem>
          </varlistentry>
ijones's avatar
ijones committed
527

ijones's avatar
ijones committed
528
529
530
531
532
533
534
535
536
          <varlistentry>
            <term>
              <literal>copyright:</literal>
              <replaceable>freeform</replaceable>
            </term>
            <listitem>
              <para>The content of a copyright notice, typically the
                name of the holder of the copyright on the package and
                the year(s) from which copyright is claimed.</para>
537
538
539
              <para>For example:
              <literal>Copyright: (c) 2006-2007 Joe Bloggs</literal>
              </para>
ijones's avatar
ijones committed
540
541
            </listitem>
          </varlistentry>
ijones's avatar
ijones committed
542

ijones's avatar
ijones committed
543
544
545
546
547
548
549
550
551
          <varlistentry>
            <term>
              <literal>author:</literal>
              <replaceable>freeform</replaceable>
            </term>
            <listitem>
              <para>The original author of the package.</para>
            </listitem>
          </varlistentry>
ijones's avatar
ijones committed
552

ijones's avatar
ijones committed
553
554
555
556
557
558
559
560
561
562
563
          <varlistentry>
            <term>
              <literal>maintainer:</literal>
              <replaceable>address</replaceable>
            </term>
            <listitem>
              <para>The current maintainer or maintainers of the package.
                This is an e-mail address to which users should send bug
                reports, feature requests and patches.</para>
            </listitem>
          </varlistentry>
ijones's avatar
ijones committed
564

ijones's avatar
ijones committed
565
566
567
568
569
570
571
572
573
574
575
576
          <varlistentry>
            <term>
              <literal>stability:</literal>
              <replaceable>freeform</replaceable>
            </term>
            <listitem>
              <para>The stability level of the package, e.g.
                <literal>alpha</literal>, <literal>experimental</literal>,
                <literal>provisional</literal>,
                <literal>stable</literal>.</para>
            </listitem>
          </varlistentry>
ijones's avatar
ijones committed
577

ijones's avatar
ijones committed
578
579
580
581
582
583
584
585
          <varlistentry>
            <term>
              <literal>homepage:</literal> <replaceable>URL</replaceable>
            </term>
            <listitem>
              <para>The package homepage.</para>
            </listitem>
          </varlistentry>
ijones's avatar
ijones committed
586

ijones's avatar
ijones committed
587
588
589
590
591
592
593
594
595
          <varlistentry>
            <term>
              <literal>package-url:</literal> <replaceable>URL</replaceable>
            </term>
            <listitem>
              <para>The location of a source bundle for the package.
                The distribution should be a Cabal package.</para>
            </listitem>
          </varlistentry>
ijones's avatar
ijones committed
596

ijones's avatar
ijones committed
597
598
599
600
601
602
603
604
605
606
607
608
609
          <varlistentry>
            <term>
              <literal>synopsis:</literal>
              <replaceable>freeform</replaceable>
            </term>
            <listitem>
              <para>A very short description of the package, for use in
                a table of packages.  This is your headline, so keep
                it short (one line) but as informative as possible.
                Save space by not including the package name or saying
                it's written in Haskell.</para>
            </listitem>
          </varlistentry>
ijones's avatar
ijones committed
610

ijones's avatar
ijones committed
611
612
613
614
615
616
617
618
619
          <varlistentry>
            <term>
              <literal>description:</literal>
              <replaceable>freeform</replaceable>
            </term>
            <listitem>
              <para>Description of the package.  This may be several
                paragraphs, and should be aimed at a Haskell programmer
                who has never heard of your package before.</para>
Ross Paterson's avatar
Ross Paterson committed
620
621
622
623
624
625

              <para>For library packages, this field is used as
                prologue text by <command>setup haddock</command>
                (see <xref linkend="setup-haddock"/>), and thus may
                contain the same markup as &Haddock; documentation
                comments.</para>
ijones's avatar
ijones committed
626
627
            </listitem>
          </varlistentry>
ijones's avatar
ijones committed
628

ijones's avatar
ijones committed
629
630
631
632
633
634
635
636
637
638
639
640
          <varlistentry>
            <term>
              <literal>category:</literal>
              <replaceable>freeform</replaceable>
            </term>
            <listitem>
              <para>A classification category for future use by the
                package catalogue <firstterm>Hackage</firstterm>.  These
                categories have not yet been specified, but the upper
                levels of the module hierarchy make a good start.</para>
            </listitem>
          </varlistentry>
ijones's avatar
ijones committed
641

ijones's avatar
ijones committed
642
643
644
645
646
647
648
649
650
651
          <varlistentry>
            <term>
              <literal>tested-with:</literal>
              <replaceable>compiler list</replaceable>
            </term>
            <listitem>
              <para>A list of compilers and versions against which the
                package has been tested (or at least built).</para>
            </listitem>
          </varlistentry>
ijones's avatar
ijones committed
652

ijones's avatar
ijones committed
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
          <varlistentry>
            <term>
              <literal>data-files:</literal>
              <replaceable>filename list</replaceable>
            </term>
            <listitem>
              <para>A list of files to be installed for run-time use by
                the package.  This is useful for packages that use a
                large amount of static data, such as tables of values
                or code templates.  For details on how to find these
                files at run-time, see
                <xref linkend="paths-module"/>.</para>
            </listitem>
          </varlistentry>

ijones's avatar
ijones committed
668
669
          <varlistentry>
            <term>
ijones's avatar
ijones committed
670
              <literal>extra-source-files:</literal>
ijones's avatar
ijones committed
671
672
673
674
675
676
677
678
              <replaceable>filename list</replaceable>
            </term>
            <listitem>
              <para>A list of additional files to be included in source
                distributions built with <command>setup sdist</command>
                (see <xref linkend="setup-sdist"/>).</para>
            </listitem>
          </varlistentry>
ijones's avatar
ijones committed
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693

          <varlistentry>
            <term>
              <literal>extra-tmp-files:</literal>
              <replaceable>filename list</replaceable>
            </term>
            <listitem>
              <para>A list of additional files or directories to be
                removed by <command>setup clean</command>
                (see <xref linkend="setup-clean"/>).
                These would typically be additional files created by
                additional hooks, such as the scheme described in
                <xref linkend="system-dependent"/>.</para>
            </listitem>
          </varlistentry>
ijones's avatar
ijones committed
694
695
        </variablelist>
      </sect3>
696

ijones's avatar
ijones committed
697
698
699
      <sect3 id="library">
        <title>Library</title>

700
        <para>The library section should contain the following
701
        fields:</para>
ijones's avatar
ijones committed
702
703
704
705
706
707
708
709
710
711
712
713

        <variablelist>
          <varlistentry>
            <term>
              <literal>exposed-modules:</literal>
              <replaceable>identifier list</replaceable>
              (required if this package contains a library)
            </term>
            <listitem>
              <para>A list of modules added by this package.</para>
            </listitem>
          </varlistentry>
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
	  <varlistentry>
            <term>
              <literal>build-depends:</literal>
              <replaceable>package list</replaceable>
            </term>
            <listitem>
              <para>A list of packages, possibly annotated with versions,
                needed to build this one,
                e.g. <literal>foo > 1.2, bar</literal>.
                If no version constraint is specified, any version is
                assumed to be acceptable.</para>
            </listitem>
          </varlistentry>


ijones's avatar
ijones committed
729
730
        </variablelist>

731
732
        <para>The library section may also contain build information fields
          (see <xref linkend="buildinfo"/>).</para>
ijones's avatar
ijones committed
733
      </sect3>
734

ijones's avatar
ijones committed
735
      <sect3 id="executable">
ijones's avatar
ijones committed
736
        <title>Executables</title>
737

738
739
740
741
742
743
744
745
746
        <para>Executable sections (if present) describe executable
        programs contained in the package and must have an argument
        after the section label, which defines the name of the
        executable.  This is a freeform argument but may not contain
        spaces.</para>

        <para>The executable may be described using the following
        fields, as well as build information fields (see <xref
        linkend="buildinfo"/>).</para>
747

ijones's avatar
ijones committed
748
749
        <variablelist>
          <varlistentry>
750
            <term>
751
              <literal>main-is:</literal> <replaceable>filename</replaceable>
ijones's avatar
ijones committed
752
              (required)
753
            </term>
ijones's avatar
ijones committed
754
            <listitem>
755
756
757
758
759
760
761
762
              <para>The name of the <filename>.hs</filename> or
                <filename>.lhs</filename> file containing the
                <literal>Main</literal> module. Note that it is the
                <filename>.hs</filename> filename that must be listed, even if
                that file is generated using a preprocessor. The source
                file must be relative to one of the directories listed in
                <literal>hs-source-dirs</literal>.
              </para>
ijones's avatar
ijones committed
763
764
            </listitem>
          </varlistentry>
765
	  <varlistentry>
766
            <term>
767
768
              <literal>build-depends:</literal>
              <replaceable>package list</replaceable>
769
            </term>
ijones's avatar
ijones committed
770
            <listitem>
771
772
773
774
775
              <para>A list of packages, possibly annotated with versions,
                needed to build this executable,
                e.g. <literal>foo > 1.2, bar</literal>.
                If no version constraint is specified, any version is
                assumed to be acceptable.</para>
ijones's avatar
ijones committed
776
777
778
            </listitem>
          </varlistentry>
        </variablelist>
ijones's avatar
ijones committed
779

ijones's avatar
ijones committed
780
      </sect3>
ijones's avatar
ijones committed
781

ijones's avatar
ijones committed
782
      <sect3 id="buildinfo">
ijones's avatar
ijones committed
783
        <title>Build information</title>
784

785
786
787
788
789
790
        <para>The following fields may be optionally present in a
        library or executable section, and give information for the
        building of the corresponding library or executable.  See also
        <xref linkend="system-dependent"/> and <xref linkend="configurations"/>
        for a way to supply system-dependent values for these
        fields.</para>
791

ijones's avatar
ijones committed
792
793
        <variablelist>
          <varlistentry>
794
795
            <term>
              <literal>buildable:</literal> <replaceable>Boolean</replaceable>
ijones's avatar
ijones committed
796
              (default: <literal>True</literal>)
797
            </term>
ijones's avatar
ijones committed
798
799
800
801
802
803
804
805
806
807
            <listitem>
              <para>Is the component buildable?
                Like some of the other fields below, this field is
                more useful with the slightly more elaborate form of
                the simple build infrastructure described in
                <xref linkend="system-dependent"/>.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
808
809
            <term>
              <literal>other-modules:</literal>
ijones's avatar
ijones committed
810
              <replaceable>identifier list</replaceable>
811
            </term>
ijones's avatar
ijones committed
812
813
814
815
816
817
818
819
820
821
            <listitem>
              <para>A list of modules used by the component
                but not exposed to users.  For a library component, these
                would be hidden modules of the library.  For an executable,
                these would be auxiliary modules to be linked with the
                file named in the <literal>main-is</literal> field.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
822
            <term>
ijones's avatar
ijones committed
823
824
              <literal>hs-source-dirs:</literal>
              <replaceable>directory list</replaceable>
ijones's avatar
ijones committed
825
              (default: <quote><literal>.</literal></quote>)
826
            </term>
ijones's avatar
ijones committed
827
            <listitem>
ijones's avatar
ijones committed
828
829
830
831
              <para>Root directories for the module hierarchy.</para>

              <para>For backwards compatibility, the old variant
                <literal>hs-source-dir</literal> is also recognized.</para>
ijones's avatar
ijones committed
832
833
834
            </listitem>
          </varlistentry>
          <varlistentry>
835
836
            <term>
              <literal>extensions:</literal>
ijones's avatar
ijones committed
837
              <replaceable>identifier list</replaceable>
838
            </term>
ijones's avatar
ijones committed
839
840
841
842
843
844
845
846
847
848
849
            <listitem>
              <para>A list of Haskell extensions used by every module.
                Extension names are the constructors of the &Extension; type.
                These determine corresponding compiler options.
                In particular, <literal>CPP</literal> specifies that
                Haskell source files are to be preprocessed with a
                C preprocessor.</para>

              <para>Extensions used only by one module may be specified
                by placing a <literal>LANGUAGE</literal> pragma in the
                source file affected, e.g.:</para>
ijones's avatar
ijones committed
850
851
              <programlisting>{-# LANGUAGE CPP, MultiParamTypeClasses #-}</programlisting>
	      <note>
Ross Paterson's avatar
Ross Paterson committed
852
853
                <para>GHC versions prior to 6.6 do not support the
                  <literal>LANGUAGE</literal> pragma.</para>
ijones's avatar
ijones committed
854
	      </note>
ijones's avatar
ijones committed
855
856
857
            </listitem>
          </varlistentry>

858
859
860
861
862
863
864
865
866
867
868
869
870
871
          <varlistentry>
            <term>
              <literal>build-tools:</literal>
              <replaceable>program list</replaceable>
            </term>
            <listitem>
              <para>A list of programs, possibly annotated with versions,
                needed to build this package,
                e.g. <literal>c2hs > 0.15, cpphs</literal>.
                If no version constraint is specified, any version is
                assumed to be acceptable.</para>
            </listitem>
          </varlistentry>

ijones's avatar
ijones committed
872
          <varlistentry>
873
            <term>
ijones's avatar
ijones committed
874
875
              <literal>ghc-options:</literal>
              <replaceable>token list</replaceable>
876
            </term>
ijones's avatar
ijones committed
877
878
879
880
881
882
883
884
885
886
887
            <listitem>
              <para>Additional options for GHC.  You can often achieve
                the same effect using the <literal>extensions</literal>
                field, which is preferred.</para>

              <para>Options required only by one module may be specified
                by placing an <literal>OPTIONS_GHC</literal> pragma in the
                source file affected.</para>
            </listitem>
          </varlistentry>

ijones's avatar
ijones committed
888
889
890
891
892
893
894
895
896
897
898
          <varlistentry>
            <term>
              <literal>ghc-prof-options:</literal>
              <replaceable>token list</replaceable>
            </term>
            <listitem>
              <para>Additional options for GHC when the package is built
                with profiling enabled.</para>
            </listitem>
          </varlistentry>

899
900
901
902
903
904
905
906
907
908
909
910
          <varlistentry>
            <term>
              <literal>ghc-shared-options:</literal>
              <replaceable>token list</replaceable>
            </term>
            <listitem>
              <para>Additional options for GHC when the package is
              built as shared library.</para>
            </listitem>
          </varlistentry>


ijones's avatar
ijones committed
911
          <varlistentry>
912
            <term>
ijones's avatar
ijones committed
913
914
              <literal>hugs-options:</literal>
              <replaceable>token list</replaceable>
915
            </term>
ijones's avatar
ijones committed
916
917
918
919
920
921
922
923
924
925
926
927
            <listitem>
              <para>Additional options for Hugs.  You can often achieve
                the same effect using the <literal>extensions</literal>
                field, which is preferred.</para>

              <para>Options required only by one module may be specified
                by placing an <literal>OPTIONS_HUGS</literal> pragma in the
                source file affected.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
928
            <term>
929
              <literal>nhc98-options:</literal>
ijones's avatar
ijones committed
930
              <replaceable>token list</replaceable>
931
            </term>
ijones's avatar
ijones committed
932
933
934
935
936
937
            <listitem>
              <para>Additional options for nhc98.  You can often achieve
                the same effect using the <literal>extensions</literal>
                field, which is preferred.</para>

              <para>Options required only by one module may be specified
938
                by placing an <literal>OPTIONS_NHC98</literal> pragma in the
ijones's avatar
ijones committed
939
                source file affected.</para>
940
941
942

              <para>Warning: Cabal does not currently support building
                libraries or executables with nhc98 anyway.</para>
ijones's avatar
ijones committed
943
944
945
946
            </listitem>
          </varlistentry>

          <varlistentry>
947
948
            <term>
              <literal>includes:</literal>
ijones's avatar
ijones committed
949
              <replaceable>filename list</replaceable>
950
            </term>
ijones's avatar
ijones committed
951
            <listitem>
952
953
954
955
956
957
              <para>A list of header files to be included in any
              compilations via C.  This field applies to both header
              files that are already installed on the system and to
              those coming with the package to be isntalled.  These files
              typically contain function prototypes for foreign imports
              used by the package.</para>
958
959
960
961
962
963
964
965
966
967
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>
              <literal>install-includes:</literal>
              <replaceable>filename list</replaceable>
            </term>
            <listitem>
              <para>A list of header files from this package to be
968
              installed into
969
              <literal>$libdir/includes</literal> when the package
970
971
              is installed.  Files listed in
              <literal>install-includes:</literal> should be found in
972
973
              relative to the top of the source tree or relative to one of the
              directories listed in <literal>include-dirs</literal>.</para>
974
975
976
977
978

	      <para><literal>install-includes</literal> is typically
	      used to name header files that contain prototypes for
	      foreign imports used in Haskell code in this package,
	      for which the C implementations are also provided with
979
980
981
	      the package.  Note that to include them when compiling
	      the package itself, they need to be listed in the
	      <literal>includes:</literal> field as well.</para>
ijones's avatar
ijones committed
982
983
984
985
            </listitem>
          </varlistentry>

          <varlistentry>
986
987
988
989
            <term>
              <literal>include-dirs:</literal>
              <replaceable>directory list</replaceable>
            </term>
ijones's avatar
ijones committed
990
            <listitem>
ijones's avatar
ijones committed
991
              <para>A list of directories to search for header files,
Ross Paterson's avatar
Ross Paterson committed
992
993
994
995
                when preprocessing with <command>c2hs</command>,
                <command>hsc2hs</command>, <command>ffihugs</command>,
                <command>cpphs</command> or the C preprocessor,
		and also when compiling via C.</para>
ijones's avatar
ijones committed
996
997
998
999
            </listitem>
          </varlistentry>

          <varlistentry>
1000
1001
1002
1003
            <term>
              <literal>c-sources:</literal>
              <replaceable>filename list</replaceable>
            </term>
ijones's avatar
ijones committed
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
            <listitem>
              <para>A list of C source files to be compiled
                and linked with the Haskell files.</para>

              <para>If you use this field, you should also name the
                C files in <literal>CFILES</literal> pragmas in the
                Haskell source files that use them, e.g.:
                <screen>{-# CFILES dir/file1.c dir/file2.c #-}</screen>
                These are ignored by the compilers, but needed by Hugs.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
1017
            <term>
ijones's avatar
ijones committed
1018
1019
              <literal>extra-libraries:</literal>
              <replaceable>token list</replaceable>
1020
            </term>
ijones's avatar
ijones committed
1021
1022
1023
1024
1025
1026
            <listitem>
              <para>A list of extra libraries to link with.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
1027
1028
            <term>
              <literal>extra-lib-dirs:</literal>
ijones's avatar
ijones committed
1029
              <replaceable>directory list</replaceable>
1030
            </term>
ijones's avatar
ijones committed
1031
1032
1033
1034
1035
1036
            <listitem>
              <para>A list of directories to search for libraries.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
1037
1038
            <term>
              <literal>cc-options:</literal>
ijones's avatar
ijones committed
1039
              <replaceable>token list</replaceable>
1040
            </term>
ijones's avatar
ijones committed
1041
1042
1043
1044
1045
1046
1047
1048
1049
            <listitem>
              <para>Command-line arguments to be passed to the C compiler.
                Since the arguments are compiler-dependent, this field
                is more useful with the setup described in
                <xref linkend="system-dependent"/>.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
1050
1051
            <term>
              <literal>ld-options:</literal>
ijones's avatar
ijones committed
1052
              <replaceable>token list</replaceable>
1053
            </term>
ijones's avatar
ijones committed
1054
1055
1056
1057
1058
1059
1060
1061
            <listitem>
              <para>Command-line arguments to be passed to the linker.
                Since the arguments are compiler-dependent, this field
                is more useful with the setup described in
                <xref linkend="system-dependent"/>.</para>
            </listitem>
          </varlistentry>

1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
          <varlistentry>
            <term>
              <literal>pkgconfig-depends:</literal>
              <replaceable>package list</replaceable>
            </term>
            <listitem>
              <para>A list of &PkgConfig; packages, needed to build this
                package. They can be annotated with versions,
                e.g. <literal>gtk+-2.0 >= 2.10, cairo >= 1.0</literal>.
                If no version constraint is specified, any version is
                assumed to be acceptable. Cabal uses
                <literal>pkg-config</literal> to find if the packages are
                available on the system and to find the extra compilation and
                linker options needed to use the packages.
              </para>
              <para> If you need to bind to a C library that supports
                <literal>pkg-config</literal> (use
                <literal>pkg-config --list-all</literal> to find out if it is
                supported) then it is much preferable to use this field rather
                than hard code options into the other fields.
              </para>
            </listitem>
          </varlistentry>

ijones's avatar
ijones committed
1086
          <varlistentry>
1087
1088
            <term>
              <literal>frameworks:</literal>
ijones's avatar
ijones committed
1089
              <replaceable>token list</replaceable>
1090
            </term>
ijones's avatar
ijones committed
1091
            <listitem>
ijones's avatar
ijones committed
1092
1093
1094
1095
              <para>On Darwin/MacOS X, a list of frameworks to link to.
                See Apple's developer documentation for more details
                on frameworks.  This entry is ignored on all other
                platforms.</para>
ijones's avatar
ijones committed
1096
1097
1098
            </listitem>
          </varlistentry>
        </variablelist>
ijones's avatar
ijones committed
1099
      </sect3>
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114

      <sect3 id="configurations">
	<title>Configurations</title>
	<para>Library and executable sections may include conditional
	blocks, which test for various system parameters and
	configuration flags.  The flags mechanism is rather generic,
	but most of the time a flag represents certain feature, that
	can be switched on or off by the package user.</para>
	<para>Here is an example package description file using
	configurations:</para>
	<example id="package-with-configurations-example">
	  <title>A package containing a library and executable programs</title>

	<programlisting>Name: Test1
Version: 0.0.1
1115
Cabal-Version: >= 1.2
1116
1117
1118
1119
1120
License: BSD3
Author:  Jane Doe
Synopsis: Test package to test configurations
Category: Example

1121
Flag Debug
1122
1123
1124
  Description: Enable debug support
  Default:     False

1125
Flag WebFrontend
1126
  Description: Include API for web frontend.
1127
1128
  -- Cabal checks if the configuration is possible, first
  -- with this flag set to True and if not it tries with False
1129

1130
Library
1131
1132
1133
1134
  Build-Depends:   base
  Exposed-Modules: Testing.Test1
  Extensions:      CPP

1135
  if flag(debug)
1136
    GHC-Options: -DDEBUG
1137
    if !os(windows)
1138
      CC-Options: "-DDEBUG"
1139
    else
1140
1141
      CC-Options: "-DNDEBUG"

1142
  if flag(webfrontend)
1143
    Build-Depends: cgi > 0.42
1144
    Other-Modules: Testing.WebStuff
1145

1146
Executable test1
1147
1148
1149
1150
  Main-is: T1.hs
  Other-Modules: Testing.Test1
  Build-Depends: base

1151
  if flag(debug)
1152
1153
    CC-Options: "-DDEBUG"
    GHC-Options: -DDEBUG
1154
</programlisting>
1155
	</example>
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
	<sect4>
	 <title>Layout</title>
	 <para>Flags, conditionals, library and executable sections use layout to
     indicate structure. This is very similar to the Haskell layout rule.
     Entries in a section have to all be indented to the same level which must
     be more than the section header. Tabs are not allowed to be used for
     indentation.</para>

	 <para>As an alternative to using layout you can also use explicit braces
     <literal>{}</literal>. In this case the indentation of entries in a
     section does not matter, though different fields within a block must be
     on different lines. Here is a bit of the above example again, using
     braces:</para>
   <example id="configurations-with-braces-example">
	  <title>Using explicit braces rather than indentation for layout</title>

	  <programlisting>Name: Test1
Version: 0.0.1
Cabal-Version: >= 1.2
License: BSD3
Author:  Jane Doe
Synopsis: Test package to test configurations
Category: Example

Flag Debug {
  Description: Enable debug support
  Default:     False
}

Library {
  Build-Depends:   base
  Exposed-Modules: Testing.Test1
  Extensions:      CPP
  if flag(debug) {
    GHC-Options: -DDEBUG
1191
    if !os(windows) {
1192
1193
1194
1195
1196
1197
1198
1199
1200
      CC-Options: "-DDEBUG"
    } else {
      CC-Options: "-DNDEBUG"
    }
  }
}
</programlisting>
	  </example>
	</sect4>
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
	<sect4>
	 <title>Configuration Flags</title>
	 <para>A flag section takes the flag name as an argument and
	 may contain the following fields.</para>
	 <variablelist>
          <varlistentry>
            <term>
              <literal>description:</literal>
              <replaceable>freeform</replaceable>
            </term>
            <listitem>
              <para>The description of this flag.</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <literal>default:</literal>
              <replaceable>Boolean</replaceable>
	      (default: <literal>True</literal>)
            </term>
            <listitem>
              <para>The default value of this flag.</para>
	      <para>Note that this value may be overridden in several
	      ways (see <xref linkend="flag-control"/>).  The
	      rationale for having flags default to True is that users
	      usually want new features as soon as they are available.
	      Flags representing features that are not (yet)
	      recommended for most users (such as experimental
	      features or debugging support) should therefore
	      explicitly override the default to False.</para>
            </listitem>
          </varlistentry>
        </variablelist>
	</sect4>
	<sect4 id="conditionals">
	  <title>Conditional Blocks</title>
	  <para>Conditional blocks may appear anywhere inside a
	  library or executable section.  They have to follow rather
	  strict formatting rules.</para>
	  <para>Conditional blocks must always be of the shape
	  <literallayout>
1242
1243
1244
1245
1246
1247
1248
1249
	    <literal>if </literal><replaceable>condition</replaceable>
	         <replaceable>property-descriptions-or-conditionals*</replaceable>
    </literallayout>or
	  <literallayout>
	    <literal>if </literal><replaceable>condition</replaceable>
	         <replaceable>property-descriptions-or-conditionals*</replaceable>
	    <literal>else</literal>
	         <replaceable>property-descriptions-or-conditionals*</replaceable>
1250
1251
	  </literallayout></para>

1252
1253
	  <para>Note that the <literal>if</literal> and the condition have to
	  be all on the same line.</para>
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278

	</sect4>
	<sect4 id="conditions">
	  <title>Conditions</title>
	  <para>Conditions can be formed using boolean tests and the
	  boolean operators <literal>||</literal> (disjunction /
	  logical "or"), <literal>&amp;&amp;</literal> (conjunction /
	  logical "and"), or <literal>!</literal> (negation / logical
	  "not").  The unary <literal>!</literal> takes highest
	  precedence, <literal>||</literal> takes lowest.  Precedence
	  levels may be overridden through the use of parentheses.
	  For example, <literal>os(darwin) &amp;&amp; !arch(i386) || os(freebsd)</literal>
          is equivalent to <literal>(os(darwin) &amp;&amp; !(arch(i386))) || os(freebsd)</literal>.
	  </para>
	  <para>The following tests are currently supported.</para>
	  <variablelist>
	    <varlistentry>
	      <term>
		<literal>os(</literal>
		<replaceable>name</replaceable>
		<literal>)</literal>
	      </term>
            <listitem>
              <para>Tests if the current operating system is
              <replaceable>name</replaceable>.  The argument is tested
1279
1280
1281
1282
1283
1284
1285
1286
              against <literal>System.Info.os</literal> on 
              the target system. There is unfortunately some disagreement
              between Haskell implementations about the standard values of
              <literal>System.Info.os</literal>. Cabal canonicalises it so
              that in particular <literal>os(windows)</literal> works on all
              implementations. If the canonicalised os names match, this test
              evaluates to true, otherwise false. The match is
              case-insensitive. </para>
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
            </listitem>
          </varlistentry>
	    <varlistentry>
	      <term>
		<literal>arch(</literal>
		<replaceable>name</replaceable>
		<literal>)</literal>
	      </term>
            <listitem>
              <para>Tests if the current architecture is
1297
1298
1299
1300
              <replaceable>name</replaceable>.  The argument is matched
              against <literal>System.Info.arch</literal> on the target system.
              If the arch names match, this test evaluates to true,
              otherwise false. The match is case-insensitive. </para>
1301
1302
1303
1304
1305
1306
1307
1308
1309
            </listitem>
          </varlistentry>
	  <varlistentry>
	      <term>
		<literal>impl(</literal>
		<replaceable>compiler</replaceable>
		<literal>)</literal>
	      </term>
            <listitem>
1310
              <para>Tests for the configured Haskell implementation. An optional
1311
1312
              version constraint may be specified (for example
              <literal>impl(ghc >= 6.6.1)</literal>).  If the
1313
              configured implementation is of the right type and matches the
1314
              version constraint, then this evaluates to true,
1315
              otherwise false. The match is case-insensitive.</para>
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
            </listitem>
          </varlistentry>
	  <varlistentry>
	      <term>
		<literal>flag(</literal>
		<replaceable>name</replaceable>
		<literal>)</literal>
	      </term>
            <listitem>
              <para>Evaluates to the current assignment of the flag of
              the given name.  Flag names are case insensitive.
              Testing for flags that have not been introduced with a
              flag section is an error.</para>
            </listitem>
          </varlistentry>
	  <varlistentry>
	      <term>
		<literal>true</literal>
	      </term>
            <listitem>
1336
              <para>Constant value true.</para>
1337
1338
1339
1340
1341
1342
1343
            </listitem>
          </varlistentry>
	  <varlistentry>
	      <term>
		<literal>false</literal>
	      </term>
            <listitem>
1344
              <para>Constant value false.</para>
1345
1346
1347
1348
            </listitem>
          </varlistentry>
        </variablelist>

1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
	</sect4>
	<sect4 id="conditional-resolution">
	  <title>Resolution of Conditions and Flags</title>
	  <para>If a package descriptions specifies configuration flags
	  the package user can control these in several ways (see
          <xref linkend="flag-control"/>). If the user does not fix the
          value of a flag, Cabal will try to find a flag assignment in the
	  following way.</para>
	  <itemizedlist>
	    <listitem>
	      <para>For each flag specified, it will assign its default
	      value, evaluate all conditions with this flag assignment,
	      and check if all dependencies can be satisfied.  If this
	      check succeeded, the package will be configured with those
	      flag assignments.</para>
	    </listitem>
	    <listitem>
	      <para>If dependencies were missing, the last flag (as by
	      the order in which the flags were introduced in the
	      package description) is tried with its alternative value
	      and so on.  This continues until either an assignment is
	      found where all dependencies can be satisfied, or all
	      possible flag assignments have been tried.</para>
	    </listitem>
	  </itemizedlist>

          <para>To put it another way, Cabal does a complete backtracking
          search to find a satisfiable packge configuration. It is only the
          dependencies specified in the <literal>build-depends</literal> field
          in conditional blocks that determine if a particular flag assignment
          is satisfiable (<literal>build-tools</literal> are not considered).
          The order of the declaration and the default value of the flags
          determines the search order. Flags overriden on the command line fix
          the assignment of that flag, so no backtracking will be tried for
          that flag.</para>

	  <para>If no suitable flag assignment could be found, the
	  configuration phase will fail and a list of missing
	  dependencies will be printed.  Note that this resolution
	  process is exponential in the worst case (i.e., in the case
	  where dependencies cannot be satisfied).  There are some
	  optimizations applied internally, but the overall complexity
	  remains unchanged.</para>
1392
1393
	</sect4>
	<sect4 id="prop-combine">
1394
          <title>Meaning of field values when using conditionals</title>
1395
	  <para>During the configuration phase, a flag assignment is
1396
1397
1398
1399
	  chosen, all conditionals are evaluated, and the package description
          is combined into a flat package descriptions. If the same field
	  both inside a conditional and outside then they are combined using
          the following rules.</para>
1400
1401
1402
1403
1404
1405
1406
1407
1408
	  <itemizedlist>
	    <listitem>
	      <para>Boolean fields are combined using conjunction
	      (logical "and").</para>
	    </listitem>
	    <listitem>
	      <para>List fields are combined by appending the inner
	      items to the outer items, for example
	      <programlisting>Extensions: CPP
1409
if impl(ghc) || impl(hugs)
1410
  Extensions: MultiParamTypeClasses
1411
</programlisting>
1412
	    when compiled using Hugs or GHC will be combined to
1413
	    <programlisting>Extensions: CPP, MultiParamTypeClasses</programlisting>
1414
1415
1416
1417
1418
1419
1420
1421
	    </para>
	    <para>Similarly, if two conditional sections appear at the
	    same nesting level, properties specified in the latter
	    will come after properties specified in the former.</para>
	    </listitem>
	    <listitem>
	      <para>All other fields must not be specified in ambiguous ways.  For example
	      <programlisting>Main-is: Main.hs
1422
if flag(useothermain)
1423
  Main-is: OtherMain.hs
1424
</programlisting>
1425
	      will lead to an error.  Instead use
1426
	      <programlisting>if flag(useothermain)
1427
  Main-is: OtherMain.hs
1428
else
1429
  Main-is: Main.hs
1430
</programlisting></para>
1431
1432
1433
1434
	    </listitem>
	  </itemizedlist>
	</sect4>
      </sect3>
ijones's avatar
ijones committed
1435
    </sect2>
ijones's avatar
ijones committed
1436

ijones's avatar
ijones committed
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
    <sect2 id="paths-module">
      <title>Accessing data files from package code</title>
      <para>The placement on the target system of files listed in the
	<literal>data-files</literal> field varies between systems, and in
	some cases one can even move packages around after installation
	(see <xref linkend="prefix-independence"/>).  To enable packages
	to find these files in a portable way, Cabal generates a module
	called <literal>Paths_</literal><replaceable>pkgname</replaceable>
	(with any hyphens in <replaceable>pkgname</replaceable> replaced
	by underscores) during building, so that it may be imported by
	modules of the package.  This module defines a function
	<programlisting>getDataFileName :: FilePath -> IO FilePath</programlisting>
	If the argument is a filename listed in the
	<literal>data-files</literal> field, the result is the name
	of the corresponding file on the system on which the program
	is running.</para>
    </sect2>

ijones's avatar
ijones committed
1455
    <sect2 id="system-dependent">
ijones's avatar
ijones committed
1456
      <title>System-dependent parameters</title>
ijones's avatar
ijones committed
1457

ijones's avatar
ijones committed
1458
1459
      <para>For some packages, especially those interfacing with C
        libraries, implementation details and the build procedure depend
1460
1461
1462
1463
        on the build environment.  A variant of the simple build
        infrastructure (the <literal>build-type</literal>
        <literal>Configure</literal>) handles many such situations using
        a slightly longer <filename>Setup.hs</filename>:</para>
ijones's avatar
ijones committed
1464
1465
1466
      <programlisting>
import Distribution.Simple
main = defaultMainWithHooks defaultUserHooks</programlisting>
1467

ijones's avatar
ijones committed
1468
1469
      <para>This program differs from <literal>defaultMain</literal>
        in two ways:</para>
ijones's avatar
ijones committed
1470
1471
1472
1473
      <orderedlist>
        <listitem>
          <para>If the package root directory contains a file called
            <filename>configure</filename>, the configure step will
1474
            run that.  This <filename>configure</filename> program may
ijones's avatar
ijones committed
1475
            be a script produced by the &Autoconf;
1476
1477
1478
1479
1480
1481
            system, or may be hand-written.  This program typically
            discovers information about the system and records it for
            later steps, e.g. by generating system-dependent header files
            for inclusion in C source files and preprocessed Haskell
            source files.  (Clearly this won't work for Windows without
            MSYS or Cygwin: other ideas are needed.)</para>
ijones's avatar
ijones committed
1482
1483
1484
        </listitem>

        <listitem>
ijones's avatar
ijones committed
1485
          <para>If the package root directory contains a file called
ijones's avatar
ijones committed
1486
            <replaceable>package</replaceable><literal>.buildinfo</literal>
ijones's avatar
ijones committed
1487
1488
            after the configuration step, subsequent steps will read it
            to obtain additional settings for build information fields
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
            (see <xref linkend="buildinfo"/>), to be merged with the
            ones given in the <literal>.cabal</literal> file.
            In particular, this file may be generated by the
            <filename>configure</filename> script mentioned above,
            allowing these settings to vary depending on the build
            environment.</para>

          <para>The build information file should have the following
            structure:</para>
          <programlisting>
ijones's avatar
ijones committed
1499
1500
1501
1502
1503
1504
1505
1506
1507
<replaceable>buildinfo</replaceable>

executable: <replaceable>name</replaceable>
<replaceable>buildinfo</replaceable>

executable: <replaceable>name</replaceable>
<replaceable>buildinfo</replaceable>

...</programlisting>
1508
1509
1510
1511
1512
1513
          <para>where each <replaceable>buildinfo</replaceable> consists
            of settings of fields listed in <xref linkend="buildinfo"/>.
            The first one (if present) relates to the library, while each
            of the others relate to the named executable.  (The names
            must match the package description, but you don't have to
            have entries for all of them.)</para>
ijones's avatar
ijones committed
1514

1515
1516
        </listitem>
      </orderedlist>
ijones's avatar
ijones committed
1517

<