doc/file-format-changelog.rst

   1 .. _spec-history:
   2
   3 ==================================================
   4  Package Description Format Specification History
   5 ==================================================
   6
   7 :ref:`pkg-desc` need to specify the version of the
   8 specification they need to be interpreted in via the
   9 :pkg-field:`cabal-version` declaration. The following list describes
  10 changes that occurred in each version of the cabal specification
  11 relative to the respective preceding *published* version.
  12
  13 .. note::
  14
  15     The sequence of specification version numbers is *not*
  16     contiguous because it's synchronised with the version of the
  17     ``Cabal`` library. As a consequence, only *even* versions are
  18     considered proper published versions of the specification as *odd*
  19     versions of the ``Cabal`` library denote unreleased development
  20     branches which have no stability guarantee.
  21
  22 ``cabal-version: 3.8``
  23 ----------------------
  24
  25 * Added field ``code-generators`` to :pkg-section:`test-suite` stanzas. This
  26   enumerates executabes (possibly brought into scope by  :pkg-field:`build-tool-depends`) that are run after all other
  27   preprocessors. These executables are invoked with a target dir for
  28   output, a sequence of all source directories with source files of
  29   local lib components that the given test stanza depends on, and
  30   following a double dash, all options cabal would pass to ghc for a
  31   build. They are expected to output a newline-separated list of
  32   generated modules which have been written to the targetdir. This can
  33   be used for driving doctests and other discover-style tests generated
  34   from source code.
  35
  36 * Added fields :pkg-field:`extra-libraries-static` and
  37   :pkg-field:`extra-lib-dirs-static` to allow Haskell libraries to remember
  38   linker flags needed for fully static linking of system libraries into
  39   executables.
  40   The existing field :pkg-field:`pkgconfig-depends` can used to append
  41   the relevant output of ``pkg-config --libs --static`` to these new fields
  42   automatically.
  43   When :pkg-field:`extra-libraries-static` is not given, it defaults to
  44   :pkg-field:`extra-libraries`.
  45   When :pkg-field:`extra-lib-dirs-static` is not given, it defaults to
  46   :pkg-field:`extra-lib-dirs`.
  47
  48 * Wildcard matching has been slightly expanded. Matches are now
  49   allowed of the form ``foo/**/literalFile``. Prior, double-star
  50   wildcards required the trailing filename itself be a wildcard.
  51
  52 * Allow the omission of the `type` field in `test-suite` and `benchmark` stanzas
  53   when the type can be inferred by the presence of `main-is` or `test-module`.
  54
  55 * License fields use identifiers from SPDX License List version
  56   ``3.16 2022-02-06``
  57
  58 ``cabal-version: 3.6``
  59 ----------------------
  60
  61 * License fields use identifiers from SPDX License List version
  62   ``3.10 2020-08-03``
  63
  64 * Add :pkg-field:`hsc2hs-options`
  65
  66 ``cabal-version: 3.4``
  67 ----------------------
  68
  69
  70 * License fields use identifiers from SPDX License List version
  71   ``3.9 2020-05-15``
  72
  73 * Dependencies to sublibraries have to be specified explicitly,
  74   even for current package.
  75   This way you can have an internal library with the same
  76   name as some external dependency.
  77
  78 * Remove ``-any`` and ``-none`` syntax for version ranges
  79   Use ``>=0`` and ``<0`` respectively.
  80
  81 * :pkg-field:`default-language` is optional.
  82   The Default value is to use the compiler's default language.
  83
  84 * :pkg-field:`mixins` field allow specifying a sublibrary.
  85
  86 ``cabal-version: 3.0``
  87 ----------------------
  88
  89 * Added the :pkg-field:`extra-dynamic-library-flavours` field to specify non-trivial
  90   variants of dynamic flavours. It is :pkg-field:`extra-library-flavours` but for
  91   shared libraries. Mainly useful for GHC's RTS library.
  92
  93 * Free text fields (e.g. :pkg-field:`description`) preserve empty lines
  94   and indentation. In other words, you don't need to add dots for blank lines.
  95
  96 * License fields use identifiers from SPDX License List version
  97   ``3.6 2019-07-10``
  98
  99 * Remove deprecated ``hs-source-dir``, :pkg-field:`extensions` and
 100   :pkg-field:`build-tools` fields.
 101
 102 * Common stanzas are now allowed also in the beginning of conditional
 103   sections.  In other words, the following is valid
 104
 105     ::
 106
 107         library
 108             import deps
 109
 110             if flag(foo)
 111                 import foo-deps
 112
 113 * Allow redundant leading or trailing commas in package fields with
 114   optional commas, such as :pkg-field:`library:exposed-modules`
 115
 116 * Require fields with optional commas to consistently omit or place
 117   commas between elements.
 118
 119 * Changed the behavior of :pkg-field:`extra-bundled-libraries` field. The naming convention
 120   of dynamic library files (e.g. generated by a custom build script) has
 121   changed. For library names prefixed with "C", the dynamic library file
 122   name(s) must be of the form `lib<library-name>.<dyn-library-extension>*`
 123   instead of the old `libC<library-name>-ghc<ghc-flavour><ghc-version>.<dyn-library-extension>`
 124
 125 * New set-notation syntax for ``==`` and ``^>=`` operators, see
 126   :pkg-field:`build-depends` field documentation for examples.
 127
 128 * Allow more whitespace in :pkg-field:`mixins` field
 129
 130 * Wildcards are disallowed in :pkg-field:`pkgconfig-depends`,
 131   Yet the pkgconfig format is relaxed to accept e.g. versions like ``1.1.0h``.
 132
 133 * New :pkg-field:`autogen-includes` for specifying :pkg-field:`install-includes`
 134   which are autogenerated (e.g. by a ``configure`` script).
 135
 136 * New :pkg-field:`asm-sources` and :pkg-field:`asm-options` fields
 137   added for supporting bundled foreign routines implemented in
 138   assembler.
 139
 140 * New :pkg-field:`cmm-sources` and :pkg-field:`cmm-options` fields
 141   added for supporting bundled foreign primops implemented in
 142   C--.
 143
 144 ``cabal-version: 2.4``
 145 ----------------------
 146
 147 * Wildcard matching has been expanded. All previous wildcard
 148   expressions are still valid; some will match strictly more files
 149   than before. Specifically:
 150
 151   * Double-star (``**``) wildcards are now accepted for recursive
 152     matching immediately before the final slash; they must be followed
 153     by a filename wildcard (e.g., ``foo/**/*.html`` is valid;
 154     ``foo/**/bar/*.html`` and ``foo/**/**/*.html``,
 155     ``foo/**/bar.html`` are all invalid). As ``**`` was an error in
 156     globs before, this does not affect any existing ``.cabal`` files
 157     that previously worked.
 158
 159   * Wildcards now match when the pattern's extensions form a suffix of
 160     the candidate file's extension, rather than requiring strict
 161     equality (e.g., previously ``*.html`` did not match
 162     ``foo.en.html``, but now it does).
 163
 164 * License fields use identifiers from SPDX License List version
 165   ``3.2 2018-07-10``
 166
 167
 168 ``cabal-version: 2.2``
 169 ----------------------
 170
 171 * New :pkg-section:`common` stanzas and :pkg-field:`import`
 172   pseudo-field added.
 173
 174 * New :pkg-field:`library:virtual-modules` field added.
 175
 176 * New :pkg-field:`cxx-sources` and :pkg-field:`cxx-options` fields
 177   added for supporting bundled foreign routines implemented in C++.
 178
 179 * New :pkg-field:`extra-bundled-libraries` field for specifying
 180   additional custom library objects to be installed.
 181
 182 * Extended ``if`` control structure with support for ``elif`` keyword.
 183
 184 * Changed default rules of :pkg-field:`build-type` field to infer
 185   "build-type:" for "Simple"/"Custom" automatically.
 186
 187 * :pkg-field:`license` field syntax changed to require SPDX
 188   expression syntax (using SPDX license list version ``3.0 2017-12-28``).
 189
 190 * Allow redundant leading or trailing commas in package fields (which
 191   require commas) such as :pkg-field:`build-depends`.
 192
 193
 194 ``cabal-version: 2.0``
 195 ----------------------
 196
 197 * New :pkg-field:`library:signatures` and :pkg-field:`mixins` fields
 198   added for supporting :ref:`Backpack`.
 199
 200 * New :pkg-field:`build-tool-depends` field added for adding
 201   build-time dependencies of executable components.
 202
 203 * New :pkg-field:`custom-setup:autogen-modules` field added for declaring modules
 204   which are generated at build time.
 205
 206 * Support for new PVP_ caret-style version operator (``^>=``) added to
 207   :pkg-field:`build-depends`.
 208
 209 * Add support for new :pkg-section:`foreign-library` stanza.
 210
 211 * Add support for :ref:`internal library stanzas <sublibs>`.
 212
 213 * New CPP Macro ``CURRENT_PACKAGE_VERSION``.
 214
 215 ``cabal-version: 1.24``
 216 -----------------------
 217
 218 * New :pkg-section:`custom-setup` stanza and
 219   :pkg-field:`custom-setup:setup-depends` field added for specifying dependencies
 220   of custom ``Setup.hs`` scripts.
 221
 222 * CPP Macros ``VERSION_$pkgname`` and ``MIN_VERSION_$pkgname`` are now
 223   also generated for the current package.
 224
 225 * New CPP Macros ``CURRENT_COMPONENT_ID`` and ``CURRENT_PACKAGE_KEY``.
 226
 227 * New :pkg-field:`extra-framework-dirs` field added for specifying
 228   extra locations to find OS X frameworks.
 229
 230 ``cabal-version: 1.22``
 231 -----------------------
 232
 233 * New :pkg-field:`library:reexported-modules` field.
 234
 235 * Support for ``-none`` version constraint added to
 236   :pkg-field:`build-depends`.
 237
 238 * New :pkg-field:`license` type ``ISC`` added.
 239
 240 ``cabal-version: 1.20``
 241 -----------------------
 242
 243 * Add support for new :pkg-field:`license-files` field for declaring
 244   multiple license documents.
 245
 246 * New CPP Macro ``MIN_TOOL_VERSION_$buildtool``.
 247
 248 * New :pkg-field:`license` types ``BSD2`` and ``MPL-2.0`` added.
 249
 250 ``cabal-version: 1.18``
 251 -----------------------
 252
 253 * Add support for new :pkg-field:`extra-doc-files` field for
 254   specifying extra file assets referenced by the Haddock
 255   documentation.
 256
 257 * New :pkg-field:`license` type ``AGPL`` and ``AGPL-3`` added.
 258
 259 * Add support for specifying a C/C++/obj-C source file in
 260   :pkg-field:`executable:main-is` field.
 261
 262 * Add ``getSysconfDir`` operation to ``Paths_`` API.
 263
 264 ``cabal-version: 1.16``
 265 -----------------------
 266
 267 .. todo::
 268
 269    this needs to be researched; there were only few changes between
 270    1.12 and 1.18;
 271
 272 ``cabal-version: 1.12``
 273 -----------------------
 274
 275 * Change syntax of :pkg-field:`cabal-version` to support the new recommended
 276   ``cabal-version: x.y`` style
 277
 278
 279
 280 .. include:: references.inc