The sole requirement of an Cabal package is that it should contain,
in the root of its file structure, (a) a package description file Setup.description,
and (b) a setup script, Setup.lhs.
This section
specifies the syntax of the package description, and the command-line interface for the setup script.

The rest of the lines are optional. Any fields the system
doesn't understand will be ignored (to allow addition of fields at a
later date, or to allow Setup script authors to provide their own
fields). Each field must begin with "Field-Name:".

Lines beginning with "--" will be considered comments and
ignored.

Each field must begin with "Field-Name:". In order to allow for
long fields, any line that begins with whitespace will be considered
part of the previous field.

As given, there should be no reason to have completely empty
lines (except perhaps for the last line in the file). In the future,
if there is need to add more records, they will be separated by at
least one completely empty line.

For the Cabal-provided simple build infrastructure, the package
description fields and syntax are given in Section 5.2.

The command ./Setup.lhs configure
prepares to build the package. For sophisticated packages,
the configure step may perform elaborate checks, to gather
information about the target system. It may write a file to
record its results, but the name and format of this file are
not part of the specification.

All flags are optional. The flags are these:

--with-compiler=path,
--ghc,
--nhc,
--hugs:
specifies which compiler to use. At most one of the value of these flags may be specified.
The configure step checks
that the compiler is available, in a sufficiently up-to-date form for the package, and that the package
expects to work with that compiler. If the compiler name
is not specified, Setup.lhs will choose one; some packages will come with one compiler baked in.

--prefix=path: specifies where the installed files
for the package should be installed (ie the location of the files themselves). Typically on Unix this will be /usr/local and
on Windows it will be Program Files. The setup script will use a sensible default
(often platform-specific) if the flag is not specified.

Unrecognized flags are errors in the default build system, but may be meaningful to wrapped make-based systems (for instance). Therefore, the provided command-line parser will pass unrecognized command-line flags on to the wrapped system.

It is OK for these flags to be "baked into" the compiled
tool. In particular, the build system may bake the
installation path into the compiled files. There is no
provision for changing these baked-into values after
configuration.

The command ./Setup.lhs install
copies files from the built package to the right location for
installed files, specified in the configure step. Then it
registers the new package with the compiler, using the
hc-pkg command.

--install-prefix=path:
specifies where the installed files for the package should
be installed (ie the location of the files themselves).
It has three effects. First, it over-rides the
--prefix flag specified in the
configure step, providing an alternative
location. Second, it does not call hc-pkg to register
the package. Instead, third, it creates an installed
package description file,
installed-pkg-descr, which can later
be fed to hc-pkg.

--user: if present, this flag is
passed to hc-pkg so that the package is registed for the
current user only. This flag has no effect if
--install-prefix is used, because in
that case hc-pkg is not called.

--global: if present, this flag is
passed to hc-pkg so that the package is registed
globally (this is the default if neither
--user or --global are
given). This flag has no effect if
--install-prefix is used, because in
that case hc-pkg is not called.

The reason for the --install-prefix
flag is that Roland RPM wants to create an exact installation
tree, all ready to bundle up for the target machine,
but in a temporary location. He cannot
use this location for --prefix in the
configure step, because that might bake
the wrong path into some compiled files. Nor does he want to
register this temporary tree with the compiler on his
machine. Instead, he bundles up the temporary installation
tree, plus the installed-pkg-descr, and
ships them all to the target machine. When they are installed
there, the post-installation script runs
hc-pkg on the
installed-pkg-descr file.

Note that there is no uninstall
command in the setup script. While it would be easy enough to
implement in the simple build infrastructure, we don't want to
require make-based build systems to implement make
uninstall, which is fairly non-standard and
difficult to get right. In the majority of cases, we expect
libraries to be installed via a package manager (eg. RPM,
Debian APT), which already provide uninstallation
services.

System packagers, such as Peter Packager or Donald
Debian, will run the configure and build steps just like Bob
and Sam. A that point, Donald will say

./Setup.lhs install --install-prefix=/tmp/donald

to construct a ready-to-zip tree of all the
installed files, plus a file
installed-pkg-descr that describes the
installed package. He arranges to deliver both these
components to the target machine, and then feed
installed-pkg-descr to hc-pkg on the
target machine.

The file installed-pkg-descr also
contains information he needs for building his Debian
distribution, namely the package name, version, and (exact)
dependencies.

We expect there to be additional tools to help System
Packagers to prepare the materials necessary to build their
packages from a source distribution. For example, an RPM tool
could take a Haskell package source distribution and build an
initial .spec file with as many of the
fields as possible filled in automatically. In most cases
some intervention by the System Packager will be necessary;
for example platform-specific dependencies may need to be
specified.

After Peter has constructed the package, Isabella can
install it in a manner she is comfortable with.