7. Package Description Format Specification History — Cabal 3.16.1.0 User's Guide

# 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`.

- The `autogen-modules` field allows `PackageInfo_*` modules to be specified.

  Note

  Before `Cabal-3.12.0.0`, from `Cabal-3.10.1.0`, `PackageInfo_*` modules were supported irrespective of the `cabal-version`. From `Cabal-3.12.0.0`, such modules require `cabal-version: 3.12` or later.

## 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`

- New `library:signatures` and `mixins` fields added for supporting How to use Backpack modules.

- New `build-tool-depends` field added for adding build-time dependencies of executable components.

- New `custom-setup:autogen-modules` field 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-library` stanza.

- Add support for sublibrary stanzas.

- New CPP Macro `CURRENT_PACKAGE_VERSION`.

## 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`

- New `library:reexported-modules` field.

- Support for `-none` version constraint added to `build-depends`.

- New `license` type `ISC` added.

- Deprecate `hugs-options` and `nhc98-options` fields.

## 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`

- New `source-repository` stanza for information about the location of the package’s source code within a source code repository.

- Add support for new `bug-reports` field, to specify the URL where users should direct bug reports.

- Add support for wildcards in `data-files` and `extra-source-files` fields.

- Add support for `foo ==1.2.*` syntax to `build-depends` field.

- Add support for new `library:exposed` field (default: `True`), to be able to specify that the package should not be exposed.

- `cpp-options`, `cc-options` and `ld-options` fields no longer use `,` as a separator.

## 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’.