Documentation for default-package-bounds

changelog.d/default-package-bounds

@@ -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).
+
+}

doc/buildinfo-fields-reference.rst

@@ -568,6 +568,14 @@ data-files
     .. math::
         \mathrm{commalist}\left\{ \mathop{\mathit{hs\text{-}string}}\mid{{[\mathop{\mathord{``}\mathtt{\ }\mathord{"}}\mathop{\mathord{``}\mathtt{\text{,}}\mathord{"}}]^c}}^+_{} \right\}
 
+default-package-bounds
+    * Monoidal field
+    * Available since ``cabal-version: 3.14``.
+    * Documentation of :pkg-field:`default-package-bounds`
+
+    .. math::
+        \mathrm{commalist}\left\{ \mathop{\mathit{pkg\text{-}name}}\mathop{\mathord{``}\mathtt{\text{:}}\mathord{"}}\mathop{\mathit{unqual\text{-}name}}\circ\mathop{\mathit{version\text{-}range}}\mid\mathop{\mathit{pkg\text{-}name}}\circ\mathop{\mathit{version\text{-}range}} \right\}
+
 description
     * Free text field
     * Documentation of :pkg-field:`description`

doc/cabal-package-description-file.rst

@@ -799,6 +799,61 @@ 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.14
+
+   Starting with **Cabal 3.14**, a new section ``default-package-bounds`` can be
+   declared on the package description which will provide version bounds that
+   will be used when a :pkg-field:`build-depends` dependency doesn't specify a version
+   bound.
+
+   So the package description:
+
+   ::
+
+        default-package-bounds:
+          , awesome-package ^>= 5
+
+        library a
+          build-depends: awesome-package
+
+        library b
+          build-depends: awesome-package >5.5
+
+        library c
+          build-depends: y
+
+   will be equivalent to:
+
+   ::
+
+        library a
+          build-depends: awesome-package ^>=5
+
+        library b
+          build-depends: awesome-package >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 :pkg-field:`pkgconfig-depends` entries.
+
+   Using ``--allow-newer`` or ``--allow-older`` will relax the ``default-package-bounds`` constraints
+   in the same way as it is done for normal :pkg-field:`build-depends` dependencies.
+
+   Dependencies on :pkg-field:`build-tool-depends` can also be influenced via ``default-package-bounds``:
+
+   ::
+
+        default-package-bounds:
+          markdown-unlit:markdown-unlit < 100
+
+        build-tool-depends:
+            markdown-unlit:markdown-unlit
+
 Library
 ^^^^^^^
 
@@ -1528,12 +1583,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``.
@@ -1546,7 +1601,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:
@@ -1637,8 +1692,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,
 
     ::
 
@@ -1655,7 +1710,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,13 +19,19 @@ relative to the respective preceding *published* version.
     versions of the ``Cabal`` library denote unreleased development
     branches which have no stability guarantee.
 
+``cabal-version: 3.14``
+-----------------------
+
+* 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.12``
 -----------------------
 
 * License fields use identifiers from SPDX License List version
   ``3.23 2024-02-08``.
 
-
 ``cabal-version: 3.8``
 ----------------------