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