Commit 7bfb03cf authored by Robert Henderson's avatar Robert Henderson

Added documentation for qualified constraints.

I also moved all the detail about constraint syntax that was in
the Nix-style local build cabal.project section into the section
on the --constraint command line option. This reduces some
duplication of information.
parent 53e35013
......@@ -1255,18 +1255,75 @@ Miscellaneous options
.. option:: --constraint=constraint
Restrict solutions involving a package to a given version range. For
example, ``cabal install --constraint="bar==2.1"`` will only
consider install plans that do not use ``bar`` at all, or ``bar`` of
version 2.1.
As a special case, ``cabal install --constraint="bar -none"``
prevents ``bar`` from being used at all (``-none`` abbreviates
``> 1 && < 1``); ``cabal install --constraint="bar installed"``
prevents reinstallation of the ``bar`` package;
``cabal install --constraint="bar +foo -baz"`` specifies that the
flag ``foo`` should be turned on and the ``baz`` flag should be
turned off.
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:
::
$ cabal install --constraint="bar == 2.1"
Version bounds have the same syntax as ``build-depends``. As
a special case, 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:
::
# Require bar to be installed with the foo flag turned on and
# the baz flag turned off.
$ cabal install --constraint="bar +foo -baz"
To specify multiple constraints, you may pass the
``constraint`` option multiple times.
There are also some more specialized constraints, which most people
don't generally need:
::
# Require that a version of bar be used that is already installed in
# the global package database.
$ cabal install --constraint="bar installed"
# Require the local source copy of bar to be used.
# (Note: By default, if we have a local package we will
# automatically use it, so it will generally not be necessary to
# specify this.)
$ cabal install --constraint="bar source"
# Require that bar have test suites and benchmarks enabled.
$ cabal install --constraint="bar test" --constraint="bar bench"
By default, constraints only apply to build dependencies
(``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
(``setup-depends``) nor do they apply to build tools
(``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:
::
# Example use of the 'setup' qualifier. This constraint
# applies to package bar when it is a dependency of the
# Setup.hs script of package foo.
$ cabal install --constraint="foo:setup.bar == 1.0"
# Example use of the 'exe' (executable build tool)
# qualifier. This constraint applies to package baz when it
# is a dependency of the build tool bar being used
# build package foo.
$ cabal install --constraint="foo:bar:exe.baz == 1.0"
.. option:: --preference=preference
......
......@@ -613,68 +613,21 @@ Solver configuration options
The following settings control the behavior of the dependency solver:
.. cfg-field:: constraints: constraints list (comma separated)
--constrant="pkg >= 2.0"
--constraint="pkg >= 2.0"
:synopsis: Extra dependencies constraints.
Add extra constraints to the version bounds, flag settings, and
other properties a solver can pick for a package. For example, to
only consider install plans that do not use ``bar`` at all, or use
``bar-2.1``, write:
::
constraints: bar == 2.1
Version bounds have the same syntax as ``build-depends``. You can
also specify flag assignments:
::
-- Require bar to be installed with the foo flag turned on and
-- the baz flag turned off
constraints: bar +foo -baz
-- Require that bar NOT be present in the install plan. Note:
-- this is just syntax sugar for '> 1 && < 1', and is supported
-- by build-depends.
constraints: bar -none
A package can be specified multiple times in ``constraints``, in
which case the specified constraints are intersected. This is
useful, since the syntax does not allow you to specify multiple
constraints at once. For example, to specify both version bounds and
flag assignments, you would write:
Add extra constraints to the version bounds, flag settings,
and other properties a solver can pick for a
package. For example:
::
constraints: bar == 2.1,
bar +foo -baz,
There are also some more specialized constraints, which most people
don't generally need:
::
-- Require bar to be preinstalled in the global package database
-- (this does NOT include the Nix-local build global store.)
constraints: bar installed
bar +foo -baz
-- Require the local source copy of bar to be used
-- (Note: By default, if we have a local package we will
-- automatically use it, so it generally not be necessary to
-- specify this)
constraints: bar source
-- Require that bar be solved with test suites and benchmarks enabled
-- (Note: By default, new-build configures the solver to make
-- a best-effort attempt to enable these stanzas, so this generally
-- should not be necessary.)
constraints: bar test,
bar bench
The command line variant of this field is
``--constraint="pkg >= 2.0"``; to specify multiple constraints, pass
the flag multiple times.
Valid constraints take the same form as for the `constraint
command line option
<installing-packages.html#cmdoption-setup-configure--constraint>`__.
.. cfg-field:: preferences: preference (comma separated)
--preference="pkg >= 2.0"
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment