6. Stability of Cabal interfaces

The Cabal library and related infrastructure is still under active
development. New features are being added and limitations and bugs are
being fixed. This requires internal changes and often user visible
changes as well. We therefor cannot promise complete future-proof
stability, at least not without halting all development work.

This section documents the aspects of the Cabal interface that we can
promise to keep stable and which bits are subject to change.

6.1. Cabal file format

This is backwards compatible and mostly forwards compatible.
New fields can be added without breaking older versions of Cabal.
Fields can be deprecated without breaking older packages.

6.2. Command-line interface

6.2.1. Very Stable Command-line interfaces

./setup configure

--prefix

--user

--ghc, --hugs

--verbose

--prefix

./setup build

./setup install

./setup register

./setup copy

6.2.2. Stable Command-line interfaces

6.2.3. Unstable command-line

6.3. Functions and Types

The Cabal library follows the Package
Versioning Policy. This means that within a stable major
release, for example 1.2.x, there will be no incompatible API changes.
But minor versions increments, for example 1.2.3, indicate compatible
API additions.

The Package Versioning Policy does not require any API guarantees
between major releases, for example between 1.2.x and 1.4.x. In
practise of course not everything changes between major releases. Some
parts of the API are more prone to change than others. The rest of this
section gives some informal advice on what level of API stability you
can expect between major releases.

6.3.1. Very Stable API

6.3.2. Semi-stable API

Distribution.*
is mostly declarative information about packages and is somewhat
stable.

6.3.3. Unstable API

Everything under
Distribution.Simple.*
has no stability guarantee.

6.4. Hackage

The index format is a partly stable interface. It consists of a tar.gz
file that contains directories with .cabal files
in. In future it may contain more kinds of files so do not assume every
file is a .cabal file. Incompatible revisions to
the format would involve bumping the name of the index file, i.e.,
00-index.tar.gz,
01-index.tar.gz etc.