doc/misc.rst

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