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 insdist
without adding any other semantics (compare,extra-source-files
is tracked bycabal build
).License fields use identifiers from SPDX License List version
3.25 2024-08-19
.The
build-type
field allows the new build typeHooks
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
totest-suite
stanzas. This enumerates executables (possibly brought into scope bybuild-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
andextra-lib-dirs-static
to allow Haskell libraries to remember linker flags needed for fully static linking of system libraries into executables. The existing fieldpkgconfig-depends
can used to append the relevant output ofpkg-config --libs --static
to these new fields automatically. Whenextra-libraries-static
is not given, it defaults toextra-libraries
. Whenextra-lib-dirs-static
is not given, it defaults toextra-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
andpkg:{lib1,lib2}
syntax inbuild-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 isextra-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
andbuild-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, seebuild-depends
field documentation for examples.Allow more whitespace in
mixins
fieldWildcards are disallowed in
pkgconfig-depends
, Yet the pkgconfig format is relaxed to accept e.g. versions like1.1.0h
.New
autogen-includes
for specifyinginstall-includes
which are autogenerated (e.g. by aconfigure
script).New
asm-sources
andasm-options
fields added for supporting bundled foreign routines implemented in assembler.New
cmm-sources
andcmm-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
andfoo/**/**/*.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 indata-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 matchfoo.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
library:virtual-modules
field added.New
cxx-sources
andcxx-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 forelif
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 version3.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
andmixins
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 tobuild-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 andcustom-setup:setup-depends
field added for specifying dependencies of customSetup.hs
scripts.CPP Macros
VERSION_$pkgname
andMIN_VERSION_$pkgname
are now also generated for the current package.New CPP Macros
CURRENT_COMPONENT_ID
andCURRENT_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 tobuild-depends
.New
license
typeISC
added.Deprecate
hugs-options
andnhc98-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
typesBSD2
andMPL-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
typeAGPL
andAGPL-3
added.Add support for specifying a C/C++/obj-C source file in
executable:main-is
field.Add
getSysconfDir
operation toPaths_
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 abenchmark
stanza.detailed-0.9
added as a valid value of the type field in atest-suite
stanza.
7.15. cabal-version: 1.12
Change the syntax of
cabal-version
to support the new recommendedcabal-version: x.y
style
7.16. cabal-version: ==1.10
Change the syntax of
cabal-version
to require a version range of the formcabal-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) andother-languages
(for language standards used by some modules) added.New
default-extensions
(for Haskell language extensions used by every module) andother-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 atest-suite
stanza.
7.17. cabal-version: ==1.8
Added support for the
build-depends
of aexecutable
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
typesMIT
and versionedGPL
andLGPL
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
andextra-source-files
fields.Add support for
foo ==1.2.*
syntax tobuild-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
andld-options
fields no longer use,
as a separator.
7.19. cabal-version: ==1.2.1
New format for the
flag
,library
andexecutable
stanzas.Add support for new
cpp-options
field, to specify options used when pre-processing Haskell modules.Replace
nhc-options
field withnhc98-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 inlibrary
andexecutable
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 specifypkg-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 theincludes
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 ofCabal
required for the package.Add support for new
author
,homepage
,package-url
,synopsis
,description
andcategory
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 withhs-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’.