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 * New :pkg-field:`library:visibility` for exposing sublibraries.
  90
  91 * New ``pkg:lib`` and ``pkg:{lib1,lib2}`` syntax in :pkg-field:`build-depends`
  92   for depending on public sublibraries from other packages.
  93
  94 * Added the :pkg-field:`extra-dynamic-library-flavours` field to specify non-trivial
  95   variants of dynamic flavours. It is :pkg-field:`extra-library-flavours` but for
  96   shared libraries. Mainly useful for GHC's RTS library.
  97
  98 * Free text fields (e.g. :pkg-field:`description`) preserve empty lines
  99   and indentation. In other words, you don't need to add dots for blank lines.
 100
 101 * License fields use identifiers from SPDX License List version
 102   ``3.6 2019-07-10``
 103
 104 * Remove deprecated ``hs-source-dir``, :pkg-field:`extensions` and
 105   :pkg-field:`build-tools` fields.
 106
 107 * Common stanzas are now allowed also in the beginning of conditional
 108   sections.  In other words, the following is valid
 109
 110     ::
 111
 112         library
 113             import deps
 114
 115             if flag(foo)
 116                 import foo-deps
 117
 118 * Allow redundant leading or trailing commas in package fields with
 119   optional commas, such as :pkg-field:`library:exposed-modules`
 120
 121 * Require fields with optional commas to consistently omit or place
 122   commas between elements.
 123
 124 * Changed the behavior of :pkg-field:`extra-bundled-libraries` field. The naming convention
 125   of dynamic library files (e.g. generated by a custom build script) has
 126   changed. For library names prefixed with "C", the dynamic library file
 127   name(s) must be of the form `lib<library-name>.<dyn-library-extension>*`
 128   instead of the old `libC<library-name>-ghc<ghc-flavour><ghc-version>.<dyn-library-extension>`
 129
 130 * New set-notation syntax for ``==`` and ``^>=`` operators, see
 131   :pkg-field:`build-depends` field documentation for examples.
 132
 133 * Allow more whitespace in :pkg-field:`mixins` field
 134
 135 * Wildcards are disallowed in :pkg-field:`pkgconfig-depends`,
 136   Yet the pkgconfig format is relaxed to accept e.g. versions like ``1.1.0h``.
 137
 138 * New :pkg-field:`autogen-includes` for specifying :pkg-field:`install-includes`
 139   which are autogenerated (e.g. by a ``configure`` script).
 140
 141 * New :pkg-field:`asm-sources` and :pkg-field:`asm-options` fields
 142   added for supporting bundled foreign routines implemented in
 143   assembler.
 144
 145 * New :pkg-field:`cmm-sources` and :pkg-field:`cmm-options` fields
 146   added for supporting bundled foreign primops implemented in
 147   C--.
 148
 149 ``cabal-version: 2.4``
 150 ----------------------
 151
 152 * Wildcard matching has been expanded. All previous wildcard
 153   expressions are still valid; some will match strictly more files
 154   than before. Specifically:
 155
 156   * Double-star (``**``) wildcards are now accepted for recursive
 157     matching immediately before the final slash; they must be followed
 158     by a filename wildcard (e.g., ``foo/**/*.html`` is valid;
 159     ``foo/**/bar/*.html`` and ``foo/**/**/*.html``,
 160     ``foo/**/bar.html`` are all invalid). As ``**`` was an error in
 161     globs before, this does not affect any existing ``.cabal`` files
 162     that previously worked.
 163
 164   * Wildcards now match when the pattern's extensions form a suffix of
 165     the candidate file's extension, rather than requiring strict
 166     equality (e.g., previously ``*.html`` did not match
 167     ``foo.en.html``, but now it does).
 168
 169 * License fields use identifiers from SPDX License List version
 170   ``3.2 2018-07-10``
 171
 172
 173 ``cabal-version: 2.2``
 174 ----------------------
 175
 176 * New :pkg-section:`common` stanzas and :pkg-field:`import`
 177   pseudo-field added.
 178
 179 * New :pkg-field:`library:virtual-modules` field added.
 180
 181 * New :pkg-field:`cxx-sources` and :pkg-field:`cxx-options` fields
 182   added for supporting bundled foreign routines implemented in C++.
 183
 184 * New :pkg-field:`extra-bundled-libraries` field for specifying
 185   additional custom library objects to be installed.
 186
 187 * Extended ``if`` control structure with support for ``elif`` keyword.
 188
 189 * Changed default rules of :pkg-field:`build-type` field to infer
 190   "build-type:" for "Simple"/"Custom" automatically.
 191
 192 * :pkg-field:`license` field syntax changed to require SPDX
 193   expression syntax (using SPDX license list version ``3.0 2017-12-28``).
 194
 195 * Allow redundant leading or trailing commas in package fields (which
 196   require commas) such as :pkg-field:`build-depends`.
 197
 198
 199 ``cabal-version: 2.0``
 200 ----------------------
 201
 202 * New :pkg-field:`library:signatures` and :pkg-field:`mixins` fields
 203   added for supporting :ref:`Backpack`.
 204
 205 * New :pkg-field:`build-tool-depends` field added for adding
 206   build-time dependencies of executable components.
 207
 208 * New :pkg-field:`custom-setup:autogen-modules` field added for declaring modules
 209   which are generated at build time.
 210
 211 * Support for new PVP_ caret-style version operator (``^>=``) added to
 212   :pkg-field:`build-depends`.
 213
 214 * Add support for new :pkg-section:`foreign-library` stanza.
 215
 216 * Add support for :ref:`internal library stanzas <sublibs>`.
 217
 218 * New CPP Macro ``CURRENT_PACKAGE_VERSION``.
 219
 220 ``cabal-version: 1.24``
 221 -----------------------
 222
 223 * New :pkg-section:`custom-setup` stanza and
 224   :pkg-field:`custom-setup:setup-depends` field added for specifying dependencies
 225   of custom ``Setup.hs`` scripts.
 226
 227 * CPP Macros ``VERSION_$pkgname`` and ``MIN_VERSION_$pkgname`` are now
 228   also generated for the current package.
 229
 230 * New CPP Macros ``CURRENT_COMPONENT_ID`` and ``CURRENT_PACKAGE_KEY``.
 231
 232 * New :pkg-field:`extra-framework-dirs` field added for specifying
 233   extra locations to find OS X frameworks.
 234
 235 ``cabal-version: 1.22``
 236 -----------------------
 237
 238 * New :pkg-field:`library:reexported-modules` field.
 239
 240 * Support for ``-none`` version constraint added to
 241   :pkg-field:`build-depends`.
 242
 243 * New :pkg-field:`license` type ``ISC`` added.
 244
 245 ``cabal-version: 1.20``
 246 -----------------------
 247
 248 * Add support for new :pkg-field:`license-files` field for declaring
 249   multiple license documents.
 250
 251 * New CPP Macro ``MIN_TOOL_VERSION_$buildtool``.
 252
 253 * New :pkg-field:`license` types ``BSD2`` and ``MPL-2.0`` added.
 254
 255 ``cabal-version: 1.18``
 256 -----------------------
 257
 258 * Add support for new :pkg-field:`extra-doc-files` field for
 259   specifying extra file assets referenced by the Haddock
 260   documentation.
 261
 262 * New :pkg-field:`license` type ``AGPL`` and ``AGPL-3`` added.
 263
 264 * Add support for specifying a C/C++/obj-C source file in
 265   :pkg-field:`executable:main-is` field.
 266
 267 * Add ``getSysconfDir`` operation to ``Paths_`` API.
 268
 269 ``cabal-version: 1.16``
 270 -----------------------
 271
 272 .. todo::
 273
 274    this needs to be researched; there were only few changes between
 275    1.12 and 1.18;
 276
 277 ``cabal-version: 1.12``
 278 -----------------------
 279
 280 * Change syntax of :pkg-field:`cabal-version` to support the new recommended
 281   ``cabal-version: x.y`` style
 282
 283
 284
 285 .. include:: references.inc