diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/changelog/93.doc.rst | 1 | ||||
| -rw-r--r-- | docs/example/general.rst | 39 | ||||
| -rw-r--r-- | docs/example/nose.rst | 6 |
3 files changed, 41 insertions, 5 deletions
diff --git a/docs/changelog/93.doc.rst b/docs/changelog/93.doc.rst new file mode 100644 index 00000000..2a6a8e8d --- /dev/null +++ b/docs/changelog/93.doc.rst @@ -0,0 +1 @@ +document tox environment recreate rules (:ref:`recreate`) - by :user:`gaborbernat` diff --git a/docs/example/general.rst b/docs/example/general.rst index 613e5987..6d0820f6 100644 --- a/docs/example/general.rst +++ b/docs/example/general.rst @@ -39,6 +39,45 @@ syntax: [testenv] commands = nosetests {posargs:--with-coverage} +.. _recreate: + +Dependency changes and tracking +------------------------------- + +Creating virtual environments and installing dependencies is a expensive operation. +Therefore tox tries to avoid it whenever possible, meaning it will never perform this +unless it detects with absolute certainty that it needs to perform an update. A tox +environment creation is made up of: + +- create the virtual environment +- install dependencies specified inside deps +- if it's a library project (has build package phase), install library dependencies + (with potential extras) + +These three steps are only performed once (given they all succeeded). Subsequent calls +that don't detect changes to the traits of that step will not alter the virtual +environment in any way. When a change is detected for any of the steps, the entire +virtual environment is removed and the operation starts from scratch (this is +because it's very hard to determine what would the delta changes would be needed - +e.g. a dependency could migrate from one dependency to another, and in this case +we would need to install the new while removing the old one). + +Here's what traits we track at the moment for each steps: + +- virtual environment trait is tied to the python path the :conf:`basepython` + resolves too (if this config changes, the virtual environment will be recreated), +- :conf:`deps` sections changes (meaning any string-level change for the entries, note + requirement file content changes are not tracked), +- library dependencies are tracked at :conf:`extras` level (because there's no + Python API to enquire about the actual dependencies in a non-tool specific way, + e.g. setuptools has one way, flit something else, and poetry another). + +Whenever you change traits that are not tracked we recommend you to manually trigger a +rebuild of the tox environment by passing the ``-r`` flag for the tox invocation. For +instance, for a setuptools project whenever you modify the ``install_requires`` keyword +at the next run force the recreation of the tox environment by passing the recreate cli +tox flag. + .. _`TOXENV`: Selecting one or more environments to run tests against diff --git a/docs/example/nose.rst b/docs/example/nose.rst index 8f42bdcc..336808a7 100644 --- a/docs/example/nose.rst +++ b/docs/example/nose.rst @@ -32,10 +32,6 @@ then run the specified test command. More examples? ------------------------------------------ -You can use and combine other features of ``tox`` with your tox runs, -e.g. :ref:`sphinx checks`. If you figure out some particular configurations -for nose/tox interactions please submit them. - -Also you might want to checkout :doc:`general`. +Also you might want to checkout :doc:`general` and :doc:`documentation`. .. include:: ../links.rst |