
Basic usage
=============================================

a simple tox.ini / default environments
-----------------------------------------------

Put basic information about your project and the test environments you
want your project to run in into a ``tox.ini`` file that should
reside next to your ``setup.py`` file::

    # content of: tox.ini , put in same dir as setup.py
    [tox]
    envlist = py26,py27
    [testenv]
    commands=py.test  # or 'nosetests' or ...

To sdist-package, install and test your project, you can
now type at the command prompt::

    tox

This will sdist-package your current project, create two virtualenv_
Environments, install the sdist-package into the environments and run
the specified command in each of them.  With::

    tox -e py26

you can run restrict the test run to the python2.6 environment.

Available "default" test environments names are::

    py24
    py25
    py26
    py27
    py30
    py31
    py32
    jython
    pypy

However, you can also create your own test environment names,
see some of the examples in :doc:`examples <../examples>`.

.. _virtualenv: http://pypi.python.org/pypi/virtualenv

.. _multiindex:

using a different default PyPI url
-----------------------------------------------

.. versionadded:: 0.9

To install dependencies and packages from a different
default PyPI server you can type interactively::

    tox -i http://pypi.testrun.org

This causes tox to install dependencies and the sdist install step
to use the specificied url as the index server.

You can cause the same effect by this ``tox.ini`` content::

    [tox]
    indexserver =
        default = http://pypi.testrun.org

installing dependencies from multiple PyPI servers
---------------------------------------------------

.. versionadded:: 0.9

You can instrument tox to install dependencies from
different PyPI servers, example::

    [tox]
    indexserver =
        DEV = http://mypypiserver.org

    [testenv]
    deps =
        docutils        # comes from standard PyPI
        :DEV:mypackage  # will be installed from custom "DEV" pypi url

This configuration will install ``docutils`` from the default
Python PYPI server and will install the ``mypackage`` from
our ``DEV`` indexserver, and the respective ``http://mypypiserver.org``
url.  You can override config file settings from the command line
like this::

    tox -i DEV=http://pypi.python.org/simple  # changes :DEV: package URLs
    tox -i http://pypi.python.org/simple      # changes default

forcing re-creation of virtual environments
-----------------------------------------------

.. versionadded:: 0.9

To for tox to recreate a (particular) virtual environment::

    tox --recreate -e py27

would trigger a complete reinstallation of the existing py27 environment
(or create it afresh if it doesn't exist).
