This page is also found on [https://github.com/haskell/cabal/wiki/Stable-interfaces the new GitHub wiki].

= Stable Interfaces =
[[PageOutline]]

== Cabal ==

== 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.

== Command-line interface ==
==== Very Stable Command-line interfaces ====
 * ./setup configure
   * --prefix
   * --user
   * --ghc, --hugs
   * --verbose
 * ./setup build
 * ./setup install

==== Stable Command-line interfaces ====

==== Unstable command-line ====

=== Functions & Types ===

==== Very Stable API ====
 * defaultMain
 * 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.

==== Unstable API ====
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

== Hackage ==
 * 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.