Skip to content

Commit

Permalink
Doc: rm -none from constraint section, make installed prominent
Browse files Browse the repository at this point in the history
- `PACKAGE -none` as already been removed in 3.4 as valid constraint.
(I guess this is now flag syntax.)

- Important constraint `installed` was just buried in an example, I made
it stand out more in a bullet point.
Same for `source`, even though this is an exotic constraint.

- Highlight constraint `installed` in connection with `allow-newer`.

- Group `test` and `bench` constraint with the `+/-FLAG` constraints.

Fixup: Apply concrete suggestions from code review

Fixes suggested by @ulysses4ever, thanks@

Co-authored-by: Artem Pelenitsyn <a.pelenitsyn@gmail.com>
  • Loading branch information
2 people authored and mergify[bot] committed Feb 24, 2023
1 parent 76670eb commit d9452a4
Showing 1 changed file with 26 additions and 22 deletions.
48 changes: 26 additions & 22 deletions doc/setup-commands.rst
Original file line number Diff line number Diff line change
Expand Up @@ -880,37 +880,29 @@ Miscellaneous options
.. option:: --constraint=constraint

Restrict solutions involving a package to given version
bounds, flag settings, and other properties. For example, to
consider only install plans that use version 2.1 of ``bar``
or do not use ``bar`` at all, write:
bounds, flag settings, and other properties.

The following considers only install plans where ``bar``,
if used, is restricted to version 2.1:

::

$ cabal install --constraint="bar == 2.1"

Version bounds have the same syntax as :pkg-field:`build-depends`.
As a special case, the following prevents ``bar`` from being
used at all:
The following prevents ``bar`` from being used at all:

::

# Note: this is just syntax sugar for '> 1 && < 1', and is
# supported by build-depends.
$ cabal install --constraint="bar -none"

You can also specify flag assignments:
$ cabal install --constraint="bar <0"

::

# Require bar to be installed with the foo flag turned on and
# the baz flag turned off.
$ cabal install --constraint="bar +foo -baz"
Version bounds have the same syntax as :pkg-field:`build-depends`.
Yet extra pseudo version bounds are available here in addition:

To specify multiple constraints, you may pass the
``constraint`` option multiple times.
- ``installed`` to fix a package to the already installed version.
Often useful for GHC-supplied packages in combination with :cfg-field:`allow-newer`,
e.g., ``--allow-newer='*:base' --constraint='base installed'``.

There are also some more specialized constraints, which most people
don't generally need:
- ``source`` to fix a package to the local source copy.

::

Expand All @@ -924,18 +916,30 @@ Miscellaneous options
# specify this.)
$ cabal install --constraint="bar source"

Further, we can specify flag assignments with ``+FLAG`` and ``-FLAG``
or enable test (``test``) and benchmark (``bench``) suites:

::

# Require bar to be installed with the foo flag turned on and
# the baz flag turned off.
$ cabal install --constraint="bar +foo -baz"

# Require that bar have test suites and benchmarks enabled.
$ cabal install --constraint="bar test" --constraint="bar bench"

To specify multiple constraints, you may pass the
``constraint`` option multiple times.

By default, constraints only apply to build dependencies
(:pkg-field:`build-depends`), build dependencies of build
dependencies, and so on. Constraints normally do not apply to
dependencies of the ``Setup.hs`` script of any package
(:pkg-field:`custom-setup:setup-depends`) nor do they apply to build tools
(:pkg-field:`build-tool-depends`) or the dependencies of build
tools. To explicitly apply a constraint to a setup or build
tool dependency, you can add a qualifier to the constraint as
follows:
tool dependency, you can add a qualifier ``setup`` or ``any``
to the constraint as follows:

::

Expand Down

0 comments on commit d9452a4

Please sign in to comment.