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-files for specifying extra files to be included in sdist without adding any other semantics (compare, extra-source-files is tracked by cabal build).

  • License fields use identifiers from SPDX License List version 3.25 2024-08-19.

  • The build-type field allows the new build type Hooks to be specified.

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-generators to test-suite stanzas. This enumerates executables (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-static and extra-lib-dirs-static to allow Haskell libraries to remember linker flags needed for fully static linking of system libraries into executables. The existing field pkgconfig-depends can used to append the relevant output of pkg-config --libs --static to these new fields automatically. When extra-libraries-static is not given, it defaults to extra-libraries. When extra-lib-dirs-static is 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-sublib This way you can have a sublibrary with the same name as some external dependency.

  • Remove -any and -none syntax for version ranges Use >=0 and <0 respectively.

  • default-language is optional. The Default value is to use the compiler’s default language.

  • mixins field allow specifying a sublibrary.

7.6. cabal-version: 3.0

  • New library:visibility for exposing sublibraries.

  • New pkg:lib and pkg:{lib1,lib2} syntax in build-depends for depending on public sublibraries from other packages.

  • Added the extra-dynamic-library-flavours field to specify non-trivial variants of dynamic flavours. It is extra-library-flavours but 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, extensions and build-tools fields.

  • 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-libraries field. 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-depends field documentation for examples.

  • Allow more whitespace in mixins field

  • Wildcards are disallowed in pkgconfig-depends, Yet the pkgconfig format is relaxed to accept e.g. versions like 1.1.0h.

  • New autogen-includes for specifying install-includes which are autogenerated (e.g. by a configure script).

  • New asm-sources and asm-options fields added for supporting bundled foreign routines implemented in assembler.

  • New cmm-sources and cmm-options fields 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/**/*.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. (Caveat: Double-star wildcards in data-files directories, 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 *.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

  • Deprecate jhc-options field.

7.8. 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 supporting bundled foreign routines implemented in C++.

  • 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.9. cabal-version: 2.0

7.10. 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 CPP Macros CURRENT_COMPONENT_ID and CURRENT_PACKAGE_KEY.

  • New extra-framework-dirs field added for specifying extra locations to find OS X frameworks.

7.11. cabal-version: 1.22

7.12. 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.13. 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.14. cabal-version: 1.14

  • New benchmark stanza for describing a package benchmark added.

  • exitcode-stdio-1.0 is a valid value of the type field in a benchmark stanza.

  • detailed-0.9 added as a valid value of the type field in a test-suite stanza.

7.15. cabal-version: 1.12

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

7.16. cabal-version: ==1.10

  • Change the syntax of cabal-version to require a version range of the form cabal-version: >= x.y. (Consequently, cabal-version: ==1.10 is, itself, not valid syntax.)

  • New default-language (to specify a default language standard when one is not explicitly specified) and other-languages (for language standards used by some modules) added.

  • New default-extensions (for Haskell language extensions used by every module) and other-extensions (for extensions used by some modules) added. extensions deprecated.

  • New test-suite stanza for describing a package test suite added.

  • exitcode-stdio-1.0 is a valid value of the type field in a test-suite stanza.

7.17. cabal-version: ==1.8

  • Added support for the build-depends of a executable stanza being able to specify the library in the same package (if the package provides one) by the name of the package (without a version constraint). Cabal then treats the executable as if it were in another package that depended on the package providing the executable and the library.

  • The syntax for specifying package version ranges is expanded.

  • New license types MIT and versioned GPL and LGPL added.

7.18. cabal-version: ==1.6

7.19. cabal-version: ==1.2.1

  • New format for the flag, library and executable stanzas.

  • Add support for new cpp-options field, to specify options used when pre-processing Haskell modules.

  • Replace nhc-options field with nhc98-options field.

7.20. cabal-version: ==1.2.0

  • The cabal-version field is now required.

  • New flag stanza for specifying configuration flags and add support for conditional blocks in library and executable stanzas.

  • Add distinct library stanza.

  • New format for executable stanzas.

  • Add support for new build-type field (default: Custom), to specify the type of build used by this package.

  • Add support for new build-tools field, to specify tools needed to build the package.

  • Add support for new pkgconfig-depends field, to specify pkg-config packages needed to build the package.

  • Add support for new ghc-shared-options field, to specify additional options for GHC when the package is built as a shared library.

7.21. cabal-version: ==1.1.6

  • Add support for new install-includes field, distinct from the includes field, to specify header files from the package.

  • Add support for new jhc-options field, to specify additional options for John Meacham’s Haskell compiler (JHC).

7.22. cabal-version: ==1.1.4

  • Add support for new optional cabal-version field, to specify the version of Cabal required for the package.

  • Add support for new author, homepage, package-url, synopsis, description and category fields.

  • Add support for new tested-with field to specify compilers and versions against which the package has been tested.

  • Add support for new data-files field to specify files for use by the package at run-time.

  • Add support for new extra-source-files field to specify files to be included in source distributions.

  • Add support for new extra-tmp-files field to specify files to be removed when cleaning up.

  • Replace hs-source-dir field with hs-source-dirs field.

  • Add support for new ghc-prof-options field, to specify additional options for GHC when the package is built with profiling.

  • Add support for extension fields beginning with x-.

7.23. Cabal-1.0

Cabal-1.0, released March 2005, came with a specification for ‘The Haskell Cabal: A Common Architecture for Building Applications and Tools’, including Section 5.2 ‘Package description in the simple build infrastructure’.