diff --git a/changelog.d/package-constraints b/changelog.d/package-constraints new file mode 100644 index 00000000000..5c30780ca58 --- /dev/null +++ b/changelog.d/package-constraints @@ -0,0 +1,12 @@ +synopsis: Implement `default-package-bounds` field +packages: Cabal-syntax +prs: #9462 + +description: { + +The new `default-package-bounds` stanza can be used to default versions that are +ommitted in the build-depends fields. This could be done previously by means of +common stanzas but it was too verbose and obscure (dependencies came sometimes +from stanzas). + +} diff --git a/doc/cabal-package-description-file.rst b/doc/cabal-package-description-file.rst index 8e5e59db1cf..d33fd1f4a10 100644 --- a/doc/cabal-package-description-file.rst +++ b/doc/cabal-package-description-file.rst @@ -790,6 +790,49 @@ describe the package as a whole: additional hooks, such as the scheme described in the section on `system-dependent parameters`_. +.. pkg-field:: default-package-bounds: library list + :since: 3.12 + + Starting with **Cabal 3.12**, a new section ``default-package-bounds`` can be + declared on the package description which will provide version bounds that + will be used when a `build-depends` dependency doesn't specify a version + bound. + + So the package description: + + :: + + package-constraints: + , x ^>= 5 + + library a + build-depends: x + + library b + build-depends: x >5.5 + + library c + build-depends: y + + will be equivalent to: + + :: + + library a + build-depends: x ^>=5 + + library b + build-depends: x >5.5 + + library c + build-depends: y + + This process is only applied as a syntactic desugar, only to avoid + duplication and verbosity on the cabal file. It will not apply version bounds + on transitive dependencies that are not explicitly listed as a dependency. It + will not be applied to ``build-tool-depends`` or ``pkgconfig-depends`` + entries. + Library ^^^^^^^ @@ -1519,12 +1562,12 @@ system-dependent values for these fields. common because it is recommended practice for package versions to correspond to API versions (see PVP_). - Since Cabal 1.6, there is a special wildcard syntax to help with + Since **Cabal 1.6**, there is a special wildcard syntax to help with such ranges :: - build-depends: foo ==1.2.* + build-depends: foo ==1.2.*** It is only syntactic sugar. It is exactly equivalent to ``foo >= 1.2 && < 1.3``. @@ -1537,7 +1580,7 @@ system-dependent values for these fields. than ``1.0``. This is not an issue with the caret-operator ``^>=`` described below. - Starting with Cabal 2.0, there's a new version operator to express + Starting with **Cabal 2.0**, there's a new version operator to express PVP_-style major upper bounds conveniently, and is inspired by similar syntactic sugar found in other language ecosystems where it's often called the "Caret" operator: @@ -1628,8 +1671,8 @@ system-dependent values for these fields. renaming in ``build-depends``; however, this support has since been removed and should not be used. - Starting with Cabal 3.0, a set notation for the ``==`` and ``^>=`` operator - is available. For instance, + Starting with **Cabal 3.0**, a set notation for the ``==`` and ``^>=`` + operator is available. For instance, :: @@ -1646,7 +1689,6 @@ system-dependent values for these fields. build-depends: network ^>= { 2.6.3.6, 2.7.0.2, 2.8.0.0, 3.0.1.0 } - .. pkg-field:: other-modules: identifier list A list of modules used by the component but not exposed to users. diff --git a/doc/file-format-changelog.rst b/doc/file-format-changelog.rst index c3d9aa2dfc8..66569b8b2a4 100644 --- a/doc/file-format-changelog.rst +++ b/doc/file-format-changelog.rst @@ -19,6 +19,13 @@ relative to the respective preceding *published* version. versions of the ``Cabal`` library denote unreleased development branches which have no stability guarantee. +``cabal-version: 3.12`` +----------------------- + +* Added :pkg-field:`default-package-bounds` stanza. This allows to declare + constraints that will be used for the dependencies that have no specified + constraints associated in ``build-depends`` lists. + ``cabal-version: 3.8`` ----------------------