1
<?xml version="1.0" encoding="US-ASCII"?>
2
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
5
<!ENTITY Simple '<ulink url="../libraries/Cabal/Distribution-Simple.html">Distribution.Simple</ulink>'>
6
<!ENTITY Make '<ulink url="../libraries/Cabal/Distribution-Make.html">Distribution.Make</ulink>'>
7
<!ENTITY License '<ulink url="../libraries/Cabal/Distribution-License.html#t:License"><literal>License</literal></ulink>'>
8
<!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>'>
10
<!ENTITY Alex '<ulink url="http://www.haskell.org/alex/"><command>alex</command></ulink>'>
11
<!ENTITY Autoconf '<ulink url="http://www.gnu.org/software/autoconf/"><command>autoconf</command></ulink>'>
12
<!ENTITY C2hs '<ulink url="http://www.cse.unsw.edu.au/~chak/haskell/c2hs/"><command>c2hs</command></ulink>'>
13
<!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>'>
15
<!ENTITY Haddock '<ulink url="http://www.haskell.org/haddock/"><command>haddock</command></ulink>'>
16
<!ENTITY HsColour '<ulink url="http://www.cs.york.ac.uk/fp/darcs/hscolour/"><command>HsColour</command></ulink>'>
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>'>
23
<title>Common Architecture for Building Applications and Libraries</title>
24
<subtitle>User's Guide</subtitle>
27
<para><firstterm>Cabal</firstterm> aims to simplify the
28
distribution of <ulink url="http://www.haskell.org/">Haskell</ulink>
29
software. It does this by specifying a number of interfaces between
30
package authors, builders and users, as well as providing a library
31
implementing these interfaces.</para>
35
<title>Introduction</title>
37
Developers write Cabal packages. These can be for libraries or
38
executables. This involves writing the code obviously and also creating a
39
<literal>.cabal</literal> file. The .cabal file contains some information
40
about the package. Some of this information is needed to actually build
41
the package and some is just useful for identifying the package when it
42
comes to distribution.
53
Users install Cabal packages so they can use them. It is not expected
54
that users will have to modify any of the information in the
55
<literal>.cabal</literal> file. Cabal does provide a number of ways for
56
a user to customise how and where a package is installed. They can decide
57
where a package will be installed, which Haskell implementation to use
58
and whether to build optimised code or build with the ability to profile
62
tar -xzf Foo-1.0.tar.gz
64
runhaskell Setup configure --with-compiler=ghc-6.4.2 --user
65
runhaskell Setup build
66
runhaskell Setup install
69
One of the purposes of Cabal is to make it easier to build a package with
70
different Haskell implementations. So it provides abstractions of
71
features present in different Haskell implementations and wherever
72
possible it is best to take advantage of these to increase portability.
73
Where necessary however it is possible to use specific features of
74
specific implementations. For example one of the pieces of information a
75
package author can put in the package's <literal>.cabal</literal> file is
76
what language extensions the code uses. This is far preferable to
77
specifying flags for a specific compiler as it allows Cabal to pick the
78
right flags for the Haskell implementation that the user picks. It also
79
allows Cabal to figure out if the language extension is even supported by
80
the Haskell implementation that the user picks. Where compiler-specific
81
options are needed however, there is an "escape hatch" available. The
82
developer can specify implementation-specific options and more generally
83
there is a configuration mechanism to customise many aspects of how a
84
package is built depending on the Haskell implementation, the Operating
85
system, computer architecture and user-specified configuration flags.
94
extensions: ForeignFunctionInterface
102
<sect1 id="packages">
103
<title>Packages</title>
105
<para>A <firstterm>package</firstterm> is the unit of distribution
106
for the Cabal. Its purpose, when installed, is to make available
107
either or both of:</para>
110
<para>A library, exposing a number of Haskell modules. A library
111
may also contain <firstterm>hidden</firstterm> modules, which
112
are used internally but not available to clients.<footnote>
113
<para>Hugs doesn't support module hiding.</para>
119
<para>One or more Haskell programs.</para>
122
<para>However having both a library and executables in a package
123
does not work very well; if the executables depend on the library,
124
they must explicitly list all the modules they directly or
125
indirectly import from that library.</para>
127
<para>Internally, the package may consist of much more than a
128
bunch of Haskell modules: it may also have C source code and
129
header files, source code meant for preprocessing, documentation,
130
test cases, auxiliary tools etc.</para>
132
<para>A package is identified by a globally-unique
133
<firstterm>package name</firstterm>, which consists of one or
134
more alphanumeric words separated by hyphens. To avoid ambiguity,
135
each of these words should contain at least one letter.
136
Chaos will result if two distinct packages with the
137
same name are installed on the same system, but there is not
138
yet a mechanism for allocating these names.
139
A particular version of the package is distinguished by a
140
<firstterm>version number</firstterm>, consisting of a sequence
141
of one or more integers separated by dots. These can be combined
142
to form a single text string called the <firstterm>package
143
ID</firstterm>, using a hyphen to separate the name from the
144
version, e.g. <quote><literal>HUnit-1.1</literal></quote>.</para>
147
<para>Packages are not part of the Haskell language;
148
they simply populate the hierarchical space of module names.
149
In GHC 6.6 and later a program may contain multiple modules
150
with the same name if they come from separate packages; in all
151
other current Haskell systems packages may not overlap in the
152
modules they provide, including hidden modules.</para>
157
<title>Creating a package</title>
159
<para>Suppose you have a directory hierarchy containing the source
160
files that make up your package. You will need to add two more
161
files to the root directory of the package:</para>
165
<filename><replaceable>package</replaceable>.cabal</filename>
168
<para>a Unicode UTF-8 text file containing a package description
169
(for details of the syntax of this file, see
170
<xref linkend="pkg-descr"/>)</para>
176
<filename>Setup.hs</filename> or
177
<filename>Setup.lhs</filename>
180
<para>a single-module Haskell program to perform various
181
setup tasks (with the interface described in
182
<xref linkend="builders"/>). This module should import only
183
modules that will be present in all Haskell implementations,
184
including modules of the Cabal library. In most cases it
185
will be trivial, calling on the Cabal library to do most of
190
<para>Once you have these, you can create a source bundle of this
191
directory for distribution. Building of the package is discussed in
192
<xref linkend="builders"/>.</para>
194
<example id="simple-library-example">
195
<title>A package containing a simple library</title>
196
<para>The HUnit package contains a file <filename>HUnit.cabal</filename>
201
Cabal-Version: >= 1.2
203
License-File: LICENSE
204
Author: Dean Herington
205
Homepage: http://hunit.sourceforge.net/
207
Synopsis: A unit testing framework for Haskell
212
Test.HUnit.Base, Test.HUnit.Lang, Test.HUnit.Terminal,
213
Test.HUnit.Text, Test.HUnit
216
<para>and the following <filename>Setup.hs</filename>:</para>
218
import Distribution.Simple
219
main = defaultMain</programlisting>
222
<example id="simple-executable-example">
223
<title>A package containing executable programs</title>
227
Cabal-Version: >= 1.2
229
Author: Angela Author
230
Synopsis: Small package with two programs
236
Hs-Source-Dirs: prog1
241
Hs-Source-Dirs: prog2
244
<para>with <filename>Setup.hs</filename> the same as above.</para>
247
<example id="simple-library-executable-example">
248
<title>A package containing a library and executable programs</title>
252
Cabal-Version: >= 1.2
254
Author: Angela Author
255
Synopsis: Package with library and two programs
260
Exposed-Modules: A, B, C
264
Hs-Source-Dirs: prog1
269
Hs-Source-Dirs: prog2
270
Other-Modules: A, C, Utils
272
<para>with <filename>Setup.hs</filename> the same as above.
273
Note that any library modules required (directly or indirectly)
274
by an executable must be listed again.</para>
277
<para>The trivial setup script used in these examples uses
278
the <firstterm>simple build infrastructure</firstterm>
279
provided by the Cabal library (see &Simple;).
280
The simplicity lies in its interface rather that its implementation.
281
It automatically handles preprocessing with standard preprocessors,
282
and builds packages for all the Haskell implementations (except
283
nhc98, for now).</para>
285
<para>The simple build infrastructure can also handle packages
286
where building is governed by system-dependent parameters,
287
if you specify a little more (see <xref linkend="system-dependent"/>).
288
A few packages require more elaborate solutions
289
(see <xref linkend="complex-packages"/>).</para>
291
<sect2 id="pkg-descr">
292
<title>Package descriptions</title>
294
<para>The package description file must have a name ending in
295
<quote><literal>.cabal</literal></quote>. It must be a Unicode text
296
file encoded using valid UTF-8. There must be exactly
297
one such file in the directory. The first part of the name is
298
usually the package name, and some of the tools that operate
299
on Cabal packages require this.</para>
301
<para>In the package description file, lines whose first
302
non-whitespace characters
303
are <quote><literal>--</literal></quote> are treated as comments
306
<para>This file should contain of a number global property
307
descriptions and several sections.</para>
311
<para>The global properties describe the package as a whole,
312
such as name, license, author, etc. (see <xref
313
linkend="general-fields"/>).</para>
316
<para>Optionally, a number of <firstterm>configuration
317
flags</firstterm> can be declared. These can be used to
318
enable or disable certain features of a package. (see <xref
319
linkend="configurations"/>).</para>
322
<para>The (optional) library section specifies the library
323
properties (see <xref linkend="library"/>) and relevant build
324
information (see <xref linkend="buildinfo"/>).</para>
327
<para>Following is an arbitrary number of executable sections
328
which describe an executable program and (see <xref
329
linkend="executable"/>) relevant build information (see <xref
330
linkend="buildinfo"/>).</para>
334
<para>Each section consists of a number of property descriptions
335
in the form of field/value pairs, with a syntax roughly like mail
336
message headers.</para>
339
<para>Case is not significant in field names,
340
but is significant in field values.</para>
343
<para>To continue a field value, indent the next line
344
relative to the field name.</para>
347
<para>Field names may be indented, but all field values in
348
the same section must use the same indentation.</para>
351
<para>Tabs are <emphasis>not</emphasis> allowed as
352
indentation characters due to a missing standard
353
interpretation of tab width.</para>
356
<para>To get a blank line in a field value, use an indented
357
<quote><literal>.</literal></quote></para>
360
<para>The syntax of the value depends on the field. Field types
366
<replaceable>token</replaceable>
369
<replaceable>filename</replaceable>
372
<replaceable>directory</replaceable>
375
<para>Either a sequence of one or more non-space non-comma
376
characters, or a quoted string in Haskell 98 lexical syntax.
377
Unless otherwise stated, relative filenames and directories
378
are interpreted from the package root directory.</para>
384
<replaceable>freeform</replaceable>
387
<replaceable>URL</replaceable>
390
<replaceable>address</replaceable>
393
<para>An arbitrary, uninterpreted string.</para>
399
<replaceable>identifier</replaceable>
402
<para>A letter followed by zero or more alphanumerics
403
or underscores.</para>
409
<replaceable>compiler</replaceable>
412
<para>A compiler flavor (one
413
of: <literal>GHC</literal>, <literal>NHC</literal>,
414
<literal>YHC</literal>, <literal>Hugs</literal>,
415
<literal>HBC</literal>, <literal>Helium</literal>,
416
<literal>JHC</literal>, or <literal>LHC</literal>)
417
followed by a version range. For example,
418
<literal>GHC ==6.10.3</literal>,
419
or <literal>LHC >=0.6 && <0.8</literal>.
426
<title>Modules and preprocessors</title>
427
<para>Haskell module names listed in the
428
<literal>exposed-modules</literal> and
429
<literal>other-modules</literal> fields may
430
correspond to Haskell source files, i.e. with names
431
ending in <quote><literal>.hs</literal></quote> or
432
<quote><literal>.lhs</literal></quote>, or to inputs for
433
various Haskell preprocessors.
434
The simple build infrastructure understands the extensions
435
<quote><literal>.gc</literal></quote> (&Greencard;),
436
<quote><literal>.chs</literal></quote> (&C2hs;),
437
<quote><literal>.hsc</literal></quote> (<command>hsc2hs</command>),
438
<quote><literal>.y</literal></quote> and
439
<quote><literal>.ly</literal></quote> (&Happy;),
440
<quote><literal>.x</literal></quote> (&Alex;)
442
<quote><literal>.cpphs</literal></quote> (&Cpphs;).
443
When building, Cabal will automatically run the appropriate
444
preprocessor and compile the Haskell module it produces.</para>
447
<para>Some fields take lists of values, which
448
are optionally separated by commas, except for the
449
<literal>build-depends</literal> field, where the commas are
452
<para>Some fields are marked as required. All others are optional,
453
and unless otherwise specified have empty default values.</para>
455
<sect3 id="general-fields">
456
<title>Package properties</title>
458
<para>These fields may occur in the first top-level properties
459
section and describe the package as a whole:</para>
464
<literal>name:</literal> <replaceable>package-name</replaceable>
468
<para>The unique name of the package
469
(see <xref linkend="packages"/>), without the version
476
<literal>version:</literal> <replaceable>numbers</replaceable>
480
<para>The package version number, usually consisting of a
481
sequence of natural numbers separated by dots.</para>
487
<literal>cabal-version:</literal> <replaceable>>, <=, etc. & numbers</replaceable>
490
<para>The version of Cabal required for this package.
491
Since, with Cabal version 1.2 the syntax of package
492
descriptions has changed, this is now a required field.
493
List the field early in your <literal>.cabal</literal>
494
file so that it will appear as a syntax error before any
495
others, since old versions of Cabal unfortunately do not
496
recognize this field.</para>
497
<para>For compatibility, files written in the old syntax
498
are still recognized. Thus if you don't require
499
features introduced with or after Cabal version 1.2, you
500
may write your package description file using the old
501
syntax. Please consult the user's guide of that Cabal
502
version for a description of that syntax.</para>
508
<literal>build-type:</literal> <replaceable>identifier</replaceable>
511
<para>The type of build used by this package.
512
Build types are the constructors of the &BuildType; type,
513
defaulting to <literal>Custom</literal>.
514
If this field is given a value other than
515
<literal>Custom</literal>, some tools such as
516
<literal>cabal-install</literal> will be able to
517
build the package without using the setup script. So if you are
518
just using the default <literal>Setup.hs</literal> then set
519
the build type as <literal>Simple</literal>.</para>
525
<literal>license:</literal> <replaceable>identifier</replaceable>
526
(default: <literal>AllRightsReserved</literal>)
529
<para>The type of license under which this package is
530
distributed. License names are the constants of the
531
&License; type.</para>
537
<literal>license-file:</literal>
538
<replaceable>filename</replaceable>
541
<para>The name of a file containing the precise license
542
for this package. It will be installed with the package.
549
<literal>copyright:</literal>
550
<replaceable>freeform</replaceable>
553
<para>The content of a copyright notice, typically the
554
name of the holder of the copyright on the package and
555
the year(s) from which copyright is claimed.</para>
557
<literal>Copyright: (c) 2006-2007 Joe Bloggs</literal>
564
<literal>author:</literal>
565
<replaceable>freeform</replaceable>
568
<para>The original author of the package.</para>
574
<literal>maintainer:</literal>
575
<replaceable>address</replaceable>
578
<para>The current maintainer or maintainers of the package.
579
This is an e-mail address to which users should send bug
580
reports, feature requests and patches.</para>
586
<literal>stability:</literal>
587
<replaceable>freeform</replaceable>
590
<para>The stability level of the package, e.g.
591
<literal>alpha</literal>, <literal>experimental</literal>,
592
<literal>provisional</literal>,
593
<literal>stable</literal>.</para>
599
<literal>homepage:</literal> <replaceable>URL</replaceable>
602
<para>The package homepage.</para>
608
<literal>bug-reports:</literal> <replaceable>URL</replaceable>
612
The URL where users should direct bug reports. This would
617
A <literal>mailto:</literal> URL, eg for a person or a
623
An <literal>http:</literal> (or <literal>https:</literal>)
624
URL for an online bug tracking system.
628
For example Cabal itself uses a web-based bug tracking system
629
<programlisting>bug-reports: http://hackage.haskell.org/trac/hackage/</programlisting>
636
<literal>package-url:</literal> <replaceable>URL</replaceable>
639
<para>The location of a source bundle for the package.
640
The distribution should be a Cabal package.</para>
646
<literal>synopsis:</literal>
647
<replaceable>freeform</replaceable>
650
<para>A very short description of the package, for use in
651
a table of packages. This is your headline, so keep
652
it short (one line) but as informative as possible.
653
Save space by not including the package name or saying
654
it's written in Haskell.</para>
660
<literal>description:</literal>
661
<replaceable>freeform</replaceable>
664
<para>Description of the package. This may be several
665
paragraphs, and should be aimed at a Haskell programmer
666
who has never heard of your package before.</para>
668
<para>For library packages, this field is used as
669
prologue text by <command>setup haddock</command>
670
(see <xref linkend="setup-haddock"/>), and thus may
671
contain the same markup as &Haddock; documentation
678
<literal>category:</literal>
679
<replaceable>freeform</replaceable>
682
<para>A classification category for future use by the
683
package catalogue <firstterm>Hackage</firstterm>. These
684
categories have not yet been specified, but the upper
685
levels of the module hierarchy make a good start.</para>
691
<literal>tested-with:</literal>
692
<replaceable>compiler list</replaceable>
695
<para>A list of compilers and versions against which the
696
package has been tested (or at least built).</para>
702
<literal>data-files:</literal>
703
<replaceable>filename list</replaceable>
706
<para>A list of files to be installed for run-time use by
707
the package. This is useful for packages that use a
708
large amount of static data, such as tables of values
709
or code templates. For details on how to find these
710
files at run-time, see
711
<xref linkend="paths-module"/>.</para>
713
A limited form of <literal>*</literal> wildcards in file names,
714
for example <literal>data-files: images/*.png</literal> matches
715
all the <literal>.png</literal> files in the
716
<literal>images</literal> directory.
719
The limitation is that <literal>*</literal> wildcards are only
720
allowed in place of the file name, not in the directory name or
721
file extension. In particular, wildcards do not include
722
directories contents recursively. Furthermore, if a wildcard is
723
used it must be used with an extension, so <literal>data-files:
724
data/*</literal> is not allowed. When matching a wildcard plus
725
extension, a file's full extension must match exactly, so
726
<literal>*.gz</literal> matches <literal>foo.gz</literal> but
727
not <literal>foo.tar.gz</literal>. A wildcard that does not
728
match any files is an error.
731
The reason for providing only a very limited form of wildcard
732
is to concisely express the common case of a large number of
733
related files of the same file type without making it too easy
734
to accidentally include unwanted files.
741
<literal>data-dir:</literal>
742
<replaceable>directory</replaceable>
745
<para>The directory where Cabal looks for data files to install,
746
relative to the source directory. By default, Cabal will look
747
in the source directory itself.</para>
753
<literal>extra-source-files:</literal>
754
<replaceable>filename list</replaceable>
757
<para>A list of additional files to be included in source
758
distributions built with <command>setup sdist</command>
759
(see <xref linkend="setup-sdist"/>).</para>
760
<para>As with <literal>data-files</literal> it can use a limited
761
form of <literal>*</literal> wildcards in file names.</para>
767
<literal>extra-tmp-files:</literal>
768
<replaceable>filename list</replaceable>
771
<para>A list of additional files or directories to be
772
removed by <command>setup clean</command>
773
(see <xref linkend="setup-clean"/>).
774
These would typically be additional files created by
775
additional hooks, such as the scheme described in
776
<xref linkend="system-dependent"/>.</para>
783
<title>Library</title>
785
<para>The library section should contain the following
791
<literal>exposed-modules:</literal>
792
<replaceable>identifier list</replaceable>
793
(required if this package contains a library)
796
<para>A list of modules added by this package.</para>
802
<literal>exposed:</literal> <replaceable>boolean</replaceable>
803
(default: <literal>True</literal>)
807
Some Haskell compilers (notably GHC) support the notion of
808
packages being <quote>exposed</quote> or <quote>hidden</quote>
809
which means the modules they provide can be easily imported
810
without always having to specify which package they come from.
811
However this only works effectively if the modules provided by
812
all exposed packages do not overlap (otherwise a module import
816
Almost all new libraries use hierarchical module names that do
817
not clash, so it is very uncommon to have to use this field.
818
However it may be necessary to set <literal>exposed:
819
False</literal> for some old libraries that use a flat module
820
namespace or where it is known that the exposed modules would
821
clash with other common modules.
828
<para>The library section may also contain build information fields
829
(see <xref linkend="buildinfo"/>).</para>
832
<sect3 id="executable">
833
<title>Executables</title>
835
<para>Executable sections (if present) describe executable
836
programs contained in the package and must have an argument
837
after the section label, which defines the name of the
838
executable. This is a freeform argument but may not contain
841
<para>The executable may be described using the following
842
fields, as well as build information fields (see <xref
843
linkend="buildinfo"/>).</para>
848
<literal>main-is:</literal> <replaceable>filename</replaceable>
852
<para>The name of the <filename>.hs</filename> or
853
<filename>.lhs</filename> file containing the
854
<literal>Main</literal> module. Note that it is the
855
<filename>.hs</filename> filename that must be listed, even if
856
that file is generated using a preprocessor. The source
857
file must be relative to one of the directories listed in
858
<literal>hs-source-dirs</literal>.
866
<sect3 id="buildinfo">
867
<title>Build information</title>
869
<para>The following fields may be optionally present in a
870
library or executable section, and give information for the
871
building of the corresponding library or executable. See also
872
<xref linkend="system-dependent"/> and <xref linkend="configurations"/>
873
for a way to supply system-dependent values for these
879
<literal>build-depends:</literal>
880
<replaceable>package list</replaceable>
883
<para>A list of packages needed to build this one. Each package
884
can be annotated with a version constraint.
887
Version constraints use the operators <literal>==, >=, >,
888
<, <=</literal> and a version number. Multiple
889
constraints can be combined using <literal>&&</literal>
890
or <literal>||</literal>. If no version constraint is
891
specified, any version is assumed to be acceptable.
898
foo >= 1.2 && < 1.3,
902
Dependencies like <literal>foo >= 1.2 && < 1.3</literal> turn
903
out to be very common because it is recommended practise for
904
package versions to correspond to API versions. There is a
905
special syntax to support this use:
907
<programlisting>build-depends: foo ==1.2.*</programlisting>
909
It is only syntactic sugar. It is exactly equivalent to
910
<literal>foo >= 1.2 && < 1.3</literal>.
917
<literal>other-modules:</literal>
918
<replaceable>identifier list</replaceable>
921
<para>A list of modules used by the component
922
but not exposed to users. For a library component, these
923
would be hidden modules of the library. For an executable,
924
these would be auxiliary modules to be linked with the
925
file named in the <literal>main-is</literal> field.</para>
927
<para>Every module in the package <emphasis>must</emphasis> be
928
listed in one of <literal>other-modules</literal>,
929
<literal>exposed-modules</literal> or
930
<literal>main-is</literal> fields.
938
<literal>hs-source-dirs:</literal>
939
<replaceable>directory list</replaceable>
940
(default: <quote><literal>.</literal></quote>)
943
<para>Root directories for the module hierarchy.</para>
945
<para>For backwards compatibility, the old variant
946
<literal>hs-source-dir</literal> is also recognized.</para>
951
<literal>extensions:</literal>
952
<replaceable>identifier list</replaceable>
955
<para>A list of Haskell extensions used by every module.
956
Extension names are the constructors of the &Extension; type.
957
These determine corresponding compiler options.
958
In particular, <literal>CPP</literal> specifies that
959
Haskell source files are to be preprocessed with a
960
C preprocessor.</para>
962
<para>Extensions used only by one module may be specified
963
by placing a <literal>LANGUAGE</literal> pragma in the
964
source file affected, e.g.:</para>
965
<programlisting>{-# LANGUAGE CPP, MultiParamTypeClasses #-}</programlisting>
967
<para>GHC versions prior to 6.6 do not support the
968
<literal>LANGUAGE</literal> pragma.</para>
975
<literal>build-tools:</literal>
976
<replaceable>program list</replaceable>
979
<para>A list of programs, possibly annotated with versions,
980
needed to build this package,
981
e.g. <literal>c2hs > 0.15, cpphs</literal>.
982
If no version constraint is specified, any version is
983
assumed to be acceptable.</para>
989
<literal>buildable:</literal> <replaceable>boolean</replaceable>
990
(default: <literal>True</literal>)
993
<para>Is the component buildable?
994
Like some of the other fields below, this field is
995
more useful with the slightly more elaborate form of
996
the simple build infrastructure described in
997
<xref linkend="system-dependent"/>.</para>
1003
<literal>ghc-options:</literal>
1004
<replaceable>token list</replaceable>
1007
<para>Additional options for GHC. You can often achieve
1008
the same effect using the <literal>extensions</literal>
1009
field, which is preferred.</para>
1011
<para>Options required only by one module may be specified
1012
by placing an <literal>OPTIONS_GHC</literal> pragma in the
1013
source file affected.</para>
1019
<literal>ghc-prof-options:</literal>
1020
<replaceable>token list</replaceable>
1023
<para>Additional options for GHC when the package is built
1024
with profiling enabled.</para>
1030
<literal>ghc-shared-options:</literal>
1031
<replaceable>token list</replaceable>
1034
<para>Additional options for GHC when the package is
1035
built as shared library.</para>
1041
<literal>hugs-options:</literal>
1042
<replaceable>token list</replaceable>
1045
<para>Additional options for Hugs. You can often achieve
1046
the same effect using the <literal>extensions</literal>
1047
field, which is preferred.</para>
1049
<para>Options required only by one module may be specified
1050
by placing an <literal>OPTIONS_HUGS</literal> pragma in the
1051
source file affected.</para>
1057
<literal>nhc98-options:</literal>
1058
<replaceable>token list</replaceable>
1061
<para>Additional options for nhc98. You can often achieve
1062
the same effect using the <literal>extensions</literal>
1063
field, which is preferred.</para>
1065
<para>Options required only by one module may be specified
1066
by placing an <literal>OPTIONS_NHC98</literal> pragma in the
1067
source file affected.</para>
1069
<para>Warning: Cabal does not currently support building
1070
libraries or executables with nhc98 anyway.</para>
1076
<literal>includes:</literal>
1077
<replaceable>filename list</replaceable>
1080
<para>A list of header files to be included in any
1081
compilations via C. This field applies to both header
1082
files that are already installed on the system and to
1083
those coming with the package to be installed. These files
1084
typically contain function prototypes for foreign imports
1085
used by the package.</para>
1091
<literal>install-includes:</literal>
1092
<replaceable>filename list</replaceable>
1095
<para>A list of header files from this package to be
1097
<literal>$libdir/includes</literal> when the package
1098
is installed. Files listed in
1099
<literal>install-includes:</literal> should be found in
1100
relative to the top of the source tree or relative to one of the
1101
directories listed in <literal>include-dirs</literal>.</para>
1103
<para><literal>install-includes</literal> is typically
1104
used to name header files that contain prototypes for
1105
foreign imports used in Haskell code in this package,
1106
for which the C implementations are also provided with
1107
the package. Note that to include them when compiling
1108
the package itself, they need to be listed in the
1109
<literal>includes:</literal> field as well.</para>
1115
<literal>include-dirs:</literal>
1116
<replaceable>directory list</replaceable>
1119
<para>A list of directories to search for header files,
1120
when preprocessing with <command>c2hs</command>,
1121
<command>hsc2hs</command>, <command>ffihugs</command>,
1122
<command>cpphs</command> or the C preprocessor,
1123
and also when compiling via C.</para>
1129
<literal>c-sources:</literal>
1130
<replaceable>filename list</replaceable>
1133
<para>A list of C source files to be compiled
1134
and linked with the Haskell files.</para>
1136
<para>If you use this field, you should also name the
1137
C files in <literal>CFILES</literal> pragmas in the
1138
Haskell source files that use them, e.g.:
1139
<screen>{-# CFILES dir/file1.c dir/file2.c #-}</screen>
1140
These are ignored by the compilers, but needed by Hugs.</para>
1146
<literal>extra-libraries:</literal>
1147
<replaceable>token list</replaceable>
1150
<para>A list of extra libraries to link with.</para>
1156
<literal>extra-lib-dirs:</literal>
1157
<replaceable>directory list</replaceable>
1160
<para>A list of directories to search for libraries.</para>
1166
<literal>cc-options:</literal>
1167
<replaceable>token list</replaceable>
1170
<para>Command-line arguments to be passed to the C compiler.
1171
Since the arguments are compiler-dependent, this field
1172
is more useful with the setup described in
1173
<xref linkend="system-dependent"/>.</para>
1179
<literal>ld-options:</literal>
1180
<replaceable>token list</replaceable>
1183
<para>Command-line arguments to be passed to the linker.
1184
Since the arguments are compiler-dependent, this field
1185
is more useful with the setup described in
1186
<xref linkend="system-dependent"/>.</para>
1192
<literal>pkgconfig-depends:</literal>
1193
<replaceable>package list</replaceable>
1196
<para>A list of &PkgConfig; packages, needed to build this
1197
package. They can be annotated with versions,
1198
e.g. <literal>gtk+-2.0 >= 2.10, cairo >= 1.0</literal>.
1199
If no version constraint is specified, any version is
1200
assumed to be acceptable. Cabal uses
1201
<literal>pkg-config</literal> to find if the packages are
1202
available on the system and to find the extra compilation and
1203
linker options needed to use the packages.
1205
<para> If you need to bind to a C library that supports
1206
<literal>pkg-config</literal> (use
1207
<literal>pkg-config --list-all</literal> to find out if it is
1208
supported) then it is much preferable to use this field rather
1209
than hard code options into the other fields.
1216
<literal>frameworks:</literal>
1217
<replaceable>token list</replaceable>
1220
<para>On Darwin/MacOS X, a list of frameworks to link to.
1221
See Apple's developer documentation for more details
1222
on frameworks. This entry is ignored on all other
1229
<sect3 id="configurations">
1230
<title>Configurations</title>
1231
<para>Library and executable sections may include conditional
1232
blocks, which test for various system parameters and
1233
configuration flags. The flags mechanism is rather generic,
1234
but most of the time a flag represents certain feature, that
1235
can be switched on or off by the package user.</para>
1236
<para>Here is an example package description file using
1237
configurations:</para>
1238
<example id="package-with-configurations-example">
1239
<title>A package containing a library and executable programs</title>
1241
<programlisting>Name: Test1
1243
Cabal-Version: >= 1.2
1246
Synopsis: Test package to test configurations
1250
Description: Enable debug support
1254
Description: Include API for web frontend.
1255
-- Cabal checks if the configuration is possible, first
1256
-- with this flag set to True and if not it tries with False
1260
Exposed-Modules: Testing.Test1
1264
GHC-Options: -DDEBUG
1266
CC-Options: "-DDEBUG"
1268
CC-Options: "-DNDEBUG"
1270
if flag(webfrontend)
1271
Build-Depends: cgi > 0.42
1272
Other-Modules: Testing.WebStuff
1276
Other-Modules: Testing.Test1
1280
CC-Options: "-DDEBUG"
1281
GHC-Options: -DDEBUG
1285
<title>Layout</title>
1286
<para>Flags, conditionals, library and executable sections use layout to
1287
indicate structure. This is very similar to the Haskell layout rule.
1288
Entries in a section have to all be indented to the same level which must
1289
be more than the section header. Tabs are not allowed to be used for
1292
<para>As an alternative to using layout you can also use explicit braces
1293
<literal>{}</literal>. In this case the indentation of entries in a
1294
section does not matter, though different fields within a block must be
1295
on different lines. Here is a bit of the above example again, using
1297
<example id="configurations-with-braces-example">
1298
<title>Using explicit braces rather than indentation for layout</title>
1300
<programlisting>Name: Test1
1302
Cabal-Version: >= 1.2
1305
Synopsis: Test package to test configurations
1309
Description: Enable debug support
1315
Exposed-Modules: Testing.Test1
1318
GHC-Options: -DDEBUG
1320
CC-Options: "-DDEBUG"
1322
CC-Options: "-DNDEBUG"
1330
<title>Configuration Flags</title>
1331
<para>A flag section takes the flag name as an argument and
1332
may contain the following fields.</para>
1336
<literal>description:</literal>
1337
<replaceable>freeform</replaceable>
1340
<para>The description of this flag.</para>
1345
<literal>default:</literal>
1346
<replaceable>boolean</replaceable>
1347
(default: <literal>True</literal>)
1350
<para>The default value of this flag.</para>
1351
<para>Note that this value may be overridden in several
1352
ways (see <xref linkend="flag-control"/>). The
1353
rationale for having flags default to True is that users
1354
usually want new features as soon as they are available.
1355
Flags representing features that are not (yet)
1356
recommended for most users (such as experimental
1357
features or debugging support) should therefore
1358
explicitly override the default to False.</para>
1363
<literal>manual:</literal>
1364
<replaceable>boolean</replaceable>
1365
(default: <literal>False</literal>)
1368
<para>By default, Cabal will first try to satisfy
1369
dependencies with the default flag value and then,
1370
if that is not possible, with the negated value.
1371
However, if the flag is manual, then the default
1372
value (which can be overridden by commandline flags)
1373
will be used.</para>
1378
<sect4 id="conditionals">
1379
<title>Conditional Blocks</title>
1380
<para>Conditional blocks may appear anywhere inside a
1381
library or executable section. They have to follow rather
1382
strict formatting rules.</para>
1383
<para>Conditional blocks must always be of the shape
1385
<literal>if </literal><replaceable>condition</replaceable>
1386
<replaceable>property-descriptions-or-conditionals*</replaceable>
1389
<literal>if </literal><replaceable>condition</replaceable>
1390
<replaceable>property-descriptions-or-conditionals*</replaceable>
1391
<literal>else</literal>
1392
<replaceable>property-descriptions-or-conditionals*</replaceable>
1393
</literallayout></para>
1395
<para>Note that the <literal>if</literal> and the condition have to
1396
be all on the same line.</para>
1399
<sect4 id="conditions">
1400
<title>Conditions</title>
1401
<para>Conditions can be formed using boolean tests and the
1402
boolean operators <literal>||</literal> (disjunction /
1403
logical "or"), <literal>&&</literal> (conjunction /
1404
logical "and"), or <literal>!</literal> (negation / logical
1405
"not"). The unary <literal>!</literal> takes highest
1406
precedence, <literal>||</literal> takes lowest. Precedence
1407
levels may be overridden through the use of parentheses.
1408
For example, <literal>os(darwin) && !arch(i386) || os(freebsd)</literal>
1409
is equivalent to <literal>(os(darwin) && !(arch(i386))) || os(freebsd)</literal>.
1411
<para>The following tests are currently supported.</para>
1415
<literal>os(</literal>
1416
<replaceable>name</replaceable>
1417
<literal>)</literal>
1420
<para>Tests if the current operating system is
1421
<replaceable>name</replaceable>. The argument is tested
1422
against <literal>System.Info.os</literal> on
1423
the target system. There is unfortunately some disagreement
1424
between Haskell implementations about the standard values of
1425
<literal>System.Info.os</literal>. Cabal canonicalises it so
1426
that in particular <literal>os(windows)</literal> works on all
1427
implementations. If the canonicalised os names match, this test
1428
evaluates to true, otherwise false. The match is
1429
case-insensitive. </para>
1434
<literal>arch(</literal>
1435
<replaceable>name</replaceable>
1436
<literal>)</literal>
1439
<para>Tests if the current architecture is
1440
<replaceable>name</replaceable>. The argument is matched
1441
against <literal>System.Info.arch</literal> on the target system.
1442
If the arch names match, this test evaluates to true,
1443
otherwise false. The match is case-insensitive. </para>
1448
<literal>impl(</literal>
1449
<replaceable>compiler</replaceable>
1450
<literal>)</literal>
1453
<para>Tests for the configured Haskell implementation. An optional
1454
version constraint may be specified (for example
1455
<literal>impl(ghc >= 6.6.1)</literal>). If the
1456
configured implementation is of the right type and matches the
1457
version constraint, then this evaluates to true,
1458
otherwise false. The match is case-insensitive.</para>
1461
<varlistentry> <term>
1462
<literal>flag(</literal>
1463
<replaceable>name</replaceable>
1464
<literal>)</literal>
1467
<para>Evaluates to the current assignment of the flag of
1468
the given name. Flag names are case insensitive.
1469
Testing for flags that have not been introduced with a
1470
flag section is an error.</para>
1475
<literal>true</literal>
1478
<para>Constant value true.</para>
1483
<literal>false</literal>
1486
<para>Constant value false.</para>
1492
<sect4 id="conditional-resolution">
1493
<title>Resolution of Conditions and Flags</title>
1494
<para>If a package descriptions specifies configuration flags
1495
the package user can control these in several ways (see
1496
<xref linkend="flag-control"/>). If the user does not fix the
1497
value of a flag, Cabal will try to find a flag assignment in the
1498
following way.</para>
1501
<para>For each flag specified, it will assign its default
1502
value, evaluate all conditions with this flag assignment,
1503
and check if all dependencies can be satisfied. If this
1504
check succeeded, the package will be configured with those
1505
flag assignments.</para>
1508
<para>If dependencies were missing, the last flag (as by
1509
the order in which the flags were introduced in the
1510
package description) is tried with its alternative value
1511
and so on. This continues until either an assignment is
1512
found where all dependencies can be satisfied, or all
1513
possible flag assignments have been tried.</para>
1517
<para>To put it another way, Cabal does a complete backtracking
1518
search to find a satisfiable package configuration. It is only the
1519
dependencies specified in the <literal>build-depends</literal> field
1520
in conditional blocks that determine if a particular flag assignment
1521
is satisfiable (<literal>build-tools</literal> are not considered).
1522
The order of the declaration and the default value of the flags
1523
determines the search order. Flags overridden on the command line fix
1524
the assignment of that flag, so no backtracking will be tried for
1527
<para>If no suitable flag assignment could be found, the
1528
configuration phase will fail and a list of missing
1529
dependencies will be printed. Note that this resolution
1530
process is exponential in the worst case (i.e., in the case
1531
where dependencies cannot be satisfied). There are some
1532
optimizations applied internally, but the overall complexity
1533
remains unchanged.</para>
1535
<sect4 id="prop-combine">
1536
<title>Meaning of field values when using conditionals</title>
1537
<para>During the configuration phase, a flag assignment is
1538
chosen, all conditionals are evaluated, and the package description
1539
is combined into a flat package descriptions. If the same field
1540
both inside a conditional and outside then they are combined using
1541
the following rules.</para>
1544
<para>Boolean fields are combined using conjunction
1545
(logical "and").</para>
1548
<para>List fields are combined by appending the inner
1549
items to the outer items, for example
1550
<programlisting>Extensions: CPP
1551
if impl(ghc) || impl(hugs)
1552
Extensions: MultiParamTypeClasses
1554
when compiled using Hugs or GHC will be combined to
1555
<programlisting>Extensions: CPP, MultiParamTypeClasses</programlisting>
1557
<para>Similarly, if two conditional sections appear at the
1558
same nesting level, properties specified in the latter
1559
will come after properties specified in the former.</para>
1562
<para>All other fields must not be specified in ambiguous ways. For example
1563
<programlisting>Main-is: Main.hs
1564
if flag(useothermain)
1565
Main-is: OtherMain.hs
1567
will lead to an error. Instead use
1568
<programlisting>if flag(useothermain)
1569
Main-is: OtherMain.hs
1572
</programlisting></para>
1578
<sect3 id="source-repos">
1579
<title>Source Repositories</title>
1581
It is often useful to be able to specify a source revision control
1582
repository for a package. Cabal lets you specifying this information
1583
in a relatively structured form which enables other tools to
1584
interpret and make effective use of the information. For example the
1585
information should be sufficient for an automatic tool to checkout
1589
Cabal supports specifying different information for various common
1590
source control systems. Obviously not all automated tools will
1591
support all source control systems.
1594
Cabal supports specifying repositories for different use cases. By
1595
declaring which case we mean automated tools can be more useful.
1596
There are currently two kinds defined:
1600
The <literal>head</literal> kind refers to the
1601
latest development branch of the package. This may be used for
1602
example to track activity of a project or as an indication to
1603
outside developers what sources to get for making new
1609
The <literal>this</literal> kind refers to the
1610
branch and tag of a repository that contains the sources for this
1611
version or release of a package. For most source control systems
1612
this involves specifying a tag, id or hash of some form and
1613
perhaps a branch. The purpose is to be able to reconstruct the
1614
sources corresponding to a particular package version. This might
1615
be used to indicate what sources to get if someone needs to fix a
1616
bug in an older branch that is no longer an active head branch.
1622
You can specify one kind or the other or both. As an example here are
1623
the repositories for the Cabal library. Note that the
1624
<literal>this</literal> kind of repo specifies a tag.
1626
source-repository head
1628
location: http://darcs.haskell.org/cabal/
1630
source-repository this
1632
location: http://darcs.haskell.org/cabal-branches/cabal-1.6/
1637
The exact fields are as follows:
1642
<literal>type:</literal>
1643
<replaceable>token</replaceable>
1647
The name of the source control system used for this repository.
1648
The currently recognised types are:
1650
<listitem><para>darcs</para></listitem>
1651
<listitem><para>git</para></listitem>
1652
<listitem><para>svn</para></listitem>
1653
<listitem><para>cvs</para></listitem>
1654
<listitem><para>mercurial (or alias hg)</para></listitem>
1655
<listitem><para>bazaar (or alias bzr)</para></listitem>
1656
<listitem><para>arch</para></listitem>
1657
<listitem><para>monotone</para></listitem>
1661
This field is required.
1667
<literal>location:</literal>
1668
<replaceable>URL</replaceable>
1672
The location of the repository. The exact form of this field
1673
depends on the repository type. For example:
1676
<para>for darcs: <literal>http://code.haskell.org/foo/</literal></para>
1679
<para>for git: <literal>git://github.com/foo/bar.git</literal></para>
1682
<para>for CVS: <literal>anoncvs@cvs.foo.org:/cvs</literal></para>
1687
This field is required.
1693
<literal>module:</literal>
1694
<replaceable>token</replaceable>
1698
CVS requires a named module, as each CVS server can host multiple
1702
This field is required for the CVS repo type and should not be
1709
<literal>branch:</literal>
1710
<replaceable>token</replaceable>
1714
Many source control systems support the notion of a branch,
1715
as a distinct concept from having repositories in separate
1716
locations. For example CVS, SVN and git use branches while for
1717
darcs uses different locations for different branches. If you
1718
need to specify a branch to identify a your repository
1719
then specify it in this field.
1722
This field is optional.
1728
<literal>tag:</literal>
1729
<replaceable>token</replaceable>
1733
A tag identifies a particular state of a source repository. The
1734
tag can be used with a <literal>this</literal> repo kind to
1735
identify the state of a repo corresponding to a particular
1736
package version or release. The exact form of the tag depends on
1737
the repository type.
1740
This field is required for the <literal>this</literal> repo kind.
1746
<literal>subdir:</literal>
1747
<replaceable>directory</replaceable>
1751
Some projects put the sources for multiple packages under a
1752
single source repository. This field lets you specify the
1753
relative path from the root of the repository to the top
1754
directory for the package, ie the directory containing the
1755
package's <literal>.cabal</literal> file.
1758
This field is optional. It default to empty which corresponds to
1759
the root directory of the repository.
1767
<sect2 id="paths-module">
1768
<title>Accessing data files from package code</title>
1769
<para>The placement on the target system of files listed in the
1770
<literal>data-files</literal> field varies between systems, and in
1771
some cases one can even move packages around after installation
1772
(see <xref linkend="prefix-independence"/>). To enable packages
1773
to find these files in a portable way, Cabal generates a module
1774
called <literal>Paths_</literal><replaceable>pkgname</replaceable>
1775
(with any hyphens in <replaceable>pkgname</replaceable> replaced
1776
by underscores) during building, so that it may be imported by
1777
modules of the package. This module defines a function
1778
<programlisting>getDataFileName :: FilePath -> IO FilePath</programlisting>
1779
If the argument is a filename listed in the
1780
<literal>data-files</literal> field, the result is the name
1781
of the corresponding file on the system on which the program
1784
<para>If you decide to import the
1785
<literal>Paths_</literal><replaceable>pkgname</replaceable> module then
1786
it <emphasis>must</emphasis> be listed in the
1787
<literal>other-modules</literal> field just like any other module in
1790
<para>The <literal>Paths_</literal><replaceable>pkgname</replaceable>
1791
module is not platform independent so it does not get included in the
1792
source tarballs generated by <command>sdist</command>.
1797
<sect2 id="system-dependent">
1798
<title>System-dependent parameters</title>
1800
<para>For some packages, especially those interfacing with C
1801
libraries, implementation details and the build procedure depend
1802
on the build environment. A variant of the simple build
1803
infrastructure (the <literal>build-type</literal>
1804
<literal>Configure</literal>) handles many such situations using
1805
a slightly longer <filename>Setup.hs</filename>:</para>
1807
import Distribution.Simple
1808
main = defaultMainWithHooks autoconfUserHooks</programlisting>
1810
<para>Most packages, however, would probably do better with
1811
configurations (see <xref linkend="configurations"/>).</para>
1813
<para>This program differs from <literal>defaultMain</literal>
1817
<para>The package root directory must contain a shell script called
1818
<filename>configure</filename>. The configure step will run the
1819
script. This <filename>configure</filename> script may
1820
be produced by &Autoconf; or may be hand-written. The
1821
<filename>configure</filename> script typically
1822
discovers information about the system and records it for
1823
later steps, e.g. by generating system-dependent header files
1824
for inclusion in C source files and preprocessed Haskell
1825
source files. (Clearly this won't work for Windows without
1826
MSYS or Cygwin: other ideas are needed.)</para>
1830
<para>If the package root directory contains a file called
1831
<replaceable>package</replaceable><literal>.buildinfo</literal>
1832
after the configuration step, subsequent steps will read it
1833
to obtain additional settings for build information fields
1834
(see <xref linkend="buildinfo"/>), to be merged with the
1835
ones given in the <literal>.cabal</literal> file.
1836
In particular, this file may be generated by the
1837
<filename>configure</filename> script mentioned above,
1838
allowing these settings to vary depending on the build
1841
<para>The build information file should have the following
1844
<replaceable>buildinfo</replaceable>
1846
executable: <replaceable>name</replaceable>
1847
<replaceable>buildinfo</replaceable>
1849
executable: <replaceable>name</replaceable>
1850
<replaceable>buildinfo</replaceable>
1852
...</programlisting>
1853
<para>where each <replaceable>buildinfo</replaceable> consists
1854
of settings of fields listed in <xref linkend="buildinfo"/>.
1855
The first one (if present) relates to the library, while each
1856
of the others relate to the named executable. (The names
1857
must match the package description, but you don't have to
1858
have entries for all of them.)</para>
1863
<para>Neither of these files is required. If they are absent, this
1864
setup script is equivalent to <literal>defaultMain</literal>.</para>
1866
<example id="autoconf-example">
1867
<title>Using autoconf</title>
1869
<para>(This example is for people familiar with the &Autoconf;
1872
<para>In the X11 package, the file <filename>configure.ac</filename>
1875
AC_INIT([Haskell X11 package], [1.1], [libraries@haskell.org], [X11])
1877
# Safety check: Ensure that we are in the correct source directory.
1878
AC_CONFIG_SRCDIR([X11.cabal])
1880
# Header file to place defines in
1881
AC_CONFIG_HEADERS([include/HsX11Config.h])
1883
# Check for X11 include paths and libraries
1885
AC_TRY_CPP([#include <X11/Xlib.h>],,[no_x=yes])
1887
# Build the package if we found X11 stuff
1888
if test "$no_x" = yes
1889
then BUILD_PACKAGE_BOOL=False
1890
else BUILD_PACKAGE_BOOL=True
1892
AC_SUBST([BUILD_PACKAGE_BOOL])
1894
AC_CONFIG_FILES([X11.buildinfo])
1895
AC_OUTPUT</programlisting>
1897
<para>Then the setup script will run the
1898
<literal>configure</literal> script, which checks for the
1899
presence of the X11 libraries and substitutes for variables
1900
in the file <filename>X11.buildinfo.in</filename>:</para>
1902
buildable: @BUILD_PACKAGE_BOOL@
1903
cc-options: @X_CFLAGS@
1904
ld-options: @X_LIBS@</programlisting>
1906
<para>This generates a file <filename>X11.buildinfo</filename>
1907
supplying the parameters needed by later stages:</para>
1910
cc-options: -I/usr/X11R6/include
1911
ld-options: -L/usr/X11R6/lib</programlisting>
1913
<para>The <filename>configure</filename> script also generates
1914
a header file <filename>include/HsX11Config.h</filename>
1915
containing C preprocessor defines recording the results of
1916
various tests. This file may be included by C source files
1917
and preprocessed Haskell source files in the package.</para>
1921
<para>Packages using these features will also need to list
1922
additional files such as <filename>configure</filename>,
1923
templates for <literal>.buildinfo</literal> files, files named
1924
only in <literal>.buildinfo</literal> files, header files and
1925
so on in the <literal>extra-source-files</literal> field,
1926
to ensure that they are included in source distributions.
1927
They should also list files and directories generated by
1928
<command>configure</command> in the
1929
<literal>extra-tmp-files</literal> field to ensure that they
1930
are removed by <command>setup clean</command>.</para>
1935
<title>Conditional compilation</title>
1937
<para>Sometimes you want to write code that works with more than
1938
one version of a dependency. You can specify a range of
1939
versions for the depenency in
1940
the <literal>build-depends</literal>, but how do you then write
1941
the code that can use different versions of the API?</para>
1943
<para>Haskell lets you preprocess your code using the C
1944
preprocessor (either the real C preprocessor, or
1945
<literal>cpphs</literal>). To enable this,
1946
add <literal>extensions: CPP</literal> to your package
1947
description. When using CPP, Cabal provides some pre-defined
1948
macros to let you test the version of dependent packages; for
1949
example, suppose your package works with either version 3 or
1950
version 4 of the <literal>base</literal> package, you could
1951
select the available version in your Haskell modules like
1954
#if MIN_VERSION_base(4,0,0)
1955
... code that works with base-4 ...
1957
... code that works with base-3 ...
1960
<para>In general, Cabal supplies a
1961
macro <literal>MIN_VERSION_<replaceable>package</replaceable>(A,B,C)</literal>
1962
for each package depended on via <literal>build-depends</literal>.
1963
This macro is true if the actual version of the package in use is
1964
greater than or equal to <literal>A.B.C</literal> (using the
1965
conventional ordering on version numbers, which is lexicographic on
1966
the sequence, but numeric on each component, so for example 1.2.0 is
1967
greater than 1.0.3).</para>
1969
<para>Cabal places the definitions of these macros into an
1970
automatically-generated header file, which is included when
1971
preprocessing Haskell source code by passing options to the C
1972
preprocessor.</para>
1975
<sect2 id="complex-packages">
1976
<title>More complex packages</title>
1978
<para>For packages that don't fit the simple schemes described above,
1979
you have a few options:</para>
1983
<para>You can customize the simple build infrastructure
1984
using <firstterm>hooks</firstterm>. These allow you to
1985
perform additional actions before and after each command is
1986
run, and also to specify additional preprocessors. See
1987
<literal>UserHooks</literal> in &Simple; for the details,
1988
but note that this interface is experimental, and likely to
1989
change in future releases.</para>
1993
<para>You could delegate all the work to <command>make</command>,
1994
though this is unlikely to be very portable.
1995
Cabal supports this with the <literal>build-type</literal>
1996
<literal>Make</literal> and a trivial setup library &Make;,
1997
which simply parses the command line arguments and invokes
1998
<command>make</command>. Here <filename>Setup.hs</filename>
2001
import Distribution.Make
2002
main = defaultMain</programlisting>
2004
<para>The root directory of the package should contain
2005
a <filename>configure</filename> script, and, after
2006
that has run, a <filename>Makefile</filename> with a
2007
default target that builds the package, plus targets
2008
<literal>install</literal>, <literal>register</literal>,
2009
<literal>unregister</literal>, <literal>clean</literal>,
2010
<literal>dist</literal> and <literal>docs</literal>.
2011
Some options to commands are passed through as follows:</para>
2015
<para>The <option>--with-hc-pkg</option>,
2016
<option>--prefix</option>, <option>--bindir</option>,
2017
<option>--libdir</option>, <option>--datadir</option>
2018
and <option>--libexecdir</option> options to the
2019
<literal>configure</literal> command are passed on to
2020
the <filename>configure</filename> script.
2021
In addition the value of the <option>--with-compiler</option>
2022
option is passed in a <option>--with-hc</option> option and
2023
all options specified with <option>--configure-option</option>=
2024
are passed on.</para>
2028
<para>the <literal>--destdir</literal> option to the
2029
<literal>copy</literal> command becomes a setting of a
2030
<literal>destdir</literal> variable on the invocation of
2031
<literal>make copy</literal>. The supplied
2032
<literal>Makefile</literal> should provide a
2033
<literal>copy</literal> target, which will probably
2037
$(MAKE) install prefix=$(destdir)/$(prefix) \
2038
bindir=$(destdir)/$(bindir) \
2039
libdir=$(destdir)/$(libdir) \
2040
datadir=$(destdir)/$(datadir) \
2041
libexecdir=$(destdir)/$(libexecdir)</programlisting>
2049
<para>You can write your own setup script conforming to the
2050
interface of <xref linkend="builders"/>, possibly using
2051
the Cabal library for part of the work. One option is to
2052
copy the source of <literal>Distribution.Simple</literal>,
2053
and alter it for your needs. Good luck.</para>
2059
<sect1 id="builders">
2060
<title>Building and installing a package</title>
2061
<para>After you've unpacked a Cabal package, you can build it
2062
by moving into the root directory of the package and using the
2063
<filename>Setup.hs</filename> or <filename>Setup.lhs</filename>
2064
script there:</para>
2066
<command>runhaskell Setup.hs</command>
2067
<arg><replaceable>command</replaceable></arg>
2068
<arg rep="repeat" choice="opt"><replaceable>option</replaceable></arg>
2070
<para>where <replaceable>runhaskell</replaceable> might be
2071
<command>runhugs</command>, <command>runghc</command> or
2072
<command>runnhc</command>. The <replaceable>command</replaceable>
2073
argument selects a particular step in the build/install process.
2074
You can also get a summary of the command syntax with</para>
2076
<command>runhaskell Setup.hs <option>--help</option></command>
2079
<example id="system-install-example">
2080
<title>Building and installing a system package</title>
2082
runhaskell Setup.hs configure --ghc
2083
runhaskell Setup.hs build
2084
runhaskell Setup.hs install</screen>
2085
<para>The first line readies the system to build the tool using GHC;
2086
for example, it checks that GHC exists on the system. The second
2087
line performs the actual building, while the last both copies
2088
the build results to some permanent place and registers the
2089
package with GHC.</para>
2092
<example id="user-install-example">
2093
<title>Building and installing a user package</title>
2095
runhaskell Setup.hs configure --user
2096
runhaskell Setup.hs build
2097
runhaskell Setup.hs install</screen>
2098
<para>The package is installed under the user's home directory
2099
and is registered in the user's package database
2100
(<option>--user</option>).</para>
2103
<example id="binary-package-example">
2104
<title>Creating a binary package</title>
2105
<para>When creating binary packages (e.g. for RedHat or
2106
Debian) one needs to create a tarball that can be sent to
2107
another system for unpacking in the root directory:</para>
2109
runhaskell Setup.hs configure --prefix=/usr
2110
runhaskell Setup.hs build
2111
runhaskell Setup.hs copy --destdir=/tmp/mypkg
2112
tar -czf mypkg.tar.gz /tmp/mypkg/</screen>
2114
<para>If the package contains a library, you need two additional
2117
runhaskell Setup.hs register --gen-script
2118
runhaskell Setup.hs unregister --gen-script</screen>
2119
<para>This creates shell scripts <filename>register.sh</filename>
2120
and <filename>unregister.sh</filename>, which must also be sent
2121
to the target system. After unpacking there, the package must be
2122
registered by running the <filename>register.sh</filename> script.
2123
The <filename>unregister.sh</filename> script would be used
2124
in the uninstall procedure of the package. Similar steps may
2125
be used for creating binary packages for Windows.</para>
2128
<para>The following options are understood by all commands:</para>
2132
<option>--help</option>, <option>-h</option> or
2136
<para>List the available options for the command.</para>
2142
<option>--verbose</option>=<replaceable>n</replaceable> or
2143
<option>-v</option><replaceable>n</replaceable>
2146
<para>Set the verbosity level (0-3). The normal level is 1;
2147
a missing <replaceable>n</replaceable> defaults to 2.</para>
2152
<para>The various commands and the additional options they support
2153
are described below. In the simple build infrastructure, any
2154
other options will be reported as errors.</para>
2156
<sect2 id="setup-configure">
2157
<title>setup configure</title>
2158
<para>Prepare to build the package. Typically, this step checks
2159
that the target platform is capable of building the package,
2160
and discovers platform-specific features that are needed during
2163
<para>The user may also adjust the behaviour of later stages using
2164
the options listed in the following subsections. In the simple
2165
build infrastructure, the values supplied via these options are
2166
recorded in a private file read by later stages.</para>
2168
<para>If a user-supplied <filename>configure</filename>
2169
script is run (see <xref linkend="system-dependent"/>
2170
or <xref linkend="complex-packages"/>), it is passed the
2171
<option>--with-hc-pkg</option>,
2172
<option>--prefix</option>, <option>--bindir</option>,
2173
<option>--libdir</option>, <option>--datadir</option> and
2174
<option>--libexecdir</option> options.
2175
In addition the value of the <option>--with-compiler</option>
2176
option is passed in a <option>--with-hc</option> option and
2177
all options specified with <option>--configure-option</option>=
2178
are passed on.</para>
2180
<sect3 id="setup-configure-programs">
2181
<title>Programs used for building</title>
2183
<para>The following options govern the programs used to process
2184
the source files of a package:</para>
2188
<term><option>--ghc</option> or <option>-g</option></term>
2189
<term><option>--nhc</option></term>
2190
<term><option>--jhc</option></term>
2191
<term><option>--hugs</option></term>
2193
<para>Specify which Haskell implementation to use to build
2194
the package. At most one of these flags may be given.
2195
If none is given, the implementation under which the setup
2196
script was compiled or interpreted is used.</para>
2201
<term><option>--with-compiler</option>=<replaceable>path</replaceable>
2202
or <option>-w</option><replaceable>path</replaceable></term>
2204
<para>Specify the path to a particular compiler. If given,
2205
this must match the implementation selected above.
2206
The default is to search for the usual name of the
2207
selected implementation.</para>
2208
<para>This flag also sets the default value of the
2209
<option>--with-hc-pkg</option> option to the package tool
2211
Check the output of <literal>setup configure -v</literal>
2212
to ensure that it finds the right package tool (or use
2213
<option>--with-hc-pkg</option> explicitly).</para>
2218
<term><option>--with-hc-pkg</option>=<replaceable>path</replaceable></term>
2220
<para>Specify the path to the package tool, e.g.
2221
<command>ghc-pkg</command>.
2222
The package tool must be compatible with the compiler
2223
specified by <option>--with-compiler</option>.
2224
If this option is omitted, the default value is determined
2225
from the compiler selected.</para>
2230
<term><option>--with-<replaceable>prog</replaceable></option>=<replaceable>path</replaceable></term>
2232
<para>Specify the path to the program <replaceable>prog</replaceable>.
2233
Any program known to Cabal can be used in place of
2234
<replaceable>prog</replaceable>. It can either be a fully
2235
path or the name of a program that can be found on the program
2236
search path. For example: <option>--with-ghc=ghc-6.6.1</option>
2237
or <option>--with-cpphs=/usr/local/bin/cpphs</option>.</para>
2242
<term><option>--<replaceable>prog</replaceable>-options</option>=<replaceable>options</replaceable></term>
2244
<para>Specify additional options to the program <replaceable>prog</replaceable>.
2245
Any program known to Cabal can be used in place of
2246
<replaceable>prog</replaceable>. For example:
2247
<option>--alex-options="--template=mytemplatedir/"</option>.</para>
2248
<para>The <replaceable>options</replaceable> is split into program options
2249
based on spaces. Any options containing embeded spaced need to
2250
be quoted, for example
2251
<literal>--foo-options='--bar="C:\Program File\Bar"'</literal>. As an
2252
alternative that takes only one option at a time but avoids the
2254
<option>--<replaceable>prog</replaceable>-option</option> instead.
2260
<term><option>--<replaceable>prog</replaceable>-option</option>=<replaceable>option</replaceable></term>
2262
<para>Specify a single additional option to the program
2263
<replaceable>prog</replaceable>.</para>
2264
<para>For passing an option that contain embeded spaces, such as a file
2265
name with embeded spaces, using this rather than
2266
<option>--<replaceable>prog</replaceable>-options</option> means you
2267
do not need an additional level of quoting. Of course if
2268
you are using a command shell you may still need to quote, for
2269
example <literal>--foo-options="--bar=C:\Program File\Bar"</literal>.
2274
<para>All of the options passed with either
2275
<option>--<replaceable>prog</replaceable>-options</option> or
2276
<option>--<replaceable>prog</replaceable>-option</option> are passed
2277
in the order they were specified on the configure command line.
2282
<sect3 id="setup-configure-paths">
2283
<title>Installation paths</title>
2285
<para>The following options govern the location of installed files
2286
from a package:</para>
2290
<term><option>--prefix</option>=<replaceable>dir</replaceable></term>
2292
<para>The root of the installation. For example for a global
2293
install you might use
2294
<filename>/usr/local</filename> on a Unix system, or
2295
<filename>C:\Program Files</filename> on a Windows system.
2296
The other installation paths are usually subdirectories of
2297
<replaceable>prefix</replaceable>, but they don't have
2299
<para>In the simple build system, <replaceable>dir</replaceable>
2300
may contain the following path variables:
2301
<replaceable>$pkgid</replaceable>,
2302
<replaceable>$pkg</replaceable>,
2303
<replaceable>$version</replaceable>,
2304
<replaceable>$compiler</replaceable>,
2305
<replaceable>$os</replaceable>,
2306
<replaceable>$arch</replaceable>
2312
<term><option>--bindir</option>=<replaceable>dir</replaceable></term>
2314
<para>Executables that the user might invoke are installed here.</para>
2315
<para>In the simple build system, <replaceable>dir</replaceable>
2316
may contain the following path variables:
2317
<replaceable>$prefix</replaceable>,
2318
<replaceable>$pkgid</replaceable>,
2319
<replaceable>$pkg</replaceable>,
2320
<replaceable>$version</replaceable>,
2321
<replaceable>$compiler</replaceable>,
2322
<replaceable>$os</replaceable>,
2323
<replaceable>$arch</replaceable>
2329
<term><option>--libdir</option>=<replaceable>dir</replaceable></term>
2331
<para>Object-code libraries are installed here.</para>
2332
<para>In the simple build system, <replaceable>dir</replaceable>
2333
may contain the following path variables:
2334
<replaceable>$prefix</replaceable>,
2335
<replaceable>$bindir</replaceable>,
2336
<replaceable>$pkgid</replaceable>,
2337
<replaceable>$pkg</replaceable>,
2338
<replaceable>$version</replaceable>,
2339
<replaceable>$compiler</replaceable>,
2340
<replaceable>$os</replaceable>,
2341
<replaceable>$arch</replaceable>
2347
<term><option>--libexecdir</option>=<replaceable>dir</replaceable></term>
2349
<para>Executables that are not expected to be invoked
2350
directly by the user are installed here.</para>
2351
<para>In the simple build system, <replaceable>dir</replaceable>
2352
may contain the following path variables:
2353
<replaceable>$prefix</replaceable>,
2354
<replaceable>$bindir</replaceable>,
2355
<replaceable>$libdir</replaceable>,
2356
<replaceable>$libsubdir</replaceable>,
2357
<replaceable>$pkgid</replaceable>,
2358
<replaceable>$pkg</replaceable>,
2359
<replaceable>$version</replaceable>,
2360
<replaceable>$compiler</replaceable>,
2361
<replaceable>$os</replaceable>,
2362
<replaceable>$arch</replaceable>
2368
<term><option>--datadir</option>=<replaceable>dir</replaceable></term>
2370
<para>Architecture-independent data files are installed
2372
<para>In the simple build system, <replaceable>dir</replaceable>
2373
may contain the following path variables:
2374
<replaceable>$prefix</replaceable>,
2375
<replaceable>$bindir</replaceable>,
2376
<replaceable>$libdir</replaceable>,
2377
<replaceable>$libsubdir</replaceable>,
2378
<replaceable>$pkgid</replaceable>,
2379
<replaceable>$pkg</replaceable>,
2380
<replaceable>$version</replaceable>,
2381
<replaceable>$compiler</replaceable>,
2382
<replaceable>$os</replaceable>,
2383
<replaceable>$arch</replaceable>
2389
<para>In addition the simple build system supports the following
2390
installation path options:</para>
2394
<term><option>--libsubdir</option>=<replaceable>dir</replaceable></term>
2396
<para>A subdirectory of <replaceable>libdir</replaceable>
2397
in which libraries are actually installed. For example,
2398
in the simple build system on Unix, the default
2399
<replaceable>libdir</replaceable> is
2400
<filename>/usr/local/lib</filename>, and
2401
<replaceable>libsubdir</replaceable> contains the package
2402
identifier and compiler,
2403
e.g. <literal>mypkg-0.2/ghc-6.4</literal>, so libraries
2404
would be installed in
2405
<filename>/usr/local/lib/mypkg-0.2/ghc-6.4</filename>.
2407
<para><replaceable>dir</replaceable> may contain the following path
2409
<replaceable>$pkgid</replaceable>,
2410
<replaceable>$pkg</replaceable>,
2411
<replaceable>$version</replaceable>,
2412
<replaceable>$compiler</replaceable>,
2413
<replaceable>$os</replaceable>,
2414
<replaceable>$arch</replaceable>
2420
<term><option>--datasubdir</option>=<replaceable>dir</replaceable></term>
2422
<para>A subdirectory of <replaceable>datadir</replaceable>
2423
in which data files are actually installed.
2425
<para><replaceable>dir</replaceable> may contain the following path
2427
<replaceable>$pkgid</replaceable>,
2428
<replaceable>$pkg</replaceable>,
2429
<replaceable>$version</replaceable>,
2430
<replaceable>$compiler</replaceable>,
2431
<replaceable>$os</replaceable>,
2432
<replaceable>$arch</replaceable>
2438
<term><option>--docdir</option>=<replaceable>dir</replaceable></term>
2440
<para>Documentation files are installed relative to this directory.
2442
<para><replaceable>dir</replaceable> may contain the following path
2444
<replaceable>$prefix</replaceable>,
2445
<replaceable>$bindir</replaceable>,
2446
<replaceable>$libdir</replaceable>,
2447
<replaceable>$libsubdir</replaceable>,
2448
<replaceable>$datadir</replaceable>,
2449
<replaceable>$datasubdir</replaceable>,
2450
<replaceable>$pkgid</replaceable>,
2451
<replaceable>$pkg</replaceable>,
2452
<replaceable>$version</replaceable>,
2453
<replaceable>$compiler</replaceable>,
2454
<replaceable>$os</replaceable>,
2455
<replaceable>$arch</replaceable>
2461
<term><option>--htmldir</option>=<replaceable>dir</replaceable></term>
2463
<para>HTML documentation files are installed relative to this directory.
2465
<para><replaceable>dir</replaceable> may contain the following path
2467
<replaceable>$prefix</replaceable>,
2468
<replaceable>$bindir</replaceable>,
2469
<replaceable>$libdir</replaceable>,
2470
<replaceable>$libsubdir</replaceable>,
2471
<replaceable>$datadir</replaceable>,
2472
<replaceable>$datasubdir</replaceable>,
2473
<replaceable>$docdir</replaceable>,
2474
<replaceable>$pkgid</replaceable>,
2475
<replaceable>$pkg</replaceable>,
2476
<replaceable>$version</replaceable>,
2477
<replaceable>$compiler</replaceable>,
2478
<replaceable>$os</replaceable>,
2479
<replaceable>$arch</replaceable>
2485
<term><option>--program-prefix</option>=<replaceable>prefix</replaceable></term>
2487
<para>Prepend <replaceable>prefix</replaceable> to installed program names.
2489
<para><replaceable>prefix</replaceable> may contain the following path
2491
<replaceable>$pkgid</replaceable>,
2492
<replaceable>$pkg</replaceable>,
2493
<replaceable>$version</replaceable>,
2494
<replaceable>$compiler</replaceable>,
2495
<replaceable>$os</replaceable>,
2496
<replaceable>$arch</replaceable>
2502
<term><option>--program-suffix</option>=<replaceable>suffix</replaceable></term>
2504
<para>Append <replaceable>suffix</replaceable> to installed program names. The
2505
most obvious use for this is to append the program's version number to make it
2506
possible to install several versions of a program at once:
2507
<literal>--program-suffix='$version'</literal>.
2509
<para><replaceable>suffix</replaceable> may contain the following path
2511
<replaceable>$pkgid</replaceable>,
2512
<replaceable>$pkg</replaceable>,
2513
<replaceable>$version</replaceable>,
2514
<replaceable>$compiler</replaceable>,
2515
<replaceable>$os</replaceable>,
2516
<replaceable>$arch</replaceable>
2523
<sect4 id="simple-path-vars">
2524
<title>Path variables in the simple build system</title>
2526
<para>For the simple build system, there are a number of variables
2527
that can be used when specifying installation paths. The defaults
2528
are also specified in terms of these variables. A number of the
2529
variables are actually for other paths, like
2530
<literal>$prefix</literal>. This allows paths to be specified
2531
relative to each other rather than as absolute paths, which is
2532
important for building relocatable packages (see
2533
<xref linkend="prefix-independence"/>).</para>
2537
<term><replaceable>$prefix</replaceable></term>
2539
<para>The path variable that stands for the root of the
2540
installation.</para>
2541
<para>For an installation to be relocatable, all other
2542
instllation paths must be relative to the
2543
<replaceable>$prefix</replaceable> variable.</para>
2548
<term><replaceable>$bindir</replaceable></term>
2550
<para>The path variable that expands to the path given by
2551
the <option>--bindir</option> configure option (or the
2557
<term><replaceable>$libdir</replaceable></term>
2559
<para>As above but for <option>--libdir</option></para>
2564
<term><replaceable>$libsubdir</replaceable></term>
2566
<para>As above but for <option>--libsubdir</option></para>
2571
<term><replaceable>$datadir</replaceable></term>
2573
<para>As above but for <option>--datadir</option></para>
2578
<term><replaceable>$datasubdir</replaceable></term>
2580
<para>As above but for <option>--datasubdir</option></para>
2585
<term><replaceable>$docdir</replaceable></term>
2587
<para>As above but for <option>--docdir</option></para>
2592
<term><replaceable>$pkgid</replaceable></term>
2594
<para>The name and version of the package, eg
2595
<literal>mypkg-0.2</literal></para>
2600
<term><replaceable>$pkg</replaceable></term>
2602
<para>The name of the package, eg
2603
<literal>mypkg</literal></para>
2608
<term><replaceable>$version</replaceable></term>
2610
<para>The version of the package, eg
2611
<literal>0.2</literal></para>
2616
<term><replaceable>$compiler</replaceable></term>
2618
<para>The compiler being used to build the package, eg
2619
<literal>ghc-6.6.1</literal></para>
2624
<term><replaceable>$os</replaceable></term>
2626
<para>The operating system of the computer being used to build
2627
the package, eg <literal>linux</literal>,
2628
<literal>windows</literal>, <literal>osx</literal>,
2629
<literal>freebsd</literal> or <literal>solaris</literal></para>
2634
<term><replaceable>$arch</replaceable></term>
2636
<para>The architecture of the computer being used to build the
2637
package, eg <literal>i386</literal>, <literal>x86_64</literal>,
2638
<literal>ppc</literal> or <literal>sparc</literal></para>
2645
<sect4 id="simple-paths">
2646
<title>Paths in the simple build system</title>
2648
<para>For the simple build system, the following defaults
2653
<colspec align="left"/>
2654
<colspec align="left"/>
2655
<colspec align="left"/>
2659
<entry>Option</entry>
2660
<entry>Windows Default</entry>
2661
<entry>Unix Default</entry>
2666
<entry><literal>--prefix</literal> (global installs with the
2667
<literal>--global</literal> flag) </entry>
2668
<entry><filename>C:\Program Files\Haskell</filename></entry>
2669
<entry><filename>/usr/local</filename></entry>
2672
<entry><literal>--prefix</literal> (per-user installs with
2673
the <literal>--user</literal> flag)</entry>
2674
<entry><filename>C:\Documents And Settings\<replaceable>user</replaceable>\Application Data\cabal</filename></entry>
2675
<entry><filename><replaceable>$HOME</replaceable>/.cabal</filename></entry>
2679
<entry><literal>--bindir</literal></entry>
2680
<entry><literal>$prefix\bin</literal></entry>
2681
<entry><literal>$prefix/bin</literal></entry>
2685
<entry><literal>--libdir</literal></entry>
2686
<entry><literal>$prefix</literal></entry>
2687
<entry><literal>$prefix/lib</literal></entry>
2691
<entry><literal>--libsubdir</literal> (Hugs)</entry>
2692
<entry><literal>hugs\packages\$pkg</literal></entry>
2693
<entry><literal>hugs/packages/$pkg</literal></entry>
2697
<entry><literal>--libsubdir</literal> (others)</entry>
2698
<entry><literal>$pkgid\$compiler</literal></entry>
2699
<entry><literal>$pkgid/$compiler</literal></entry>
2703
<entry><literal>--libexecdir</literal></entry>
2704
<entry><literal>$prefix\$pkgid</literal></entry>
2705
<entry><literal>$prefix/libexec</literal></entry>
2709
<entry><literal>--datadir</literal> (executable)</entry>
2710
<entry><literal>$prefix</literal></entry>
2711
<entry><literal>$prefix/share</literal></entry>
2715
<entry><literal>--datadir</literal> (library)</entry>
2716
<entry><filename>C:\Program Files\Haskell</filename></entry>
2717
<entry><literal>$prefix/share</literal></entry>
2721
<entry><literal>--datasubdir</literal></entry>
2722
<entry><literal>$pkgid</literal></entry>
2723
<entry><literal>$pkgid</literal></entry>
2727
<entry><literal>--docdir</literal></entry>
2728
<entry><literal>$prefix\doc\$pkgid</literal></entry>
2729
<entry><literal>$datadir/doc/$pkgid</literal></entry>
2733
<entry><literal>--htmldir</literal></entry>
2734
<entry><literal>$docdir\html</literal></entry>
2735
<entry><literal>$docdir/html</literal></entry>
2739
<entry><literal>--program-prefix</literal></entry>
2740
<entry>(empty)</entry>
2741
<entry>(empty)</entry>
2745
<entry><literal>--program-suffix</literal></entry>
2746
<entry>(empty)</entry>
2747
<entry>(empty)</entry>
2754
<sect4 id="prefix-independence">
2755
<title>Prefix-independence</title>
2757
<para>On Windows, and when using Hugs on any system, it is
2758
possible to obtain the pathname of the running program.
2759
This means that we can construct an installable executable
2760
package that is independent of its absolute install location.
2761
The executable can find its auxiliary files by finding its
2762
own path and knowing the location of the other files relative
2763
to <replaceable>bindir</replaceable>. Prefix-independence is
2764
particularly useful: it means the user can choose the install
2765
location (i.e. the value of <replaceable>prefix</replaceable>)
2766
at install-time, rather than having to bake the path into
2767
the binary when it is built.</para>
2769
<para>In order to achieve this, we require
2770
that for an executable on Windows, all
2771
of <replaceable>bindir</replaceable>,
2772
<replaceable>libdir</replaceable>,
2773
<replaceable>datadir</replaceable> and
2774
<replaceable>libexecdir</replaceable> begin with
2775
<literal>$prefix</literal>. If this is not the case
2776
then the compiled executable will have baked in
2777
all absolute paths.</para>
2779
<para>The application need do nothing special to achieve
2780
prefix-independence. If it finds any files using
2781
<literal>getDataFileName</literal> and the other functions
2782
provided for the purpose (see <xref linkend="paths-module"/>),
2783
the files will be accessed relative to the location of the
2784
current executable.</para>
2786
<para>A library cannot (currently) be prefix-independent,
2787
because it will be linked into an executable whose
2788
file system location bears no relation to the library
2793
<sect3 id="flag-control">
2794
<title>Controlling Flag Assignments</title>
2795
<para>Flag assignments (see <xref linkend="conditional-resolution"/>) can be
2796
controlled with the following command line options.</para>
2799
<term><option>-f</option><replaceable>flagname</replaceable> or
2800
<option>-f</option><literal>-</literal><replaceable>flagname</replaceable></term>
2802
<para>Force the specified flag to
2803
<literal>true</literal> or <literal>false</literal> (if
2804
preceded with a <literal>-</literal>). Later
2805
specifications for the same flags will override earlier,
2806
i.e., specifying <literal>-fdebug -f-debug</literal> is
2807
equivalent to <literal>-f-debug</literal></para>
2811
<term><option>--flags</option>=<replaceable>flagspecs</replaceable></term>
2813
<para>Same as <option>-f</option>, but allows specifying
2814
multiple flag assignments at once. The parameter is a
2815
space-separated list of flag names (to force a flag to
2816
<literal>true</literal>), optionally preceded by a
2817
<literal>-</literal> (to force a flag to
2818
<literal>false</literal>). For example,
2819
<literal>--flags="debug -feature1 feature2"</literal> is
2820
equivalent to <literal>-fdebug -f-feature1
2821
-ffeature2</literal>.</para>
2828
<sect3 id="setup-configure-misc">
2829
<title>Miscellaneous options</title>
2833
<term><option>--user</option></term>
2835
<para>Does a per-user installation. This changes the default
2836
installation prefix (see <xref linkend="simple-paths"/>).
2837
It also allow dependencies to be satisfied by the user's
2838
package database, in addition to the global database.</para>
2840
<para>This also implies a default of <option>--user</option>
2841
for any subsequent <literal>install</literal> command,
2842
as packages registered in the global database should not
2843
depend on packages registered in a user's database.</para>
2848
<term><option>--global</option></term>
2850
<para>(default) Does a global installation. In this case
2851
package dependencies must be satisfied by the global
2852
package database. All packages in the user's package database
2853
will be ignored. Typically the final instllation step will
2854
require administrative privileges.</para>
2859
<term><option>--package-db</option>=<replaceable>db</replaceable></term>
2861
<para>Allows package dependencies to be satisfied from this
2862
additional package database <replaceable>db</replaceable> in
2863
addition to the global package database. All packages in the
2864
user's package database will be ignored. The interpretation
2865
of <replaceable>db</replaceable> is implementation-specific.
2866
Typically it will be a file or directory. Not all
2867
implementations support arbitrary package databases.
2873
<term><option>--enable-optimization</option>[=<replaceable>n</replaceable>] or <option>-O</option>[<replaceable>n</replaceable>]</term>
2875
<para>(default) Build with optimization flags (if available).
2876
This is appropriate for production use, taking more time
2877
to build faster libraries and programs.</para>
2879
The optional <replaceable>n</replaceable> value is the
2880
optimisation level. Some compilers support multiple
2881
optimisation levels. The range is 0 to 2. Level 0 is
2882
equivalent to <option>--disable-optimization</option>,
2883
level 1 is the default if no <replaceable>n</replaceable>
2884
parameter is given. Level 2 is higher optimisation if the
2885
compiler supports it. Level 2 is likely to lead to longer
2886
compile times and bigger generated code.
2892
<term><option>--disable-optimization</option></term>
2894
<para>Build without optimization. This is suited for
2895
development: building will be quicker, but the resulting
2896
library or programs will be slower.</para>
2901
<term><option>--enable-library-profiling</option> or
2902
<option>-p</option></term>
2904
<para>Request that an additional version of the library
2905
with profiling features enabled be built and installed
2906
(only for implementations that support profiling).</para>
2911
<term><option>--disable-library-profiling</option></term>
2913
<para>(default) Do not generate an additional profiling
2914
version of the library.</para>
2919
<term><option>--enable-executable-profiling</option></term>
2921
<para>Any executables generated should have profiling enabled
2922
(only for implementations that support profiling). For this
2923
to work, all libraries used by these executables must also
2924
have been built with profiling support.</para>
2929
<term><option>--disable-executable-profiling</option></term>
2931
<para>(default) Do not enable profiling in generated
2937
<term><option>--enable-library-vanilla</option></term>
2939
<para>(default) Build ordinary libraries (as opposed to profiling
2940
libraries). This is independent of the
2941
<option>--enable-library-profiling</option> option. If you
2942
enable both, you get both.</para>
2947
<term><option>--disable-library-vanilla</option></term>
2949
<para>Do not build ordinary libraries. This is useful
2950
in conjunction with <option>--enable-library-profiling</option>
2951
to build only profiling libraries, rather than profiling and
2952
ordinary libraries.</para>
2957
<term><option>--enable-library-for-ghci</option></term>
2959
<para>(default) Build libraries suitable for use with GHCi.</para>
2964
<term><option>--disable-library-for-ghci</option></term>
2966
<para>Not all platforms support GHCi and indeed on some
2967
platforms, trying to build GHCi libs fails. In such cases
2968
this flag can be used as a workaround.</para>
2973
<term><option>--enable-split-objs</option></term>
2975
<para>Use the GHC <option>-split-objs</option> feature when
2976
building the library. This reduces the final size of the
2977
executables that use the library by allowing them to link with
2978
only the bits that they use rather than the entire library.
2979
The downside is that building the library takes longer and uses
2980
considerably more memory.</para>
2985
<term><option>--disable-split-objs</option></term>
2987
<para>(default) Do not use the GHC <option>-split-objs</option>
2988
feature. This makes building the library quicker but the final
2989
executables that use the library will be larger.</para>
2994
<term><option>--enable-executable-stripping</option></term>
2997
(default) When installing binary executable programs, run the
2998
<literal>strip</literal> program on the binary. This can
2999
considerably reduce the size of the executable binary file. It
3000
does this by removing debugging information and symbols. While
3001
such extra information is useful for debugging C programs with
3002
traditional debuggers it is rarely helpful for debugging
3003
binaries produced by Haskell compilers.
3006
Not all Haskell implementations generate native binaries. For
3007
such implementations this option has no effect.
3013
<term><option>--disable-executable-stripping</option></term>
3016
Do not strip binary executables during installation. You
3017
might want to use this option if you need to debug a program
3018
using gdb, for example if you want to debug the C parts of a
3019
program containing both Haskell and C code. Another reason is
3020
if your are building a package for a system which has a policy
3021
of managing the stripping itself (such as some linux
3028
<term><option>--enable-shared</option></term>
3030
<para>Build shared library. This implies a seperate
3031
compiler run to generate position independent code as
3032
required on most platforms.</para>
3038
<term><option>--disable-shared</option></term>
3040
<para>(default) Do not build shared library.</para>
3046
<term><option>--configure-option</option>=<replaceable>str</replaceable></term>
3048
<para>An extra option to an external
3049
<filename>configure</filename> script,
3050
if one is used (see <xref linkend="system-dependent"/>).
3051
There can be several of these options.</para>
3057
<term><option>--extra-include-dirs</option>[=<replaceable>dir</replaceable>]</term>
3060
An extra directory to search for C header files. You can use
3061
this flag multiple times to get a list of directories.
3064
You might need to use this flag if you have standard system
3065
header files in a non-standard location that is not mentioned
3066
in the package's <filename>.cabal</filename> file. Using this
3067
option has the same affect as appending the directory
3068
<replaceable>dir</replaceable> to the
3069
<literal>include-dirs</literal> field in each library and
3070
executable in the package's <filename>.cabal</filename> file.
3071
The advantage of course is that you do not have to modify the
3072
package at all. These extra directories will be used while
3073
building the package and for libraries it is also saved in the
3074
package registration information and used when compiling
3075
modules that use the library.
3082
<term><option>--extra-lib-dirs</option>[=<replaceable>dir</replaceable>]</term>
3085
An extra directory to search for system libraries files. You
3086
can use this flag multiple times to get a list of directories.
3089
You might need to use this flag if you have standard system
3090
libraries in a non-standard location that is not mentioned
3091
in the package's <filename>.cabal</filename> file. Using this
3092
option has the same affect as appending the directory
3093
<replaceable>dir</replaceable> to the
3094
<literal>extra-lib-dirs</literal> field in each library and
3095
executable in the package's <filename>.cabal</filename> file.
3096
The advantage of course is that you do not have to modify the
3097
package at all. These extra directories will be used while
3098
building the package and for libraries it is also saved in the
3099
package registration information and used when compiling
3100
modules that use the library.
3107
<para>In the simple build infrastructure, an additional option
3108
is recognized:</para>
3111
<term><option>--scratchdir</option>=<replaceable>dir</replaceable></term>
3113
<para>Specify the directory into which the Hugs output will be
3114
placed (default: <filename>dist/scratch</filename>).</para>
3123
<sect2 id="setup-build">
3124
<title>setup build</title>
3125
<para>Perform any preprocessing or compilation needed to make this
3126
package ready for installation.</para>
3128
<para>This command takes the following options:</para>
3132
<term><option>--<replaceable>prog</replaceable>-options</option>=<replaceable>options</replaceable></term>
3133
<term><option>--<replaceable>prog</replaceable>-option</option>=<replaceable>option</replaceable></term>
3135
<para>These are mostly the same as the options configure step (see
3136
<xref linkend="setup-configure-programs"/>). Unlike the options
3137
specified at the configure step, any program options specified at
3138
the build step are not persistent but are used for that
3139
invocation only. They options specified at the build step are in
3140
addition not in replacement of any options specified at the
3149
<sect2 id="setup-makefile">
3150
<title>setup makefile</title>
3151
<para>Generate a <filename>Makefile</filename> that may be used
3152
to compile the Haskell modules to object code.
3153
This command is currently only supported when building libraries,
3154
and only if the compiler is GHC.</para>
3156
<para>The makefile command replaces part of the work done by
3157
<literal>setup build</literal>. The sequence of commands would
3160
runhaskell Setup.hs makefile
3162
runhaskell Setup.hs build
3164
where <literal>setup makefile</literal> does the preprocessing,
3165
<literal>make</literal> compiles the Haskell modules, and
3166
<literal>setup build</literal> performs any final steps, such as
3167
building the library archives.</para>
3169
<para>The Makefile does not use GHC's <literal>--make</literal>
3170
flag to compile the modules, instead it compiles modules one at
3171
a time, using dependency information generated by GHC's
3172
<literal>-M</literal> flag. There are two reasons you might
3173
therefore want to use <literal>setup makefile</literal>:
3177
<para>You want to build in parallel using <literal>make -j</literal>.
3178
Currently, <literal>setup build</literal> on its own does not support
3179
building in parallel.</para>
3182
<para>You want to build an individual module, pass extra
3183
flags to a compilation, or do other non-standard things that
3184
<literal>setup build</literal> does not support.</para>
3189
<para>This command takes the following options:</para>
3193
<term><option>--file</option>=<replaceable>filename</replaceable> or
3194
<option>-f</option> <replaceable>filename</replaceable></term>
3196
<para>Specify the output file (default <filename>Makefile</filename>).</para>
3203
<sect2 id="setup-haddock">
3204
<title>setup haddock</title>
3205
<para>Build the documentation for the package using &Haddock;. By
3206
default, only the documentation for the exposed modules is generated
3207
(see <xref linkend="setup-haddock-executables"/>).</para>
3209
<para>This command takes the following options:</para>
3213
<term><option>--hoogle</option></term>
3215
<para>Generate a file
3216
<filename>dist/doc/html/<replaceable>pkgid</replaceable>.txt</filename>,
3217
which can be converted by
3218
<ulink url="http://www.haskell.org/hoogle/">Hoogle</ulink>
3219
into a database for searching. This is
3220
equivalent to running &Haddock; with the <option>--hoogle</option> flag.
3226
<term><option>--html-location</option>=<replaceable>url</replaceable></term>
3228
<para>Specify a template for the location of HTML documentation
3229
for prerequisite packages. The substitutions listed in
3230
<xref linkend="simple-paths"/> are applied to the template
3231
to obtain a location for each package, which will be used
3232
by hyperlinks in the generated documentation. For example,
3233
the following command generates links pointing at &HackageDB;
3235
<screen>setup haddock --html-location='http://hackage.haskell.org/packages/archive/$pkg/latest/doc/html'</screen>
3236
<para>Here the argument is quoted to prevent substitution
3237
by the shell.</para>
3238
<para>If this option is omitted, the location for each package
3239
is obtained using the package tool (e.g.
3240
<command>ghc-pkg</command>).</para>
3244
<varlistentry id="setup-haddock-executables">
3245
<term><option>--executables</option></term>
3247
<para>Also run &Haddock; for the modules of all the executable
3248
programs. By default &Haddock; is run only on the exported
3253
<varlistentry id="setup-haddock-internal">
3254
<term><option>--internal</option></term>
3256
<para>Run &Haddock; for the all modules, including unexposed ones, and
3257
make &Haddock; generate documentation for unexported symbols
3262
<varlistentry id="setup-haddock-css">
3263
<term><option>--css</option>=<replaceable>path</replaceable></term>
3265
<para>The argument <replaceable>path</replaceable> denotes a CSS
3266
file, which is passed to &Haddock; and used to set the style of
3267
the generated documentation. This is only needed to override the
3268
default style that &Haddock; uses.
3274
<term><option>--hyperlink-source</option></term>
3276
<para>Generate &Haddock; documentation integrated with &HsColour;.
3277
First, &HsColour; is run to generate colourised code.
3278
Then &Haddock; is run to generate HTML documentation. Each
3279
entity shown in the documentation is linked to its definition in
3280
the colourised code.</para>
3285
<term><option>--hscolour-css</option>=<replaceable>path</replaceable></term>
3287
<para>The argument <replaceable>path</replaceable> denotes a CSS
3288
file, which is passed to &HsColour; as in</para>
3290
runhaskell Setup.hs hscolour --css=<replaceable>path</replaceable></screen>
3297
<sect2 id="setup-hscolour">
3298
<title>setup hscolour</title>
3299
<para>Produce colourised code in HTML format using &HsColour;.
3300
Colourised code for exported modules is put in
3301
<filename>dist/doc/html/<replaceable>pkgid</replaceable>/src</filename>.</para>
3303
<para>This command takes the following options:</para>
3307
<term><option>--executables</option></term>
3309
<para>Also run &HsColour; on the sources of all executable
3310
programs. Colourised code is put in
3311
<filename>dist/doc/html/<replaceable>pkgid</replaceable>/<replaceable>executable</replaceable>/src</filename>.</para>
3316
<term><option>--css</option>=<replaceable>path</replaceable></term>
3318
<para>Copy the CSS file from <replaceable>path</replaceable> to
3319
<filename>dist/doc/html/<replaceable>pkgid</replaceable>/src/hscolour.css</filename>
3320
for exported modules, or to
3321
<filename>dist/doc/html/<replaceable>pkgid</replaceable>/<replaceable>executable</replaceable>/src/hscolour.css</filename>
3322
for executable programs. The CSS file defines the actual colours
3323
used to colourise code. Note that the
3324
<filename>hscolour.css</filename> file is required for the code
3325
to be actually colourised.</para>
3331
<sect2 id="setup-install">
3332
<title>setup install</title>
3333
<para>Copy the files into the install locations and (for library
3334
packages) register the package with the compiler, i.e. make the
3335
modules it contains available to programs.</para>
3337
<para>The install locations are determined by options to
3338
<command>setup configure</command>
3339
(see <xref linkend="setup-configure-paths"/>).</para>
3341
<para>This command takes the following options:</para>
3345
<term><option>--global</option></term>
3347
<para>Register this package in the system-wide database.
3348
(This is the default, unless the <option>--user</option>
3349
option was supplied to the <literal>configure</literal>
3355
<term><option>--user</option></term>
3357
<para>Register this package in the user's local package database.
3358
(This is the default if the <option>--user</option>
3359
option was supplied to the <literal>configure</literal>
3366
<sect2 id="setup-copy">
3367
<title>setup copy</title>
3368
<para>Copy the files without registering them. This command
3369
is mainly of use to those creating binary packages.</para>
3371
<para>This command takes the following option:</para>
3375
<term><option>--destdir</option>=<replaceable>path</replaceable></term>
3377
<para>Specify the directory under which to place
3378
installed files. If this is not given, then the root
3379
directory is assumed.</para>
3385
<sect2 id="setup-register">
3386
<title>setup register</title>
3387
<para>Register this package with the compiler, i.e. make the
3388
modules it contains available to programs. This only makes sense
3389
for library packages. Note that the <literal>install</literal>
3390
command incorporates this action. The main use of this
3391
separate command is in the post-installation step for a binary
3394
<para>This command takes the following options:</para>
3398
<term><option>--global</option></term>
3400
<para>Register this package in the system-wide database.
3401
(This is the default.)</para>
3406
<term><option>--user</option></term>
3408
<para>Register this package in the user's local package
3414
<term><option>--gen-script</option></term>
3416
<para>Instead of registering the package, generate a script
3417
containing commands to perform the registration. On Unix,
3418
this file is called <filename>register.sh</filename>, on
3419
Windows, <filename>register.bat</filename>. This script
3420
might be included in a binary bundle, to be run after the
3421
bundle is unpacked on the target system.</para>
3426
<term><option>--gen-pkg-config</option>=[<replaceable>path</replaceable>]</term>
3428
<para>Instead of registering the package, generate a package
3429
registration file. This only applies to compilers that support
3430
package registration files which at the moment is only GHC.
3431
The file should be used with the compiler's mechanism for
3432
registering packages.</para>
3433
<para>This option is mainly intended for packaging systems. If
3434
possible use the <option>--gen-script</option> option instead
3435
since it is more portable across Haskell implementations.</para>
3436
<para>The <replaceable>path</replaceable> is optional and can be
3437
used to specify a particular output file to generate. Otherwise,
3438
by default the file is the package name and version with a
3439
<literal>.conf</literal> extension.</para>
3444
<term><option>--inplace</option></term>
3446
<para>Registers the package for use directly from the
3447
build tree, without needing to install it. This can be
3448
useful for testing: there's no need to install the package
3449
after modifying it, just recompile and test.</para>
3451
<para>This flag does not create a build-tree-local package
3452
database. It still registers the package in one of the
3453
user or global databases.</para>
3455
<para>However, there are some caveats. It only works with
3456
GHC (currently). It only works if your package doesn't
3457
depend on having any supplemental files installed - plain
3458
Haskell libraries should be fine.</para>
3464
<sect2 id="setup-unregister">
3465
<title>setup unregister</title>
3466
<para>Deregister this package with the compiler.</para>
3468
<para>This command takes the following options:</para>
3472
<term><option>--global</option></term>
3474
<para>Deregister this package in the system-wide database.
3475
(This is the default.)</para>
3480
<term><option>--user</option></term>
3482
<para>Deregister this package in the user's local package
3488
<term><option>--gen-script</option></term>
3490
<para>Instead of deregistering the package, generate a script
3491
containing commands to perform the deregistration. On Unix,
3492
this file is called <filename>unregister.sh</filename>, on
3493
Windows, <filename>unregister.bat</filename>. This script
3494
might be included in a binary bundle, to be run on the
3495
target system.</para>
3501
<sect2 id="setup-clean">
3502
<title>setup clean</title>
3503
<para>Remove any local files created during the
3504
<literal>configure</literal>, <literal>build</literal>,
3505
<literal>haddock</literal>, <literal>register</literal> or
3506
<literal>unregister</literal> steps, and also any files and
3507
directories listed in the <literal>extra-tmp-files</literal>
3510
<para>This command takes the following options:</para>
3514
<term><option>--save-configure</option> or <option>-s</option></term>
3516
<para>Keeps the configuration information so it is not necessary
3517
to run the configure step again before building.</para>
3523
<sect2 id="setup-test">
3524
<title>setup test</title>
3526
<para>Run the test suite specified by the
3527
<literal>runTests</literal> field of
3528
<literal>Distribution.Simple.UserHooks</literal>. See &Simple;
3529
for information about creating hooks and using
3530
<literal>defaultMainWithHooks</literal>.</para>
3534
<sect2 id="setup-sdist">
3535
<title>setup sdist</title>
3536
<para>Create a system- and compiler-independent source distribution
3538
<filename><replaceable>package</replaceable>-<replaceable>version</replaceable>.tar.gz</filename>
3539
in the <filename>dist</filename> subdirectory, for distribution
3540
to package builders. When unpacked, the commands listed in this
3541
section will be available.</para>
3543
<para>The files placed in this distribution are the package
3544
description file, the setup script, the sources of the modules
3545
named in the package description file, and files named in the
3546
<literal>license-file</literal>, <literal>main-is</literal>,
3547
<literal>c-sources</literal>, <literal>data-files</literal> and
3548
<literal>extra-source-files</literal> fields.</para>
3550
<para>This command takes the following option:</para>
3554
<term><option>--snapshot</option></term>
3556
<para>Append today's date
3557
(in <replaceable>YYYYMMDD</replaceable> form) to the version
3558
number for the generated source package. The original
3559
package is unaffected.</para>
3567
<title>Reporting bugs and deficiencies</title>
3569
<para>Please report any flaws or feature requests in the
3570
<ulink url="http://hackage.haskell.org/trac/hackage/">bug
3574
<para>For general discussion or queries email the libraries mailing list
3575
<email>libraries@haskell.org</email>. There is also a development mailing
3576
list <email>cabal-devel@haskell.org</email>.
3580
<sect1 id="stability">
3581
<title>Stability of Cabal interfaces</title>
3583
<para>The Cabal library and related infrastructure is still under active
3584
development. New features are being added and limitations and bugs are
3585
being fixed. This requires internal changes and often user visible
3586
changes as well. We therefor cannot promise complete future-proof
3587
stability, at least not without halting all development work.</para>
3589
<para>This section documents the aspects of the Cabal interface that we can
3590
promise to keep stable and which bits are subject to change.</para>
3593
<title>Cabal file format</title>
3595
This is backwards compatible and mostly forwards compatible.
3596
New fields can be added without breaking older versions of Cabal.
3597
Fields can be deprecated without breaking older packages.
3602
<title>Command-line interface</title>
3604
<title>Very Stable Command-line interfaces</title>
3611
<listitem><para>--prefix</para></listitem>
3612
<listitem><para>--user</para></listitem>
3613
<listitem><para>--ghc, --hugs</para></listitem>
3614
<listitem><para>--verbose</para></listitem>
3615
<listitem><para>--prefix</para></listitem>
3619
<listitem><para>./setup build</para></listitem>
3620
<listitem><para>./setup install</para></listitem>
3621
<listitem><para>./setup register</para></listitem>
3622
<listitem><para>./setup copy</para></listitem>
3627
<title>Stable Command-line interfaces</title>
3632
<title>Unstable command-line</title>
3638
<title>Functions and Types</title>
3640
The Cabal library follows the <ulink
3641
url="http://haskell.org/haskellwiki/Package_versioning_policy">Package
3642
Versioning Policy</ulink>. This means that within a stable major
3643
release, for example 1.2.x, there will be no incompatible API changes.
3644
But minor versions increments, for example 1.2.3, indicate compatible
3649
The Package Versioning Policy does not require any API guarantees
3650
between major releases, for example between 1.2.x and 1.4.x. In
3651
practise of course not everything changes between major releases. Some
3652
parts of the API are more prone to change than others. The rest of this
3653
section gives some informal advice on what level of API stability you
3654
can expect between major releases.
3658
<title>Very Stable API</title>
3660
<listitem><para><literal>defaultMain</literal></para></listitem>
3663
<literal>defaultMainWithHooks defaultUserHooks</literal>
3666
But regular <literal>defaultMainWithHooks</literal> isn't stable
3667
since <literal>UserHooks</literal> changes.
3674
<title>Semi-stable API</title>
3678
<para><literal>UserHooks</literal> The hooks API will change in the
3682
<para><literal>Distribution.<replaceable>*</replaceable></literal>
3683
is mostly declarative information about packages and is somewhat
3691
<title>Unstable API</title>
3694
<literal>Distribution.Simple.<replaceable>*</replaceable></literal>
3695
has no stability guarantee.
3701
<title>Hackage</title>
3703
The index format is a partly stable interface. It consists of a tar.gz
3704
file that contains directories with <filename>.cabal</filename> files
3705
in. In future it may contain more kinds of files so do not assume every
3706
file is a <filename>.cabal</filename> file. Incompatible revisions to
3707
the format would involve bumping the name of the index file, i.e.,
3708
<filename>00-index.tar.gz</filename>,
3709
<filename>01-index.tar.gz</filename> etc.
added
removed
libraries/Cabal/doc/Cabal.xml
