diff --git a/README.rst b/README.rst index 1721ca5..111c8c7 100644 --- a/README.rst +++ b/README.rst @@ -207,6 +207,44 @@ use the ``TOX_TESTENV_PASSENV`` environment variable. Read `the documentation for passing environment variables to tox `_. +Tox provisioning +~~~~~~~~~~~~~~~~ + +The tested projects can specify the +`minimal tox version `_ +and/or +`additional requires `_ +needed in the environment where ``tox`` is installed. +Normally, ``tox`` uses *provisioning* when such requirements are not met. +It creates a virtual environment, +installs (a newer version of) ``tox`` and the missing packages +into that environment and proxies all ``tox`` invocations trough that. +Unfortunately, this is undesired for ``tox-current-env``. + + 1. Starting with ``tox`` 3.23, it is possible to invoke it as + ``tox --no-provision`` to prevent the provision entirely. + When requirements are missing, ``tox`` fails instead of provisioning. + If a path is passed as a value for ``--no-provision``, + the requirements will be serialized to the file, as JSON. + 2. Starting with ``tox`` 3.22, the requires, if specified, are included in the + results of ``tox --print-deps-to``. + This only works when they are installed (otherwise see the first point). + 3. The minimal tox version, if specified, is included in the results of + ``tox --print-deps-to`` (as ``tox >= X.Y.Z``). + This only works when the version requirement is satisfied + (otherwise see the first point). + +With ``tox >= 3.23``, the recommend way to handle this is: + + 1. Run ``tox --no-provision provision.json --print-deps-to=...`` or similar. + 2. If the command fails, install requirements from ``provision.json`` to the + current environment and try again. + +Note that the specified requirements are likely to contain +`other tox plugins `_ +and many of them might interfere with ``tox-current-env`` in an undesired way. +If that is the case, the recommended way is to patch/sed such undesired plugins +out of the configuration before running ``tox``. Other limitations and known bugs ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~