This page is also found on  the new GitHub wiki.

Stable Interfaces

  1. Stable Interfaces
    1. Cabal
    2. Cabal file format
    3. Command-line interface
        1. Very Stable Command-line interfaces
        2. Stable Command-line interfaces
        3. Unstable command-line
      2. Functions & Types
        1. Very Stable API
        2. Maybe Stable API
        3. Unstable API
    4. Hackage

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.