From 86a30706aa37848d8b386bcbf0bbb8eaffa1f855 Mon Sep 17 00:00:00 2001 From: Javier Sagredo Date: Tue, 21 Nov 2023 15:05:32 +0100 Subject: [PATCH] Document default-constraints --- changelog.d/default-constraints | 12 ++++++ doc/cabal-package-description-file.rst | 54 +++++++++++++++++++++++--- doc/file-format-changelog.rst | 7 ++++ 3 files changed, 67 insertions(+), 6 deletions(-) create mode 100644 changelog.d/default-constraints diff --git a/changelog.d/default-constraints b/changelog.d/default-constraints new file mode 100644 index 00000000000..515cbadb485 --- /dev/null +++ b/changelog.d/default-constraints @@ -0,0 +1,12 @@ +synopsis: Implement `default-constraints` field +packages: Cabal-syntax +prs: #9462 + +description: { + +The new `default-constraints` 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 ae07f3ff3bc..0553decca0b 100644 --- a/doc/cabal-package-description-file.rst +++ b/doc/cabal-package-description-file.rst @@ -795,6 +795,49 @@ describe the package as a whole: additional hooks, such as the scheme described in the section on `system-dependent parameters`_. +.. pkg-field:: default-constraints: library list + :since: 3.11 + + Starting with **Cabal 3.11**, a new section ``default-constraints`` can be + declared on the package description which will provide version bounds to the + dependencies that appear in ``build-depends`` lists with empty ranges. + + So the package description: + + :: + + default-constraints: + , x ^>= 5 + + library a + build-depends: x + + library b + build-depends: x >5.5 + + library c + build-depends: y + + will be parsed as: + + :: + + library a + build-depends: x ^>=5 + + library b + build-depends: x >5.5 + + library c + build-depends: y + + Notice that only unversioned bounds inherit the default-constraint clause. + 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 ^^^^^^^ @@ -1515,12 +1558,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``. @@ -1533,7 +1576,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: @@ -1624,8 +1667,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, :: @@ -1642,7 +1685,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..821b91e43e6 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.11`` +----------------------- + +* Added :pkg-field:`default-constraints` 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`` ----------------------