This defines the data structure for the .cabal file format. There are
several parts to this structure. It has top level info and then Library,
Executable, TestSuite, and Benchmark sections each of which have
associated BuildInfo data that's used to build the library, exe, test, or
benchmark. To further complicate things there is both a PackageDescription
and a GenericPackageDescription. This distinction relates to cabal
configurations. When we initially read a .cabal file we get a
GenericPackageDescription which has all the conditional sections.
Before actually building a package we have to decide
on each conditional. Once we've done that we get a PackageDescription.
It was done this way initially to avoid breaking too much stuff when the
feature was introduced. It could probably do with being rationalised at some
point to make it simpler.

Package descriptions

This data type is the internal representation of the file pkg.cabal.
It contains two kinds of information about the package: information
which is needed for all packages, such as the package name and version, and
information which is needed for the simple build system only, such as
the compiler options and library name.

The version of the Cabal spec that this package description uses.
For historical reasons this is specified with a version range but
only ranges of the form >= v make sense. We are in the process of
transitioning to specifying just a single version, not a range.

The version of the Cabal spec that this package should be interpreted
against.

Historically we used a version range but we are switching to using a single
version. Currently we accept either. This function converts into a single
version by ignoring upper bounds in the version range.

a package that uses an unknown build type cannot actually
be built. Doing it this way rather than just giving a
parse error means we get better error messages and allows
you to inspect the rest of the package description.

Test interface "exitcode-stdio-1.0". The test-suite takes the form
of an executable. It returns a zero exit code for success, non-zero for
failure. The stdout and stderr channels may be logged. It takes no
command line parameters and nothing on stdin.

Benchmark interface "exitcode-stdio-1.0". The benchmark
takes the form of an executable. It returns a zero exit code
for success, non-zero for failure. The stdout and stderr
channels may be logged. It takes no command line parameters
and nothing on stdin.

A FlagAssignment is a total or partial mapping of FlagNames to
Bool flag values. It represents the flags chosen by the user or
discovered during configuration. For example --flags=foo --flags=-bar
becomes [(foo, True), (bar, False)]

Source repositories

When specifying a repo it is useful to know the meaning or intention of the
information as doing so enables automation. There are two obvious common
purposes: one is to find the repo for the latest development version, the
other is to find the repo for this specific release. The ReopKind
specifies which one we mean (or another custom one).

A package can specify one or the other kind or both. Most will specify just
a head repo but some may want to specify a repo to reconstruct the sources
for this package release.

The required information is the RepoType which tells us if it's using
Darcs, Git for example. The repoLocation and other details are
interpreted according to the repo type.

CVS can put multiple "modules" on one server and requires a
module name in addition to the location to identify a particular repo.
Logically this is part of the location but unfortunately has to be
specified separately. This field is required for the CVSRepoType and
should not be given otherwise.

The name or identifier of the branch, if any. Many source control
systems have the notion of multiple branches in a repo that exist in the
same location. For example Git and CVS use this while systems like
Darcs use different locations for different branches. This field is
optional but should be used if necessary to identify the sources,
especially for the RepoThis repo kind.

Some repositories contain multiple projects in different subdirectories
This field specifies the subdirectory where this packages sources can be
found, eg the subdirectory containing the .cabal file. It is interpreted
relative to the root of the repository. This field is optional. If not
given the default is "." ie no subdirectory.