doc/cabal-interface-stability.rst

   1 Stability of Cabal interfaces
   2 =============================
   3
   4 The Cabal library and related infrastructure is still under active
   5 development. New features are being added and limitations and bugs are
   6 being fixed. This requires internal changes and often user visible
   7 changes as well. We therefore cannot promise complete future-proof
   8 stability, at least not without halting all development work.
   9
  10 This section documents the aspects of the Cabal interface that we can
  11 promise to keep stable and which bits are subject to change.
  12
  13 Cabal file format
  14 -----------------
  15
  16 This is backwards compatible and mostly forwards compatible. New fields
  17 can be added without breaking older versions of Cabal. Fields can be
  18 deprecated without breaking older packages.
  19
  20 Command-line interface
  21 ----------------------
  22
  23 Very Stable Command-line interfaces
  24 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  25
  26 -  ``./setup configure``
  27 -  ``--prefix``
  28 -  ``--user``
  29 -  ``--ghc``, ``--uhc``
  30 -  ``--verbose``
  31 -  ``--prefix``
  32
  33 -  ``./setup build``
  34 -  ``./setup install``
  35 -  ``./setup register``
  36 -  ``./setup copy``
  37
  38 Stable Command-line interfaces
  39 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  40
  41 Unstable command-line
  42 ~~~~~~~~~~~~~~~~~~~~~
  43
  44 Functions and Types
  45 -------------------
  46
  47 The Cabal library follows the `Package Versioning Policy`_.
  48 This means that within a stable major release, for example 1.2.x, there
  49 will be no incompatible API changes. But minor versions increments, for
  50 example 1.2.3, indicate compatible API additions.
  51
  52 The Package Versioning Policy does not require any API guarantees
  53 between major releases, for example between 1.2.x and 1.4.x. In practice
  54 of course not everything changes between major releases. Some parts of
  55 the API are more prone to change than others. The rest of this section
  56 gives some informal advice on what level of API stability you can expect
  57 between major releases.
  58
  59 Very Stable API
  60 ~~~~~~~~~~~~~~~
  61
  62 -  ``defaultMain``
  63
  64 -  ``defaultMainWithHooks defaultUserHooks``
  65
  66 But regular ``defaultMainWithHooks`` isn't stable since ``UserHooks``
  67 changes.
  68
  69 Semi-stable API
  70 ~~~~~~~~~~~~~~~
  71
  72 -  ``UserHooks`` The hooks API will change in the future
  73
  74 -  ``Distribution.*`` is mostly declarative information about packages
  75    and is somewhat stable.
  76
  77 Unstable API
  78 ~~~~~~~~~~~~
  79
  80 Everything under ``Distribution.Simple.*`` has no stability guarantee.
  81
  82 Hackage
  83 -------
  84
  85 The index format is a partly stable interface. It consists of a tar.gz
  86 file that contains directories with ``.cabal`` files in. In future it
  87 may contain more kinds of files so do not assume every file is a
  88 ``.cabal`` file. Incompatible revisions to the format would involve
  89 bumping the name of the index file, i.e., ``00-index.tar.gz``,
  90 ``01-index.tar.gz`` etc.
  91
  92
  93 .. include:: references.inc