<?xml version="1.0" encoding="US-ASCII"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
<!ENTITY Simple '<ulink url="../libraries/Cabal/Distribution-Simple.html">Distribution.Simple</ulink>'>
<!ENTITY Make '<ulink url="../libraries/Cabal/Distribution-Make.html">Distribution.Make</ulink>'>
<!ENTITY License '<ulink url="../libraries/Cabal/Distribution-License.html#t:License"><literal>License</literal></ulink>'>
<!ENTITY Extension '<ulink url="../libraries/Cabal/Language-Haskell-Extension.html#t:Extension"><literal>Extension</literal></ulink>'>
<!ENTITY BuildType '<ulink url="../libraries/Cabal/Distribution-PackageDescription.html#t:BuildType"><literal>BuildType</literal></ulink>'>
<!ENTITY Alex '<ulink url="http://www.haskell.org/alex/"><command>alex</command></ulink>'>
<!ENTITY Autoconf '<ulink url="http://www.gnu.org/software/autoconf/"><command>autoconf</command></ulink>'>
<!ENTITY C2hs '<ulink url="http://www.cse.unsw.edu.au/~chak/haskell/c2hs/"><command>c2hs</command></ulink>'>
<!ENTITY Cpphs '<ulink url="http://www.haskell.org/cpphs/"><command>cpphs</command></ulink>'>
<!ENTITY Greencard '<ulink url="http://www.haskell.org/greencard/"><command>greencard</command></ulink>'>
<!ENTITY Haddock '<ulink url="http://www.haskell.org/haddock/"><command>haddock</command></ulink>'>
<!ENTITY HsColour '<ulink url="http://www.cs.york.ac.uk/fp/darcs/hscolour/"><command>HsColour</command></ulink>'>
<!ENTITY Happy '<ulink url="http://www.haskell.org/happy/"><command>happy</command></ulink>'>
<!ENTITY HackageDB '<ulink url="http://hackage.haskell.org/">HackageDB</ulink>'>
]>
<article>
<title>Common Architecture for Building Applications and Libraries</title>
<subtitle>User's Guide</subtitle>
<abstract>
<para>The <firstterm>Cabal</firstterm> aims to simplify the
distribution of <ulink url="http://www.haskell.org/">Haskell</ulink>
software. It does this by specifying a number of interfaces between
package authors, builders and users, as well as providing a library
implementing these interfaces.</para>
</abstract>
<sect1 id="packages">
<title>Packages</title>
<para>A <firstterm>package</firstterm> is the unit of distribution
for the Cabal. Its purpose, when installed, is to make available
either or both of:</para>
<itemizedlist>
<listitem>
<para>A library, exposing a number of Haskell modules. A library
may also contain <firstterm>hidden</firstterm> modules, which
are used internally but not available to clients.<footnote>
<para>Hugs doesn't support module hiding.</para>
</footnote>
</para>
</listitem>
<listitem>
<para>One or more Haskell programs.</para>
</listitem>
</itemizedlist>
<para>However having both a library and executables in a package
does not work very well; if the executables depend on the library,
they must explicitly list all the modules they directly or
indirectly import from that library.</para>
<para>Internally, the package may consist of much more than a
bunch of Haskell modules: it may also have C source code and
header files, source code meant for preprocessing, documentation,
test cases, auxiliary tools etc.</para>
<para>A package is identified by a globally-unique
<firstterm>package name</firstterm>, which consists of one or
more alphanumeric words separated by hyphens. To avoid ambiguity,
each of these words should contain at least one letter.
Chaos will result if two distinct packages with the
same name are installed on the same system, but there is not
yet a mechanism for allocating these names.
A particular version of the package is distinguished by a
<firstterm>version number</firstterm>, consisting of a sequence
of one or more integers separated by dots. These can be combined
to form a single text string called the <firstterm>package
ID</firstterm>, using a hyphen to separate the name from the
version, e.g. <quote><literal>HUnit-1.1</literal></quote>.</para>
<note>
<para>Packages are not part of the Haskell language;
they simply populate the hierarchical space of module names.
In GHC 6.6 and later a program may contain multiple modules
with the same name if they come from separate packages; in all
other current Haskell systems packages may not overlap in the
modules they provide, including hidden modules.</para>
</note>
</sect1>
<sect1 id="authors">
<title>Creating a package</title>
<para>Suppose you have a directory hierarchy containing the source
files that make up your package. You will need to add two more
files to the root directory of the package:</para>
<variablelist>
<varlistentry>
<term>
<filename><replaceable>package</replaceable>.cabal</filename>
</term>
<listitem>
<para>a text file containing a package description
(for details of the syntax of this file, see
<xref linkend="pkg-descr"/>), and</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<filename>Setup.hs</filename> or
<filename>Setup.lhs</filename>
</term>
<listitem>
<para>a single-module Haskell program to perform various
setup tasks (with the interface described in
<xref linkend="builders"/>). This module should import only
modules that will be present in all Haskell implementations,
including modules of the Cabal library. In most cases it
will be trivial, calling on the Cabal library to do most of
the work.</para>
</listitem>
</varlistentry>
</variablelist>
<para>Once you have these, you can create a source bundle of this
directory for distribution. Building of the package is discussed in
<xref linkend="builders"/>.</para>
<example id="simple-library-example">
<title>A package containing a simple library</title>
<para>The HUnit package contains a file <filename>HUnit.cabal</filename>
containing:</para>
<programlisting>
Name: HUnit
Version: 1.1
License: BSD3
Author: Dean Herington
Homepage: http://hunit.sourceforge.net/
Category: Testing
Build-Type: Simple
Build-Depends: base
Synopsis: Unit testing framework for Haskell
Exposed-modules:
Test.HUnit, Test.HUnit.Base, Test.HUnit.Lang,
Test.HUnit.Terminal, Test.HUnit.Text
Extensions: CPP</programlisting>
<para>and the following <filename>Setup.hs</filename>:</para>
<programlisting>
import Distribution.Simple
main = defaultMain</programlisting>
</example>
<example id="simple-executable-example">
<title>A package containing executable programs</title>
<programlisting>
Name: TestPackage
Version: 0.0
License: BSD3
Author: Angela Author
Synopsis: Small package with two programs
Build-Type: Simple
Build-Depends: HUnit
Executable: program1
Main-Is: Main.hs
Hs-Source-Dirs: prog1
Executable: program2
Main-Is: Main.hs
Hs-Source-Dirs: prog2
Other-Modules: Utils</programlisting>
<para>with <filename>Setup.hs</filename> the same as above.</para>
</example>
<example id="simple-library-executable-example">
<title>A package containing a library and executable programs</title>
<programlisting>
Name: TestPackage
Version: 0.0
License: BSD3
Author: Angela Author
Synopsis: Package with library and two programs
Build-Type: Simple
Build-Depends: HUnit
Exposed-Modules: A, B, C
Executable: program1
Main-Is: Main.hs
Hs-Source-Dirs: prog1
Other-Modules: A, B
Executable: program2
Main-Is: Main.hs
Hs-Source-Dirs: prog2
Other-Modules: A, C, Utils</programlisting>
<para>with <filename>Setup.hs</filename> the same as above.
Note that any library modules required (directly or indirectly)
by an executable must be listed again.</para>
</example>
<para>The trivial setup script used in these examples uses
the <firstterm>simple build infrastructure</firstterm>
provided by the Cabal library (see &Simple;).
The simplicity lies in its interface rather that its implementation.
It automatically handles preprocessing with standard preprocessors,
and builds packages for all the Haskell implementations (except
nhc98, for now).</para>
<para>The simple build infrastructure can also handle packages
where building is governed by system-dependent parameters,
if you specify a little more (see <xref linkend="system-dependent"/>).
A few packages require more elaborate solutions
(see <xref linkend="complex-packages"/>).</para>
<sect2 id="pkg-descr">
<title>Package descriptions</title>
<para>The package description file should have a name ending in
<quote><literal>.cabal</literal></quote>. There must be exactly
one such file in the directory. The first part of the name is
usually the package name, and some of the tools that operate
on Cabal packages require this.</para>
<para>In the package description file, lines beginning with
<quote><literal>--</literal></quote> are treated as comments
and ignored.</para>
<para>This file should contain one or more
<firstterm>stanzas</firstterm> separated by blank lines:</para>
<itemizedlist>
<listitem>
<para>The first stanza describes the package as a whole
(see <xref linkend="general-fields"/>), as well as an optional
library (see <xref linkend="library"/>) and relevant build
information (see <xref linkend="buildinfo"/>).</para>
</listitem>
<listitem>
<para>Each subsequent stanza (if any) describes an executable
program (see <xref linkend="executable"/>) and relevant
build information (see <xref linkend="buildinfo"/>).</para>
</listitem>
</itemizedlist>
<para>Each stanza consists of a number of field/value pairs, with a
syntax like mail message headers.</para>
<itemizedlist>
<listitem>
<para>case is not significant in field names,
but is significant in field values</para>
</listitem>
<listitem>
<para>to continue a field value, indent the next line</para>
</listitem>
<listitem>
<para>to get a blank line in a field value, use an indented
<quote><literal>.</literal></quote></para>
</listitem>
</itemizedlist>
<para>The syntax of the value depends on the field. Field types
include:</para>
<variablelist>
<varlistentry>
<term>
<replaceable>token</replaceable>
</term>
<term>
<replaceable>filename</replaceable>
</term>
<term>
<replaceable>directory</replaceable>
</term>
<listitem>
<para>Either a sequence of one or more non-space non-comma
characters, or a quoted string in Haskell 98 lexical syntax.
Unless otherwise stated, relative filenames and directories
are interpreted from the package root directory.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<replaceable>freeform</replaceable>
</term>
<term>
<replaceable>URL</replaceable>
</term>
<term>
<replaceable>address</replaceable>
</term>
<listitem>
<para>An arbitrary, uninterpreted string.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<replaceable>identifier</replaceable>
</term>
<listitem>
<para>A letter followed by zero or more alphanumerics
or underscores.</para>
</listitem>
</varlistentry>
</variablelist>
<note>
<title>Modules and preprocessors</title>
<para>Haskell module names listed in the
<literal>exposed-modules</literal> and
<literal>other-modules</literal> fields may
correspond to Haskell source files, i.e. with names
ending in <quote><literal>.hs</literal></quote> or
<quote><literal>.lhs</literal></quote>, or to inputs for
various Haskell preprocessors.
The simple build infrastructure understands the extensions
<quote><literal>.gc</literal></quote> (&Greencard;),
<quote><literal>.chs</literal></quote> (&C2hs;),
<quote><literal>.hsc</literal></quote> (<command>hsc2hs</command>),
<quote><literal>.y</literal></quote> and
<quote><literal>.ly</literal></quote> (&Happy;),
<quote><literal>.x</literal></quote> (&Alex;)
and
<quote><literal>.cpphs</literal></quote> (&Cpphs;).
When building, Cabal will automatically run the appropriate
preprocessor and compile the Haskell module it produces.</para>
</note>
<para>Some fields take lists of values, which
are optionally separated by commas, except for the
<literal>build-depends</literal> field, where the commas are
mandatory.</para>
<para>Some fields are marked as required. All others are optional,
and unless otherwise specified have empty default values.</para>
<sect3 id="general-fields">
<title>Package properties</title>
<para>These fields may occur in the first stanza, and describe
the package as a whole:</para>
<variablelist>
<varlistentry>
<term>
<literal>name:</literal> <replaceable>package-name</replaceable>
(required)
</term>
<listitem>
<para>The unique name of the package
(see <xref linkend="packages"/>), without the version
number.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>version:</literal> <replaceable>numbers</replaceable>
(required)
</term>
<listitem>
<para>The package version number, usually consisting of a
sequence of natural numbers separated by dots.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>cabal-version:</literal> <replaceable>>, <=, etc. & numbers</replaceable>
</term>
<listitem>
<para>The version of Cabal required for this package.
Use <emphasis>only</emphasis> if this package requires
a particular version of Cabal, since unfortunately
early versions of Cabal do not recognize this field.
List the field early in your <literal>.cabal</literal>
file so that it will appear as a syntax error before
any others.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>build-type:</literal> <replaceable>identifier</replaceable>
</term>
<listitem>
<para>The type of build used by this package.
Build types are the constructors of the &BuildType; type,
defaulting to <literal>Custom</literal>.
If this field is given a value other than
<literal>Custom</literal>, some tools will be able to
build the package without using the setup script.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>license:</literal> <replaceable>identifier</replaceable>
(default: <literal>AllRightsReserved</literal>)
</term>
<listitem>
<para>The type of license under which this package is
distributed. License names are the constants of the
&License; type.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>license-file:</literal>
<replaceable>filename</replaceable>
</term>
<listitem>
<para>The name of a file containing the precise license
for this package.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>copyright:</literal>
<replaceable>freeform</replaceable>
</term>
<listitem>
<para>The content of a copyright notice, typically the
name of the holder of the copyright on the package and
the year(s) from which copyright is claimed.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>author:</literal>
<replaceable>freeform</replaceable>
</term>
<listitem>
<para>The original author of the package.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>maintainer:</literal>
<replaceable>address</replaceable>
</term>
<listitem>
<para>The current maintainer or maintainers of the package.
This is an e-mail address to which users should send bug
reports, feature requests and patches.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>stability:</literal>
<replaceable>freeform</replaceable>
</term>
<listitem>
<para>The stability level of the package, e.g.
<literal>alpha</literal>, <literal>experimental</literal>,
<literal>provisional</literal>,
<literal>stable</literal>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>homepage:</literal> <replaceable>URL</replaceable>
</term>
<listitem>
<para>The package homepage.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>package-url:</literal> <replaceable>URL</replaceable>
</term>
<listitem>
<para>The location of a source bundle for the package.
The distribution should be a Cabal package.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>synopsis:</literal>
<replaceable>freeform</replaceable>
</term>
<listitem>
<para>A very short description of the package, for use in
a table of packages. This is your headline, so keep
it short (one line) but as informative as possible.
Save space by not including the package name or saying
it's written in Haskell.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>description:</literal>
<replaceable>freeform</replaceable>
</term>
<listitem>
<para>Description of the package. This may be several
paragraphs, and should be aimed at a Haskell programmer
who has never heard of your package before.</para>
<para>For library packages, this field is used as
prologue text by <command>setup haddock</command>
(see <xref linkend="setup-haddock"/>), and thus may
contain the same markup as &Haddock; documentation
comments.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>category:</literal>
<replaceable>freeform</replaceable>
</term>
<listitem>
<para>A classification category for future use by the
package catalogue <firstterm>Hackage</firstterm>. These
categories have not yet been specified, but the upper
levels of the module hierarchy make a good start.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>tested-with:</literal>
<replaceable>compiler list</replaceable>
</term>
<listitem>
<para>A list of compilers and versions against which the
package has been tested (or at least built).</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>build-depends:</literal>
<replaceable>package list</replaceable>
</term>
<listitem>
<para>A list of packages, possibly annotated with versions,
needed to build this one,
e.g. <literal>foo > 1.2, bar</literal>.
If no version constraint is specified, any version is
assumed to be acceptable.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>data-files:</literal>
<replaceable>filename list</replaceable>
</term>
<listitem>
<para>A list of files to be installed for run-time use by
the package. This is useful for packages that use a
large amount of static data, such as tables of values
or code templates. For details on how to find these
files at run-time, see
<xref linkend="paths-module"/>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>extra-source-files:</literal>
<replaceable>filename list</replaceable>
</term>
<listitem>
<para>A list of additional files to be included in source
distributions built with <command>setup sdist</command>
(see <xref linkend="setup-sdist"/>).</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>extra-tmp-files:</literal>
<replaceable>filename list</replaceable>
</term>
<listitem>
<para>A list of additional files or directories to be
removed by <command>setup clean</command>
(see <xref linkend="setup-clean"/>).
These would typically be additional files created by
additional hooks, such as the scheme described in
<xref linkend="system-dependent"/>.</para>
</listitem>
</varlistentry>
</variablelist>
</sect3>
<sect3 id="library">
<title>Library</title>
<para>If the package contains a library, the first stanza should
also contain the following field:</para>
<variablelist>
<varlistentry>
<term>
<literal>exposed-modules:</literal>
<replaceable>identifier list</replaceable>
(required if this package contains a library)
</term>
<listitem>
<para>A list of modules added by this package.</para>
</listitem>
</varlistentry>
</variablelist>
<para>The first stanza may also contain build information fields
(see <xref linkend="buildinfo"/>) relating to the library.</para>
</sect3>
<sect3 id="executable">
<title>Executables</title>
<para>Subsequent stanzas (if present) describe executable programs
contained in the package, using the following fields, as well as
build information fields (see <xref linkend="buildinfo"/>).</para>
<variablelist>
<varlistentry>
<term>
<literal>executable:</literal>
<replaceable>freeform</replaceable>
(required)
</term>
<listitem>
<para>The name of the executable program.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>main-is:</literal> <replaceable>filename</replaceable>
(required)
</term>
<listitem>
<para>The name of the source file containing the
<literal>Main</literal> module, relative to one of the
directories listed in <literal>hs-source-dirs</literal>.</para>
</listitem>
</varlistentry>
</variablelist>
<para>These stanzas may also contain build information fields
(see <xref linkend="buildinfo"/>) relating to the executable.</para>
</sect3>
<sect3 id="buildinfo">
<title>Build information</title>
<para>The following fields may be optionally present
in any stanza, and give information for the building
of the corresponding library or executable. See also
<xref linkend="system-dependent"/> for a way to supply
system-dependent values for these fields.</para>
<variablelist>
<varlistentry>
<term>
<literal>buildable:</literal> <replaceable>Boolean</replaceable>
(default: <literal>True</literal>)
</term>
<listitem>
<para>Is the component buildable?
Like some of the other fields below, this field is
more useful with the slightly more elaborate form of
the simple build infrastructure described in
<xref linkend="system-dependent"/>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>other-modules:</literal>
<replaceable>identifier list</replaceable>
</term>
<listitem>
<para>A list of modules used by the component
but not exposed to users. For a library component, these
would be hidden modules of the library. For an executable,
these would be auxiliary modules to be linked with the
file named in the <literal>main-is</literal> field.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>hs-source-dirs:</literal>
<replaceable>directory list</replaceable>
(default: <quote><literal>.</literal></quote>)
</term>
<listitem>
<para>Root directories for the module hierarchy.</para>
<para>For backwards compatibility, the old variant
<literal>hs-source-dir</literal> is also recognized.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>extensions:</literal>
<replaceable>identifier list</replaceable>
</term>
<listitem>
<para>A list of Haskell extensions used by every module.
Extension names are the constructors of the &Extension; type.
These determine corresponding compiler options.
In particular, <literal>CPP</literal> specifies that
Haskell source files are to be preprocessed with a
C preprocessor.</para>
<para>Extensions used only by one module may be specified
by placing a <literal>LANGUAGE</literal> pragma in the
source file affected, e.g.:</para>
<programlisting>{-# LANGUAGE CPP, MultiParamTypeClasses #-}</programlisting>
<note>
<para>GHC versions prior to 6.6 do not support the
<literal>LANGUAGE</literal> pragma.</para>
</note>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>ghc-options:</literal>
<replaceable>token list</replaceable>
</term>
<listitem>
<para>Additional options for GHC. You can often achieve
the same effect using the <literal>extensions</literal>
field, which is preferred.</para>
<para>Options required only by one module may be specified
by placing an <literal>OPTIONS_GHC</literal> pragma in the
source file affected.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>ghc-prof-options:</literal>
<replaceable>token list</replaceable>
</term>
<listitem>
<para>Additional options for GHC when the package is built
with profiling enabled.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>hugs-options:</literal>
<replaceable>token list</replaceable>
</term>
<listitem>
<para>Additional options for Hugs. You can often achieve
the same effect using the <literal>extensions</literal>
field, which is preferred.</para>
<para>Options required only by one module may be specified
by placing an <literal>OPTIONS_HUGS</literal> pragma in the
source file affected.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>nhc-options:</literal>
<replaceable>token list</replaceable>
</term>
<listitem>
<para>Additional options for nhc98. You can often achieve
the same effect using the <literal>extensions</literal>
field, which is preferred.</para>
<para>Options required only by one module may be specified
by placing an <literal>OPTIONS_NHC</literal> pragma in the
source file affected.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>includes:</literal>
<replaceable>filename list</replaceable>
</term>
<listitem>
<para>A list of header files to be included in any
compilations via C. This field applies to both header
files that are already installed on the system and to
those coming with the package to be isntalled. These files
typically contain function prototypes for foreign imports
used by the package.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>install-includes:</literal>
<replaceable>filename list</replaceable>
</term>
<listitem>
<para>A list of header files from this package to be
installed into
<literal>$(libdir)/includes</literal> when the package
is installed. Files listed in
<literal>install-includes:</literal> should be found in
one of the directories listed in
<literal>include-dirs</literal>.</para>
<para><literal>install-includes</literal> is typically
used to name header files that contain prototypes for
foreign imports used in Haskell code in this package,
for which the C implementations are also provided with
the package. Note that to include them when compiling
the package itself, they need to be listed in the
<literal>includes:</literal> field as well.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>include-dirs:</literal>
<replaceable>directory list</replaceable>
</term>
<listitem>
<para>A list of directories to search for header files,
when preprocessing with <command>c2hs</command>,
<command>hsc2hs</command>, <command>ffihugs</command>,
<command>cpphs</command> or the C preprocessor,
and also when compiling via C.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>c-sources:</literal>
<replaceable>filename list</replaceable>
</term>
<listitem>
<para>A list of C source files to be compiled
and linked with the Haskell files.</para>
<para>If you use this field, you should also name the
C files in <literal>CFILES</literal> pragmas in the
Haskell source files that use them, e.g.:
<screen>{-# CFILES dir/file1.c dir/file2.c #-}</screen>
These are ignored by the compilers, but needed by Hugs.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>extra-libraries:</literal>
<replaceable>token list</replaceable>
</term>
<listitem>
<para>A list of extra libraries to link with.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>extra-lib-dirs:</literal>
<replaceable>directory list</replaceable>
</term>
<listitem>
<para>A list of directories to search for libraries.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>cc-options:</literal>
<replaceable>token list</replaceable>
</term>
<listitem>
<para>Command-line arguments to be passed to the C compiler.
Since the arguments are compiler-dependent, this field
is more useful with the setup described in
<xref linkend="system-dependent"/>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>ld-options:</literal>
<replaceable>token list</replaceable>
</term>
<listitem>
<para>Command-line arguments to be passed to the linker.
Since the arguments are compiler-dependent, this field
is more useful with the setup described in
<xref linkend="system-dependent"/>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>frameworks:</literal>
<replaceable>token list</replaceable>
</term>
<listitem>
<para>On Darwin/MacOS X, a list of frameworks to link to.
See Apple's developer documentation for more details
on frameworks. This entry is ignored on all other
platforms.</para>
</listitem>
</varlistentry>
</variablelist>
</sect3>
</sect2>
<sect2 id="paths-module">
<title>Accessing data files from package code</title>
<para>The placement on the target system of files listed in the
<literal>data-files</literal> field varies between systems, and in
some cases one can even move packages around after installation
(see <xref linkend="prefix-independence"/>). To enable packages
to find these files in a portable way, Cabal generates a module
called <literal>Paths_</literal><replaceable>pkgname</replaceable>
(with any hyphens in <replaceable>pkgname</replaceable> replaced
by underscores) during building, so that it may be imported by
modules of the package. This module defines a function
<programlisting>getDataFileName :: FilePath -> IO FilePath</programlisting>
If the argument is a filename listed in the
<literal>data-files</literal> field, the result is the name
of the corresponding file on the system on which the program
is running.</para>
</sect2>
<sect2 id="system-dependent">
<title>System-dependent parameters</title>
<para>For some packages, especially those interfacing with C
libraries, implementation details and the build procedure depend
on the build environment. A variant of the simple build
infrastructure (the <literal>build-type</literal>
<literal>Configure</literal>) handles many such situations using
a slightly longer <filename>Setup.hs</filename>:</para>
<programlisting>
import Distribution.Simple
main = defaultMainWithHooks defaultUserHooks</programlisting>
<para>This program differs from <literal>defaultMain</literal>
in two ways:</para>
<orderedlist>
<listitem>
<para>If the package root directory contains a file called
<filename>configure</filename>, the configure step will
run that. This <filename>configure</filename> program may
be a script produced by the &Autoconf;
system, or may be hand-written. This program typically
discovers information about the system and records it for
later steps, e.g. by generating system-dependent header files
for inclusion in C source files and preprocessed Haskell
source files. (Clearly this won't work for Windows without
MSYS or Cygwin: other ideas are needed.)</para>
</listitem>
<listitem>
<para>If the package root directory contains a file called
<replaceable>package</replaceable><literal>.buildinfo</literal>
after the configuration step, subsequent steps will read it
to obtain additional settings for build information fields
(see <xref linkend="buildinfo"/>), to be merged with the
ones given in the <literal>.cabal</literal> file.
In particular, this file may be generated by the
<filename>configure</filename> script mentioned above,
allowing these settings to vary depending on the build
environment.</para>
<para>The build information file should have the following
structure:</para>
<programlisting>
<replaceable>buildinfo</replaceable>
executable: <replaceable>name</replaceable>
<replaceable>buildinfo</replaceable>
executable: <replaceable>name</replaceable>
<replaceable>buildinfo</replaceable>
...</programlisting>
<para>where each <replaceable>buildinfo</replaceable> consists
of settings of fields listed in <xref linkend="buildinfo"/>.
The first one (if present) relates to the library, while each
of the others relate to the named executable. (The names
must match the package description, but you don't have to
have entries for all of them.)</para>
</listitem>
</orderedlist>
<para>Neither of these files is required. If they are absent, this
setup script is equivalent to <literal>defaultMain</literal>.</para>
<example id="autoconf-example">
<title>Using autoconf</title>
<para>(This example is for people familiar with the &Autoconf;
tools.)</para>
<para>In the X11 package, the file <filename>configure.ac</filename>
contains:</para>
<programlisting>
AC_INIT([Haskell X11 package], [1.1], [[email protected]], [X11])
# Safety check: Ensure that we are in the correct source directory.
AC_CONFIG_SRCDIR([X11.cabal])
# Header file to place defines in
AC_CONFIG_HEADERS([include/HsX11Config.h])
# Check for X11 include paths and libraries
AC_PATH_XTRA
AC_TRY_CPP([#include <X11/Xlib.h>],,[no_x=yes])
# Build the package if we found X11 stuff
if test "$no_x" = yes
then BUILD_PACKAGE_BOOL=False
else BUILD_PACKAGE_BOOL=True
fi
AC_SUBST([BUILD_PACKAGE_BOOL])
AC_CONFIG_FILES([X11.buildinfo])
AC_OUTPUT</programlisting>
<para>Then the setup script will run the
<literal>configure</literal> script, which checks for the
presence of the X11 libraries and substitutes for variables
in the file <filename>X11.buildinfo.in</filename>:</para>
<programlisting>
buildable: @BUILD_PACKAGE_BOOL@
cc-options: @X_CFLAGS@
ld-options: @X_LIBS@</programlisting>
<para>This generates a file <filename>X11.buildinfo</filename>
supplying the parameters needed by later stages:</para>
<programlisting>
buildable: True
cc-options: -I/usr/X11R6/include
ld-options: -L/usr/X11R6/lib</programlisting>
<para>The <filename>configure</filename> script also generates
a header file <filename>include/HsX11Config.h</filename>
containing C preprocessor defines recording the results of
various tests. This file may be included by C source files
and preprocessed Haskell source files in the package.</para>
</example>
<note>
<para>Packages using these features will also need to list
additional files such as <filename>configure</filename>,
templates for <literal>.buildinfo</literal> files, files named
only in <literal>.buildinfo</literal> files, header files and
so on in the <literal>extra-source-files</literal> field,
to ensure that they are included in source distributions.
They should also list files and directories generated by
<command>configure</command> in the
<literal>extra-tmp-files</literal> field to ensure that they
are removed by <command>setup clean</command>.</para>
</note>
</sect2>
<sect2 id="complex-packages">
<title>More complex packages</title>
<para>For packages that don't fit the simple schemes described above,
you have a few options:</para>
<itemizedlist>
<listitem>
<para>You can customize the simple build infrastructure
using <firstterm>hooks</firstterm>. These allow you to
perform additional actions before and after each command is
run, and also to specify additional preprocessors. See
<literal>UserHooks</literal> in &Simple; for the details,
but note that this interface is experimental, and likely to
change in future releases.</para>
</listitem>
<listitem>
<para>You could delegate all the work to <command>make</command>,
though this is unlikely to be very portable.
Cabal supports this with a trivial setup library &Make;,
which simply parses the command line arguments and invokes
<command>make</command>. Here <filename>Setup.hs</filename>
looks like</para>
<programlisting>
import Distribution.Make
main = defaultMain</programlisting>
<para>The root directory of the package should contain
a <filename>configure</filename> script, and, after
that has run, a <filename>Makefile</filename> with a
default target that builds the package, plus targets
<literal>install</literal>, <literal>register</literal>,
<literal>unregister</literal>, <literal>clean</literal>,
<literal>dist</literal> and <literal>docs</literal>.
Some options to commands are passed through as follows:</para>
<itemizedlist>
<listitem>
<para>The <option>--with-hc-pkg</option>,
<option>--prefix</option>, <option>--bindir</option>,
<option>--libdir</option>, <option>--datadir</option>
and <option>--libexecdir</option> options to the
<literal>configure</literal> command are passed on to
the <filename>configure</filename> script.
In addition the value of the <option>--with-compiler</option>
option is passed in a <option>--with-hc</option> option.</para>
</listitem>
<listitem>
<para>the <literal>--destdir</literal> option to the
<literal>copy</literal> command becomes a setting of a
<literal>destdir</literal> variable on the invocation of
<literal>make copy</literal>. The supplied
<literal>Makefile</literal> should provide a
<literal>copy</literal> target, which will probably
look like this:
<programlisting>
copy :
$(MAKE) install prefix=$(destdir)/$(prefix) \
bindir=$(destdir)/$(bindir) \
libdir=$(destdir)/$(libdir) \
datadir=$(destdir)/$(datadir) \
libexecdir=$(destdir)/$(libexecdir)</programlisting>
</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>You can write your own setup script conforming to the
interface of <xref linkend="builders"/>, possibly using
the Cabal library for part of the work. One option is to
copy the source of <literal>Distribution.Simple</literal>,
and alter it for your needs. Good luck.</para>
</listitem>
</itemizedlist>
</sect2>
</sect1>
<sect1 id="builders">
<title>Building and installing a package</title>
<para>After you've unpacked a Cabal package, you can build it
by moving into the root directory of the package and using the
<filename>Setup.hs</filename> or <filename>Setup.lhs</filename>
script there:</para>
<cmdsynopsis>
<command>runhaskell Setup.hs</command>
<arg><replaceable>command</replaceable></arg>
<arg rep="repeat" choice="opt"><replaceable>option</replaceable></arg>
</cmdsynopsis>
<para>where <replaceable>runhaskell</replaceable> might be
<command>runhugs</command>, <command>runghc</command> or
<command>runnhc</command>. The <replaceable>command</replaceable>
argument selects a particular step in the build/install process.
You can also get a summary of the command syntax with</para>
<cmdsynopsis>
<command>runhaskell Setup.hs <option>--help</option></command>
</cmdsynopsis>
<example id="system-install-example">
<title>Building and installing a system package</title>
<screen>
runhaskell Setup.hs configure --ghc
runhaskell Setup.hs build
runhaskell Setup.hs install</screen>
<para>The first line readies the system to build the tool using GHC;
for example, it checks that GHC exists on the system. The second
line performs the actual building, while the last both copies
the build results to some permanent place and registers the
package with GHC.</para>
</example>
<example id="user-install-example">
<title>Building and installing a user package</title>
<screen>
runhaskell Setup.hs configure --ghc --user --prefix=$HOME
runhaskell Setup.hs build
runhaskell Setup.hs install</screen>
<para>The package may use packages from the user's package database
as well as the global one (<option>--user</option>), is installed
under the user's home directory (<option>--prefix</option>),
and is registered in the user's package database
(<option>--user</option>).</para>
</example>
<example id="binary-package-example">
<title>Creating a binary package</title>
<para>When creating binary packages (e.g. for RedHat or
Debian) one needs to create a tarball that can be sent to
another system for unpacking in the root directory:</para>
<screen>
runhaskell Setup.hs configure --ghc --prefix=/usr
runhaskell Setup.hs build
runhaskell Setup.hs copy --destdir=/tmp/mypkg
(cd /tmp/mypkg; tar cf - .) | gzip -9 >mypkg.tar.gz</screen>
<para>If the package contains a library, you need two additional
steps:</para>
<screen>
runhaskell Setup.hs register --gen-script
runhaskell Setup.hs unregister --gen-script</screen>
<para>This creates shell scripts <filename>register.sh</filename>
and <filename>unregister.sh</filename>, which must also be sent
to the target system. After unpacking there, the package must be
registered by running the <filename>register.sh</filename> script.
The <filename>unregister.sh</filename> script would be used
in the uninstall procedure of the package. Similar steps may
be used for creating binary packages for Windows.</para>
</example>
<para>The following options are understood by all commands:</para>
<variablelist>
<varlistentry>
<term>
<option>--help</option>, <option>-h</option> or
<option>-?</option>
</term>
<listitem>
<para>List the available options for the command.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>--verbose</option>=<replaceable>n</replaceable> or
<option>-v</option><replaceable>n</replaceable>
</term>
<listitem>
<para>Set the verbosity level (0-5). The normal level is 1;
a missing <replaceable>n</replaceable> defaults to 3.</para>
</listitem>
</varlistentry>
</variablelist>
<para>The various commands and the additional options they support
are described below. In the simple build infrastructure, any
other options will be reported as errors, except in the case of
the <literal>configure</literal> command.</para>
<sect2 id="setup-configure">
<title>setup configure</title>
<para>Prepare to build the package. Typically, this step checks
that the target platform is capable of building the package,
and discovers platform-specific features that are needed during
the build.</para>
<para>The user may also adjust the behaviour of later stages using
the options listed in the following subsections. In the simple
build infrastructure, the values supplied via these options are
recorded in a private file read by later stages.</para>
<para>If a user-supplied <filename>configure</filename>
script is run (see <xref linkend="system-dependent"/>
or <xref linkend="complex-packages"/>), it is passed the
<option>--with-hc-pkg</option>,
<option>--prefix</option>, <option>--bindir</option>,
<option>--libdir</option>, <option>--datadir</option> and
<option>--libexecdir</option> options, plus any unrecognized
options.
In addition the value of the <option>--with-compiler</option>
option is passed in a <option>--with-hc</option> option.</para>
<sect3 id="setup-configure-programs">
<title>Programs used for building</title>
<para>The following options govern the programs used to process
the source files of a package:</para>
<variablelist>
<varlistentry>
<term><option>--ghc</option> or <option>-g</option></term>
<term><option>--nhc</option> or <option>-n</option></term>
<term><option>--hugs</option></term>
<listitem>
<para>Specify which Haskell implementation to use to build
the package. At most one of these flags may be given.
If none is given, the implementation under which the setup
script was compiled or interpreted is used.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--with-compiler</option>=<replaceable>path</replaceable>
or <option>-w</option><replaceable>path</replaceable></term>
<listitem>
<para>Specify the path to a particular compiler. If given,
this must match the implementation selected above.
The default is to search for the usual name of the
selected implementation.</para>
<para>This flag also sets the default value of the
<option>--with-hc-pkg</option> option to the package tool
for this compiler.
Check the output of <literal>setup configure</literal>
to ensure that it finds the right package tool (or use
<option>--with-hc-pkg</option> explicitly).</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--with-hc-pkg</option>=<replaceable>path</replaceable></term>
<listitem>
<para>Specify the path to the package tool, e.g.
<command>ghc-pkg</command>.
The package tool must be compatible with the compiler
specified by <option>--with-compiler</option>.
If this option is omitted, the default value is determined
from the compiler selected.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--with-hscolour</option>=<replaceable>path</replaceable></term>
<listitem>
<para>Specify the path to &HsColour;.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--with-haddock</option>=<replaceable>path</replaceable></term>
<listitem>
<para>Specify the path to &Haddock;.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--with-happy</option>=<replaceable>path</replaceable></term>
<listitem>
<para>Specify the path to &Happy;.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--with-alex</option>=<replaceable>path</replaceable></term>
<listitem>
<para>Specify the path to &Alex;.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--with-hsc2hs</option>=<replaceable>path</replaceable></term>
<listitem>
<para>Specify the path to <command>hsc2hs</command>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--with-c2hs</option>=<replaceable>path</replaceable></term>
<listitem>
<para>Specify the path to &C2hs;.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--with-greencard</option>=<replaceable>path</replaceable></term>
<listitem>
<para>Specify the path to &Greencard;.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--with-cpphs</option>=<replaceable>path</replaceable></term>
<listitem>
<para>Specify the path to &Cpphs;.</para>
</listitem>
</varlistentry>
</variablelist>
</sect3>
<sect3 id="setup-configure-paths">
<title>Installation paths</title>
<para>The following options govern the location of installed files
from a package:</para>
<variablelist>
<varlistentry>
<term><option>--prefix</option>=<replaceable>dir</replaceable></term>
<listitem>
<para>The root of the installation, for example
<filename>/usr/local</filename> on a Unix system, or
<filename>C:\Program Files</filename> on a Windows system.
The other installation paths are usually subdirectories of
<replaceable>prefix</replaceable>, but they don't have
to be.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--bindir</option>=<replaceable>dir</replaceable></term>
<listitem>
<para>Executables that the user might invoke are installed here.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--libdir</option>=<replaceable>dir</replaceable></term>
<listitem>
<para>Object-code libraries are installed here.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--libsubdir</option>=<replaceable>dir</replaceable></term>
<listitem>
<para>A subdirectory of <replaceable>libdir</replaceable>
in which libraries are actually installed. For example,
in the simple build system on Unix, the default
<replaceable>libdir</replaceable> is
<filename>/usr/local/lib</filename>, and
<replaceable>libsubdir</replaceable> contains the package
identifier and compiler,
e.g. <literal>mypkg-0.2/ghc-6.4</literal>, so libraries
would be installed in
<filename>/usr/local/lib/mypkg-0.2/ghc-6.4</filename>.</para>
<para>Not all build systems make use of
<replaceable>libsubdir</replaceable>, in particular the
&Make; system does not.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--datadir</option>=<replaceable>dir</replaceable></term>
<listitem>
<para>Architecture-independent data files are installed
here.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--datasubdir</option>=<replaceable>dir</replaceable></term>
<listitem>
<para>A subdirectory of <replaceable>datadir</replaceable>
in which data files are actually installed. This option
is similar to <literal>--libsubdir</literal> in that
not all build systems make use of it.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--libexecdir</option>=<replaceable>dir</replaceable></term>
<listitem>
<para>Executables that are not expected to be invoked
directly by the user are installed here.</para>
</listitem>
</varlistentry>
</variablelist>
<sect4 id="simple-paths">
<title>Paths in the simple build system</title>
<para>For the simple build system, the following defaults
apply:</para>
<informaltable>
<tgroup cols="3">
<colspec align="left"/>
<colspec align="left"/>
<colspec align="left"/>
<thead>
<row>
<entry>Option</entry>
<entry>Windows Default</entry>
<entry>Unix Default</entry>
</row>
</thead>
<tbody>
<row>
<entry><literal>--prefix</literal></entry>
<entry><filename>C:\Program Files</filename></entry>
<entry><filename>/usr/local</filename></entry>
</row>
<row>
<entry><literal>--bindir</literal></entry>
<entry><literal>$prefix\Haskell\bin</literal></entry>
<entry><literal>$prefix/bin</literal></entry>
</row>
<row>
<entry><literal>--libdir</literal></entry>
<entry><literal>$prefix\Haskell</literal></entry>
<entry><literal>$prefix/lib</literal></entry>
</row>
<row>
<entry><literal>--libsubdir</literal> (Hugs)</entry>
<entry><literal>hugs\packages\$pkg</literal></entry>
<entry><literal>hugs/packages/$pkg</literal></entry>
</row>
<row>
<entry><literal>--libsubdir</literal> (others)</entry>
<entry><literal>$pkgid\$compiler</literal></entry>
<entry><literal>$pkgid/$compiler</literal></entry>
</row>
<row>
<entry><literal>--datadir</literal> (executable)</entry>
<entry><literal>$prefix\Haskell</literal></entry>
<entry><literal>$prefix/share</literal></entry>
</row>
<row>
<entry><literal>--datadir</literal> (library)</entry>
<entry><filename>C:\Program Files\Common Files</filename></entry>
<entry><literal>$prefix/share</literal></entry>
</row>
<row>
<entry><literal>--datasubdir</literal></entry>
<entry><literal>$pkgid</literal></entry>
<entry><literal>$pkgid</literal></entry>
</row>
<row>
<entry><literal>--libexecdir</literal></entry>
<entry><literal>$prefix\$pkgid</literal></entry>
<entry><literal>$prefix/libexec</literal></entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>The following strings are substituted into directory
names:</para>
<variablelist>
<varlistentry>
<term><literal>$prefix</literal></term>
<listitem>
<para>The value of <replaceable>prefix</replaceable></para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>$pkgid</literal></term>
<listitem>
<para>The full package identifier, e.g. <literal>pkg-0.1</literal></para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>$compiler</literal></term>
<listitem>
<para>The compiler and version, e.g. <literal>ghc-6.4.1</literal></para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>$pkg</literal></term>
<listitem>
<para>The name of the package only</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>$version</literal></term>
<listitem>
<para>The version of the package</para>
</listitem>
</varlistentry>
</variablelist>
</sect4>
<sect4 id="prefix-independence">
<title>Prefix-independence</title>
<para>On Windows, and when using Hugs on any system, it is
possible to obtain the pathname of the running program.
This means that we can construct an installable executable
package that is independent of its absolute install location.
The executable can find its auxiliary files by finding its
own path and knowing the location of the other files relative
to <replaceable>bindir</replaceable>. Prefix-independence is
particularly useful: it means the user can choose the install
location (i.e. the value of <replaceable>prefix</replaceable>)
at install-time, rather than having to bake the path into
the binary when it is built.</para>
<para>In order to achieve this, we require
that for an executable on Windows, all
of <replaceable>bindir</replaceable>,
<replaceable>libdir</replaceable>,
<replaceable>datadir</replaceable> and
<replaceable>libexecdir</replaceable> begin with
<literal>$prefix</literal>. If this is not the case
then the compiled executable will have baked in
all absolute paths.</para>
<para>The application need do nothing special to achieve
prefix-independence. If it finds any files using
<literal>getDataFileName</literal> and the other functions
provided for the purpose (see <xref linkend="paths-module"/>),
the files will be accessed relative to the location of the
current executable.</para>
<para>A library cannot (currently) be prefix-independent,
because it will be linked into an executable whose
filesystem location bears no relation to the library
package.</para>
</sect4>
</sect3>
<sect3 id="setup-configure-misc">
<title>Miscellaneous options</title>
<variablelist>
<varlistentry>
<term><option>--user</option></term>
<listitem>
<para>Allow dependencies to be satisfied by the user package
database, in addition to the global database.</para>
<para>This also implies a default of <option>--user</option>
for any subsequent <literal>install</literal> command,
as packages registered in the global database should not
depend on packages registered in a user's database.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--global</option></term>
<listitem>
<para>(default) Dependencies must be satisfied by the global
package database.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--enable-library-profiling</option> or
<option>-p</option></term>
<listitem>
<para>Request that an additional version of the library
with profiling features enabled be built and installed
(only for implementations that support profiling).</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--disable-library-profiling</option></term>
<listitem>
<para>(default) Do not generate an additional profiling
version of the library.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--enable-executable-profiling</option></term>
<listitem>
<para>Any executables generated should have profiling enabled
(only for implementations that support profiling). For this
to work, all libraries used by these executables must also
have been built with profiling support.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--disable-executable-profiling</option></term>
<listitem>
<para>(default) Do not enable profiling in generated
executables.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--enable-optimization</option> or <option>-O</option></term>
<listitem>
<para>(default) Build with optimization flags (if available).
This is appropriate for production use, taking more time
to build faster libraries and programs.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--disable-optimization</option></term>
<listitem>
<para>Build without optimization. This is suited for
development: building will be quicker, but the resulting
library or programs will be slower.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--configure-option</option>=<replaceable>str</replaceable></term>
<listitem>
<para>An extra option to an external
<filename>configure</filename> script,
if one is used (see <xref linkend="system-dependent"/>).
There can be several of these options.</para>
</listitem>
</varlistentry>
</variablelist>
<para>In the simple build infrastructure, an additional option
is recognized:</para>
<variablelist>
<varlistentry>
<term><option>--scratchdir</option>=<replaceable>dir</replaceable></term>
<listitem>
<para>Specify the directory into which the Hugs output will be
placed (default: <filename>dist/scratch</filename>).</para>
</listitem>
</varlistentry>
</variablelist>
</sect3>
</sect2>
<sect2 id="setup-build">
<title>setup build</title>
<para>Perform any preprocessing or compilation needed to make this
package ready for installation.</para>
<para>This command takes the following option:</para>
<variablelist>
<varlistentry>
<term><option>--ghc-option</option>=<replaceable>str</replaceable></term>
<listitem>
<para>An extra option to GHC, added after those specified in
the package description. There can be several of these
options.</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
<sect2 id="setup-makefile">
<title>setup makefile</title>
<para>Generate a <filename>Makefile</filename> that may be used
to compile the Haskell modules to object code.
This command is currently only supported when building libraries,
and only if the compiler is GHC.</para>
<para>The makefile command replaces part of the work done by
<literal>setup build</literal>. The sequence of commands would
typeically be:
<programlisting>
runhaskell Setup.hs makefile
make
runhaskell Setup.hs build
</programlisting>
where <literal>setup makefile</literal> does the preprocessing,
<literal>make</literal> compiles the Haskell modules, and
<literal>setup build</literal> performs any final steps, such as
building the library archives.</para>
<para>The Makefile does not use GHC's <literal>--make</literal>
flag to compile the modules, instead it compiles modules one at
a time, using dependency information generated by GHC's
<literal>-M</literal> flag. There are two reasons you might
therefore want to use <literal>setup makefile</literal>:
<itemizedlist>
<listitem>
<para>You want to build in parallel using <literal>make -j</literal>.
Currently, <literal>setup build</literal> on its own does not support
building in parallel.</para>
</listitem>
<listitem>
<para>You want to build an individual module, pass extra
flags to a compilation, or do other non-standard things that
<literal>setup build</literal> does not support.</para>
</listitem>
</itemizedlist>
</para>
<para>This command takes the following options:</para>
<variablelist>
<varlistentry>
<term><option>--file</option>=<replaceable>filename</replaceable> or
<option>-f</option> <replaceable>filename</replaceable></term>
<listitem>
<para>Specify the output file (default <filename>Makefile</filename>).</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--ghc-option</option>=<replaceable>str</replaceable></term>
<listitem>
<para>An extra option to GHC, added after those specified in
the package description. There can be several of these
options.</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
<sect2 id="setup-haddock">
<title>setup haddock</title>
<para>Build the documentation for the package using &Haddock;. By
default, only the documentation for the exposed modules is generated
(see <xref linkend="setup-haddock-executables"/>).</para>
<para>This command takes the following options:</para>
<variablelist>
<varlistentry>
<term><option>--hoogle</option></term>
<listitem>
<para>Generate a file
<filename>dist/doc/html/<replaceable>pkgid</replaceable>.txt</filename>,
which can be converted by
<ulink url="http://www.haskell.org/hoogle/">Hoogle</ulink>
into a database for searching. This is
equivalent to running &Haddock; with the <option>--hoogle</option> flag.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--html-location</option>=<replaceable>url</replaceable></term>
<listitem>
<para>Specify a template for the location of HTML documentation
for pre-requisite packages. The substitutions listed in
<xref linkend="simple-paths"/> are applied to the template
to obtain a location for each package, which will be used
by hyperlinks in the generated documentation. For example,
the following command generates links pointing at &HackageDB;
pages:</para>
<screen>setup haddock --html-location='http://hackage.haskell.org/packages/archive/$pkg/latest/doc/html'</screen>
<para>Here the argument is quoted to prevent substitution
by the shell.</para>
<para>If this option is omitted, the location for each package
is obtained using the package tool (e.g.
<command>ghc-pkg</command>).</para>
</listitem>
</varlistentry>
<varlistentry id="setup-haddock-executables">
<term><option>--executables</option></term>
<listitem>
<para>Also run &Haddock; for the modules of all the executable
programs. By default &Haddock; is run only on the exported
modules.</para>
</listitem>
</varlistentry>
<varlistentry id="setup-haddock-css">
<term><option>--css</option>=<replaceable>path</replaceable></term>
<listitem>
<para>The argument <replaceable>path</replaceable> denotes a CSS
file, which is passed to &Haddock; and used to set the style of
the generated documentation. This is only needed to override the
default style that &Haddock; uses.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--hyperlink-source</option></term>
<listitem>
<para>Generate &Haddock; documentation integrated with &HsColour;.
First, &HsColour; is run to generate colourised code.
Then &Haddock; is run to generate HTML documentation. Each
entity shown in the documentation is linked to its definition in
the colourised code.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--hscolour-css</option>=<replaceable>path</replaceable></term>
<listitem>
<para>The argument <replaceable>path</replaceable> denotes a CSS
file, which is passed to &HsColour; as in</para>
<screen>
runhaskell Setup.hs hscolour --css=<replaceable>path</replaceable></screen>
</listitem>
</varlistentry>
</variablelist>
</sect2>
<sect2 id="setup-hscolour">
<title>setup hscolour</title>
<para>Produce colourised code in HTML format using &HsColour;.
Colourised code for exported modules is put in
<filename>dist/doc/html/<replaceable>pkgid</replaceable>/src</filename>.</para>
<para>This command takes the following options:</para>
<variablelist>
<varlistentry>
<term><option>--executables</option></term>
<listitem>
<para>Also run &HsColour; on the sources of all executable
programs. Colourised code is put in
<filename>dist/doc/html/<replaceable>pkgid</replaceable>/<replaceable>executable</replaceable>/src</filename>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--css</option>=<replaceable>path</replaceable></term>
<listitem>
<para>Copy the CSS file from <replaceable>path</replaceable> to
<filename>dist/doc/html/<replaceable>pkgid</replaceable>/src/hscolour.css</filename>
for exported modules, or to
<filename>dist/doc/html/<replaceable>pkgid</replaceable>/<replaceable>executable</replaceable>/src/hscolour.css</filename>
for executable programs. The CSS file defines the actual colours
used to colourise code. Note that the
<filename>hscolour.css</filename> file is required for the code
to be actually colourised.</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
<sect2 id="setup-install">
<title>setup install</title>
<para>Copy the files into the install locations and (for library
packages) register the package with the compiler, i.e. make the
modules it contains available to programs.</para>
<para>The install locations are determined by options to
<command>setup configure</command>
(see <xref linkend="setup-configure-paths"/>).</para>
<para>This command takes the following options:</para>
<variablelist>
<varlistentry>
<term><option>--global</option></term>
<listitem>
<para>Register this package in the system-wide database.
(This is the default, unless the <option>--user</option>
option was supplied to the <literal>configure</literal>
command.)</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--user</option></term>
<listitem>
<para>Register this package in the user's local package database.
(This is the default if the <option>--user</option>
option was supplied to the <literal>configure</literal>
command.)</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
<sect2 id="setup-copy">
<title>setup copy</title>
<para>Copy the files without registering them. This command
is mainly of use to those creating binary packages.</para>
<para>This command takes the following option:</para>
<variablelist>
<varlistentry>
<term><option>--destdir</option>=<replaceable>path</replaceable></term>
<listitem>
<para>Specify the directory under which to place
installed files. If this is not given, then the root
directory is assumed.</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
<sect2 id="setup-register">
<title>setup register</title>
<para>Register this package with the compiler, i.e. make the
modules it contains available to programs. This only makes sense
for library packages. Note that the <literal>install</literal>
command incorporates this action. The main use of this
separate command is in the post-installation step for a binary
package.</para>
<para>This command takes the following options:</para>
<variablelist>
<varlistentry>
<term><option>--global</option></term>
<listitem>
<para>Register this package in the system-wide database.
(This is the default.)</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--user</option></term>
<listitem>
<para>Register this package in the user's local package
database.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--gen-script</option></term>
<listitem>
<para>Instead of registering the package, generate a script
containing commands to perform the registration. On Unix,
this file is called <filename>register.sh</filename>, on
Windows, <filename>register.bat</filename>. This script
might be included in a binary bundle, to be run after the
bundle is unpacked on the target system.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--inplace</option></term>
<listitem>
<para>Registers the package for use directly from the
build tree, without needing to install it. This can be
useful for testing: there's no need to install the package
after modifying it, just recompile and test.</para>
<para>This flag does not create a build-tree-local package
database. It still registers the package in one of the
user or global databases.</para>
<para>However, there are some caveats. It only works with
GHC (currently). It only works if your package doesn't
depend on having any supplemental files installed - plain
Haskell libraries should be fine.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--with-hc-pkg</option>=<replaceable>path</replaceable></term>
<listitem>
<para>Specify the path to the package tool, e.g.
<command>ghc-pkg</command>. This overrides the
<replaceable>hc-pkg</replaceable> tool discovered during
configure.</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
<sect2 id="setup-unregister">
<title>setup unregister</title>
<para>Deregister this package with the compiler.</para>
<para>This command takes the following options:</para>
<variablelist>
<varlistentry>
<term><option>--global</option></term>
<listitem>
<para>Deregister this package in the system-wide database.
(This is the default.)</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--user</option></term>
<listitem>
<para>Deregister this package in the user's local package
database.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--gen-script</option></term>
<listitem>
<para>Instead of deregistering the package, generate a script
containing commands to perform the deregistration. On Unix,
this file is called <filename>unregister.sh</filename>, on
Windows, <filename>unregister.bat</filename>. This script
might be included in a binary bundle, to be run on the
target system.</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
<sect2 id="setup-clean">
<title>setup clean</title>
<para>Remove any local files created during the
<literal>configure</literal>, <literal>build</literal>,
<literal>haddock</literal>, <literal>register</literal> or
<literal>unregister</literal> steps, and also any files and
directories listed in the <literal>extra-tmp-files</literal>
field.</para>
</sect2>
<sect2 id="setup-test">
<title>setup test</title>
<para>Run the test suite specified by the
<literal>runTests</literal> field of
<literal>Distribution.Simple.UserHooks</literal>. See &Simple;
for information about creating hooks and using
<literal>defaultMainWithHooks</literal>.</para>
</sect2>
<sect2 id="setup-sdist">
<title>setup sdist</title>
<para>Create a system- and compiler-independent source distribution
in a file
<filename><replaceable>package</replaceable>-<replaceable>version</replaceable>.tar.gz</filename>
in the <filename>dist</filename> subdirectory, for distribution
to package builders. When unpacked, the commands listed in this
section will be available.</para>
<para>The files placed in this distribution are the package
description file, the setup script, the sources of the modules
named in the package description file, and files named in the
<literal>license-file</literal>, <literal>main-is</literal>,
<literal>c-sources</literal>, <literal>data-files</literal> and
<literal>extra-source-files</literal> fields.</para>
<para>This command takes the following option:</para>
<variablelist>
<varlistentry>
<term><option>--snapshot</option></term>
<listitem>
<para>Append today's date
(in <replaceable>YYYYMMDD</replaceable> form) to the version
number for the generated source package. The original
package is unaffected.</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
</sect1>
<sect1 id="bugs">
<title>Known bugs and deficiencies</title>
<para>All these should be fixed in future versions:</para>
<itemizedlist>
<listitem>
<para>The scheme described in <xref linkend="system-dependent"/>
will not work on Windows without MSYS or Cygwin.</para>
</listitem>
<listitem>
<para>Cabal has some limitations both running under Hugs
and building packages for it:</para>
<itemizedlist>
<listitem>
<para>Cabal requires the latest release (Mar 2005).</para>
</listitem>
<listitem>
<para>It doesn't work with Windows.</para>
</listitem>
<listitem>
<para>There is no <literal>hugs-pkg</literal> tool.</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>Though the library runs under Nhc98, it cannot build
packages for Nhc98.</para>
</listitem>
</itemizedlist>
<para>Please report any other flaws to
<email>[email protected]</email>.</para>
</sect1>
</article>
|
