This page is also found on the new GitHub wiki.
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.
Very Stable Command-line interfaces
- ./setup configure
- --ghc, --hugs
- ./setup build
- ./setup install
Stable Command-line interfaces
Functions & Types
Very Stable API
- defaultMainWithHooks defaultUserHooks
- but regular defaultMainWithHooks isn't stable since userHooks changes.
Maybe Stable API
- UserHooks? The hooks api will change in the future.
- Distribution.* is mostly declarative information about packages and is somewhat stable.
To what extent should the rest of the API be stabalized? Sometimes utility functions are useful to layered tools, either to find out where stuff is in the build tree, or to compute something like the package name, given the package identifier.
- Various utility functions
- Everything under Distribution.Simple.* has no stability guarantee
- 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, ie 00-index.tar.gz, 01-index.tar.gz etc.