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.
Note
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: 3.14¶
- Added field - extra-filesfor specifying extra files to be included in- sdistwithout adding any other semantics (cf.- extra-source-filesis tracked by- cabal build).
- License fields use identifiers from SPDX License List version - 3.25 2024-08-19.
7.2. cabal-version: 3.12¶
- License fields use identifiers from SPDX License List version - 3.23 2024-02-08.
7.3. cabal-version: 3.8¶
- Added field - code-generatorsto- test-suitestanzas. This enumerates executabes (possibly brought into scope by- build-tool-depends) that are run after all other preprocessors. These executables are invoked with a target dir for output, a sequence of all source directories with source files of local lib components that the given test stanza depends on, and following a double dash, all options cabal would pass to ghc for a build. They are expected to output a newline-separated list of generated modules which have been written to the targetdir. This can be used for driving doctests and other discover-style tests generated from source code.
- Added fields - extra-libraries-staticand- extra-lib-dirs-staticto allow Haskell libraries to remember linker flags needed for fully static linking of system libraries into executables. The existing field- pkgconfig-dependscan used to append the relevant output of- pkg-config --libs --staticto these new fields automatically. When- extra-libraries-staticis not given, it defaults to- extra-libraries. When- extra-lib-dirs-staticis not given, it defaults to- extra-lib-dirs.
- Wildcard matching has been slightly expanded. Matches are now allowed of the form - foo/**/literalFile. Prior, double-star wildcards required the trailing filename itself be a wildcard.
- Allow the omission of the type field in test-suite and benchmark stanzas when the type can be inferred by the presence of main-is or test-module. 
- License fields use identifiers from SPDX License List version - 3.16 2022-02-06
7.4. cabal-version: 3.6¶
- License fields use identifiers from SPDX License List version - 3.10 2020-08-03
- Add - hsc2hs-options
7.5. cabal-version: 3.4¶
- License fields use identifiers from SPDX License List version - 3.9 2020-05-15
- Dependencies to sublibraries must be specified explicitly, even for current package. For example: - build-depends: mypackage:my-sublibThis way you can have a sublibrary with the same name as some external dependency.
- Remove - -anyand- -nonesyntax for version ranges Use- >=0and- <0respectively.
- default-languageis optional. The Default value is to use the compiler’s default language.
- mixinsfield allow specifying a sublibrary.
7.6. cabal-version: 3.0¶
- New - library:visibilityfor exposing sublibraries.
- New - pkg:liband- pkg:{lib1,lib2}syntax in- build-dependsfor depending on public sublibraries from other packages.
- Added the - extra-dynamic-library-flavoursfield to specify non-trivial variants of dynamic flavours. It is- extra-library-flavoursbut for shared libraries. Mainly useful for GHC’s RTS library.
- Free text fields (e.g. - description) preserve empty lines and indentation. In other words, you don’t need to add dots for blank lines.
- License fields use identifiers from SPDX License List version - 3.6 2019-07-10
- Remove deprecated - hs-source-dir,- extensionsand- build-toolsfields.
- Common stanzas are now allowed also in the beginning of conditional sections. In other words, the following is valid - library import deps if flag(foo) import foo-deps
- Allow redundant leading or trailing commas in package fields with optional commas, such as - library:exposed-modules
- Require fields with optional commas to consistently omit or place commas between elements. 
- Changed the behavior of - extra-bundled-librariesfield. The naming convention of dynamic library files (e.g. generated by a custom build script) has changed. For library names prefixed with “C”, the dynamic library file name(s) must be of the form lib<library-name>.<dyn-library-extension>* instead of the old libC<library-name>-ghc<ghc-flavour><ghc-version>.<dyn-library-extension>
- New set-notation syntax for - ==and- ^>=operators, see- build-dependsfield documentation for examples.
- Allow more whitespace in - mixinsfield
- Wildcards are disallowed in - pkgconfig-depends, Yet the pkgconfig format is relaxed to accept e.g. versions like- 1.1.0h.
- New - autogen-includesfor specifying- install-includeswhich are autogenerated (e.g. by a- configurescript).
- New - asm-sourcesand- asm-optionsfields added for supporting bundled foreign routines implemented in assembler.
- New - cmm-sourcesand- cmm-optionsfields added for supporting bundled foreign primops implemented in C–.
7.7. 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/**/*.htmlis valid;- foo/**/bar/*.htmland- foo/**/**/*.html,- foo/**/bar.htmlare all invalid). As- **was an error in globs before, this does not affect any existing- .cabalfiles that previously worked. (Caveat: Double-star wildcards in- data-filesdirectories, e.g.- data-files: data/**/*.csv, are only supported correctly from Cabal 3.0.)
- 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 - *.htmldid not match- foo.en.html, but now it does).
 
- License fields use identifiers from SPDX License List version - 3.2 2018-07-10
7.8. cabal-version: 2.2¶
- New - library:virtual-modulesfield added.
- New - cxx-sourcesand- cxx-optionsfields added for supporting bundled foreign routines implemented in C++.
- New - extra-bundled-librariesfield for specifying additional custom library objects to be installed.
- Extended - ifcontrol structure with support for- elifkeyword.
- Changed default rules of - build-typefield to infer “build-type:” for “Simple”/”Custom” automatically.
- licensefield 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.9. cabal-version: 2.0¶
- New - library:signaturesand- mixinsfields added for supporting How to use Backpack modules.
- New - build-tool-dependsfield added for adding build-time dependencies of executable components.
- New - custom-setup:autogen-modulesfield added for declaring modules which are generated at build time.
- Support for new PVP caret-style version operator ( - ^>=) added to- build-depends.
- Add support for new - foreign-librarystanza.
- Add support for sublibrary stanzas. 
- New CPP Macro - CURRENT_PACKAGE_VERSION.
7.10. cabal-version: 1.24¶
- New - custom-setupstanza and- custom-setup:setup-dependsfield added for specifying dependencies of custom- Setup.hsscripts.
- CPP Macros - VERSION_$pkgnameand- MIN_VERSION_$pkgnameare now also generated for the current package.
- New CPP Macros - CURRENT_COMPONENT_IDand- CURRENT_PACKAGE_KEY.
- New - extra-framework-dirsfield added for specifying extra locations to find OS X frameworks.
7.11. cabal-version: 1.22¶
- New - library:reexported-modulesfield.
- Support for - -noneversion constraint added to- build-depends.
- New - licensetype- ISCadded.
7.12. cabal-version: 1.20¶
- Add support for new - license-filesfield for declaring multiple license documents.
- New CPP Macro - MIN_TOOL_VERSION_$buildtool.
- New - licensetypes- BSD2and- MPL-2.0added.
7.13. cabal-version: 1.18¶
- Add support for new - extra-doc-filesfield for specifying extra file assets referenced by the Haddock documentation.
- New - licensetype- AGPLand- AGPL-3added.
- Add support for specifying a C/C++/obj-C source file in - executable:main-isfield.
- Add - getSysconfDiroperation to- Paths_API.
7.14. cabal-version: 1.16¶
Todo
this needs to be researched; there were only few changes between 1.12 and 1.18;
7.15. cabal-version: 1.12¶
- Change syntax of - cabal-versionto support the new recommended- cabal-version: x.ystyle