diff --git a/.github/workflows/users-guide.yml b/.github/workflows/users-guide.yml
index 5b56c25266bfc257cb5b915dce2cf8beb0968f7d..cd8137fbc38338ab0e8960f985dca95913566e5a 100644
--- a/.github/workflows/users-guide.yml
+++ b/.github/workflows/users-guide.yml
@@ -46,7 +46,7 @@ jobs:
runs-on: ubuntu-latest
strategy:
matrix:
- python-version: [3.7]
+ python-version: ['3.10']
steps:
- uses: actions/checkout@v3
diff --git a/doc/Makefile b/doc/Makefile
index 4e12ab8e87a9f1ac31e7b5c153ab7df098e8ed54..5ef45877223c775ac85dcb94b4a9c4011b65f64c 100644
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -23,6 +23,7 @@ build-and-check-requirements: requirements.txt check-requirements
# See https://modelpredict.com/wht-requirements-txt-is-not-enough
requirements.txt: requirements.in
. ../.python-sphinx-virtualenv/bin/activate \
+ && pip install --upgrade pip \
&& pip install pip-tools \
&& pip-compile requirements.in
diff --git a/doc/requirements.in b/doc/requirements.in
index 3638f36e09a6a8b93aa8652b90fa597cce5df9c1..df0b2f34d80069562fc4697491033a76cc039ee4 100644
--- a/doc/requirements.in
+++ b/doc/requirements.in
@@ -1,6 +1,8 @@
-sphinx >= 5
-sphinx_rtd_theme >= 1
+sphinx == 5.3.0
+sphinx_rtd_theme >= 1.2
sphinx-jsonschema
sphinxnotes-strike
# Pygments>=2.7.4 suggested by CVE-2021-20270 CVE-2021-27291
Pygments >= 2.7.4
+# Suggested by dependabot in https://github.com/haskell/cabal/pull/8807
+certifi >= 2022.12.7
diff --git a/doc/requirements.txt b/doc/requirements.txt
index 256b6bf407d1d0a0be8b59490f618fe716e5e76d..d65e0d37e158b7eaea764649e26aaa79048b16bb 100644
--- a/doc/requirements.txt
+++ b/doc/requirements.txt
@@ -1,6 +1,6 @@
#
-# This file is autogenerated by pip-compile with python 3.9
-# To update, run:
+# This file is autogenerated by pip-compile with Python 3.10
+# by the following command:
#
# pip-compile requirements.in
#
@@ -8,35 +8,33 @@ alabaster==0.7.12
# via sphinx
babel==2.9.1
# via sphinx
-certifi==2021.10.8
- # via requests
+certifi==2022.12.7
+ # via
+ # -r requirements.in
+ # requests
charset-normalizer==2.0.7
# via requests
-docutils==0.17.1
+docutils==0.18.1
# via
# sphinx
# sphinx-jsonschema
# sphinx-rtd-theme
idna==2.10
# via requests
-imagesize==1.2.0
- # via sphinx
-importlib-metadata==4.11.4
+imagesize==1.4.1
# via sphinx
-jinja2==2.11.3
+jinja2==3.1.2
# via sphinx
jsonpointer==2.1
# via sphinx-jsonschema
-markupsafe==1.1.1
+markupsafe==2.1.2
# via jinja2
-packaging==20.9
+packaging==23.0
# via sphinx
-pygments==2.10.0
+pygments==2.14.0
# via
# -r requirements.in
# sphinx
-pyparsing==2.4.7
- # via packaging
pytz==2021.3
# via babel
pyyaml==5.4.1
@@ -47,14 +45,14 @@ requests==2.26.0
# sphinx-jsonschema
snowballstemmer==2.1.0
# via sphinx
-sphinx==5.0.1
+sphinx==5.3.0
# via
# -r requirements.in
# sphinx-rtd-theme
# sphinxnotes-strike
sphinx-jsonschema==1.16.11
# via -r requirements.in
-sphinx-rtd-theme==1.0.0
+sphinx-rtd-theme==1.2.0
# via -r requirements.in
sphinxcontrib-applehelp==1.0.2
# via sphinx
@@ -62,6 +60,8 @@ sphinxcontrib-devhelp==1.0.2
# via sphinx
sphinxcontrib-htmlhelp==2.0.0
# via sphinx
+sphinxcontrib-jquery==2.0.0
+ # via sphinx-rtd-theme
sphinxcontrib-jsmath==1.0.1
# via sphinx
sphinxcontrib-qthelp==1.0.3
@@ -72,5 +72,6 @@ sphinxnotes-strike==1.1
# via -r requirements.in
urllib3==1.26.7
# via requests
-zipp==3.8.0
- # via importlib-metadata
+
+# The following packages are considered to be unsafe in a requirements file:
+# setuptools
diff --git a/doc/setup-commands.rst b/doc/setup-commands.rst
index 12af7db7fd6d87abeb81a5a8854ddd45cec26dca..988d431e693240ef360aa051c9440ba50e8ef8ac 100644
--- a/doc/setup-commands.rst
+++ b/doc/setup-commands.rst
@@ -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.
::
@@ -924,9 +916,21 @@ 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
@@ -934,8 +938,8 @@ Miscellaneous options
(: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:
::