7. Package Description Format Specification History

Package descriptions need to specify the version of the specification they need to be interpreted in via the cabal-version declaration. The following list describes changes that occurred in each version of the cabal specification relative to the respective preceding published version.


The sequence of specification version numbers is not contiguous because it’s synchronised with the version of the Cabal library. As a consequence, only even versions are considered proper published versions of the specification as odd versions of the Cabal library denote unreleased development branches which have no stability guarantee.

7.1. cabal-version: 2.4

  • Wildcard matching has been expanded. All previous wildcard expressions are still valid; some will match strictly more files than before. Specifically:
    • Double-star (**) wildcards are now accepted for recursive matching immediately before the final slash; they must be followed by a filename wildcard (e.g., foo/**/*.html is valid; foo/**/bar/*.html and foo/**/**/*.html, foo/**/bar.html are all invalid). As ** was an error in globs before, this does not affect any existing .cabal files that previously worked.
    • Wildcards now match when the pattern’s extensions form a suffix of the candidate file’s extension, rather than requiring strict equality (e.g., previously *.html did not match foo.en.html, but now it does).
  • License fields use identifiers from SPDX License List version 3.2 2018-07-10

7.2. cabal-version: 2.2

  • New common stanzas and import pseudo-field added.
  • New library:virtual-modules field added.
  • New cxx-sources and cxx-options fields added for suppporting bundled foreign routines implemented in C++.
  • New asm-sources and asm-options fields added for suppporting bundled foreign routines implemented in assembler.
  • New extra-bundled-libraries field for specifying additional custom library objects to be installed.
  • Extended if control structure with support for elif keyword.
  • Changed default rules of build-type field to infer “build-type:” for “Simple”/”Custom” automatically.
  • license field syntax changed to require SPDX expression syntax (using SPDX license list version 3.0 2017-12-28).
  • Allow redundant leading or trailing commas in package fields (which require commas) such as build-depends.

7.3. cabal-version: 2.0

7.4. cabal-version: 1.24

  • New custom-setup stanza and custom-setup:setup-depends field added for specifying dependencies of custom Setup.hs scripts.
  • CPP Macros VERSION_$pkgname and MIN_VERSION_$pkgname are now also generated for the current package.
  • New extra-framework-dirs field added for specifying extra locations to find OS X frameworks.

7.5. cabal-version: 1.22

7.6. cabal-version: 1.20

  • Add support for new license-files field for declaring multiple license documents.
  • New CPP Macro MIN_TOOL_VERSION_$buildtool.
  • New license types BSD2 and MPL-2.0 added.

7.7. cabal-version: 1.18

  • Add support for new extra-doc-files field for specifying extra file assets referenced by the Haddock documentation.
  • New license type AGPL and AGPL-3 added.
  • Add support for specifying a C/C++/obj-C source file in executable:main-is field.
  • Add getSysconfDir operation to Paths_ API.

7.8. cabal-version: 1.16


this needs to be researched; there were only few changes between 1.12 and 1.18;

7.9. cabal-version: 1.12

  • Change syntax of cabal-version to support the new recommended cabal-version: x.y style