Document package-constraints

changelog.d/package-constraints

@@ -0,0 +1,12 @@
+synopsis: Implement `package-constraints` field
+packages: Cabal-syntax
+prs: #9462
+
+description: {
+
+The new `package-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).
+
+}

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:: package-constraints: library list
+   :since: 3.11
+
+   Starting with **Cabal 3.11**, a new section ``package-constraints``
+   can be declared on the package description which will provide
+   version bounds that will be monoidally combined with those in
+   `build-depends` sections.
+
+   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 parsed as:
+
+   ::
+
+        library a
+          build-depends: x ^>=5
+
+        library b
+          build-depends: x >5.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
 ^^^^^^^
 
@@ -1480,13 +1523,13 @@ system-dependent values for these fields.
     Version constraints use the operators ``==, >=, >, <, <=`` and a
     version number. Multiple constraints can be combined using ``&&`` or
     ``||``.
-    
+
     .. Note::
 
        Even though there is no ``/=`` operator, by combining operators we can
        skip over one or more versions, to skip a deprecated version or to skip
        versions that narrow the constraint solving more than we'd like.
-       
+
        For example, the ``time =1.12.*`` series depends on ``base >=4.13 && <5``
        but ``time-1.12.3`` bumps the lower bound on base to ``>=4.14``.  If we
        still want to compile with a ``ghc-8.8.*`` version of GHC that ships with
@@ -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.

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:`package-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``
 ----------------------