manual for some details and some further pointers.
...
...
@@ -1695,23 +1710,49 @@ system-dependent values for these fields.
It is only syntactic sugar. It is exactly equivalent to
``foo >= 1.2 && < 1.3``.
Starting with Cabal 2.0, there's a new syntactic sugar to support
.. Warning::
A potential pitfall of the wildcard syntax is that the
constraint ``nats == 1.0.*`` doesn't match the release
``nats-1`` because the version ``1`` is lexicographically less
than ``1.0``. This is not an issue with the caret-operator
``^>=`` described below.
Starting with Cabal 2.0, there's a new syntactic sugar to express
PVP_-style
major upper bounds conveniently, and is inspired by similiar
major upper bounds conveniently, and is inspired by similar
syntactic sugar found in other language ecosystems where it's often
called the "Caret" operator:
::
build-depends: foo ^>= 1.2.3.4,
bar ^>= 1
build-depends:
foo ^>= 1.2.3.4,
bar ^>= 1
This allows to express the intent that this packages requires
versions of ``foo`` and ``bar`` which are semantically compatible
to ``foo-1.2.3.4`` and ``bar-1`` respectively. This subtle but important
difference in signaling allows tooling to treat *"hard"* ``<``-style
and *"weak"* ``^>=``-style upper bounds differently. For instance,
:option:`--allow-newer`'s ``^``-modifier allows to relax only *"weak"*
``^>=``-style bounds while leaving ``<``-bounds unaffected.
Ignoring the signaling intent, the equivalences are
- ``^>= x`` == ``>= x && < x.1``
- ``^>= x.y`` == ``>= x.y && < x.(y+1)``
- ``^>= x.y.z`` == ``>= x.y.z && < x.(y+1)``
- ``^>= x.y.z.u`` == ``>= x.y.z.u && < x.(y+1)``
- etc.
The declaration above is exactly equivalent to
Consequently, the example declaration above is equivalent to
::
build-depends: foo >= 1.2.3.4 && < 1.3,
bar >= 1 && < 1.1
build-depends:
foo >= 1.2.3.4 && < 1.3,
bar >= 1 && < 1.1
.. Note::
...
...
@@ -1792,6 +1833,7 @@ system-dependent values for these fields.
Deprecated in favor of :pkg-field:`default-extensions`.
.. pkg-field:: build-tool-depends: package:executable list
:since: 2.0
A list of Haskell programs needed to build this component.
Each is specified by the package containing the executable and the name of the executable itself, separated by a colon, and optionally followed by a version bound.
...
...
@@ -1838,7 +1880,7 @@ system-dependent values for these fields.
.. _buildtoolsbc:
Although this field is deprecated in favor of :pkg-field:`build-tool-depends`, there are some situations where you may prefer to use :pkg-field:`build-tool` in cases (1) and (2), as it is supported by more versions of Cabal.
Although this field is deprecated in favor of :pkg-field:`build-tool-depends`, there are some situations where you may prefer to use :pkg-field:`build-tools` in cases (1) and (2), as it is supported by more versions of Cabal.
In case (3), :pkg-field:`build-tool-depends` is better for backwards-compatibility, as it will be ignored by old versions of Cabal; if you add the executable to :pkg-field:`build-tools`, a setup script built against old Cabal will choke.
If an old version of Cabal is used, an end-user will have to manually arrange for the requested executable to be in your ``PATH``.
