
tox configuration specification
================================

.. _ConfigParser: http://docs.python.org/library/configparser.html

``tox.ini`` files uses the standard ConfigParser_ "ini-style" format. 
Below you find the specification, but you might want to skim some 
:doc:`examples` first and use this page as a reference. 

Tox global settings
----------------------

List of optional global options::

    [tox]
    toxworkdir=path   # tox working directory, defaults to {toxinidir}/.tox
    setupdir=path     # defaults to {toxinidir} 
    distdir=path      # defaults to {toxworkdir}/dist
    distshare=path    # defaults to {homedir}/.tox/distshare
    envlist=ENVLIST   # defaults to the list of all environments

``tox`` autodetects if it is running in a Hudson_ context 
(by checking for existence of the ``HUDSON_URL`` environment variable) 
and will first lookup global tox settings in this section::

    [tox:hudson]
    ...               # override [tox] settings for the hudson context
    # note: for hudson distshare defaults to ``{toxworkdir}/distshare``. 


envlist setting
+++++++++++++++++++++++++

Determining the environment list that ``tox`` is to operate one
happens in this order:

* command line option ``-eENVLIST`` 
* environment variable ``TOXENV``
* ``tox.ini`` file's ``envlist``

Virtualenv test environment settings 
-------------------------------------------

Test environments are defined by a::

    [testenv:NAME]
    ...

section.  The ``NAME`` will be the name of the virtual environment. 
Defaults for each setting in this section are looked up in the::

    [testenv]
    ...

testenvironment default section. 

Complete list of settings that you can put into ``testenv*`` sections:

``basepython=NAME-OR-PATH``
    name or path to a Python interpreter which will be used for creating
    the virtual environment. **default**: interpreter used for tox invocation. 

``commands=ARGVLIST``
    the commands to be called for testing. Each command is defined 
    by one or more lines; a command can have multiple lines if a line 
    ends with the ``\`` character in which case the subsequent line 
    will be appended (and may contain another ``\`` character ...). 
    For eventually performing a call to ``subprocess.Popen(args, ...)`` 
    ``args`` are determined by splitting the whole command by whitespace. 

``changedir=path``
    change to this working directory when executing the test command. 
    **default**: ``{toxinidir}``

``args_are_paths=BOOL``
    treat positional arguments passed to ``tox`` as file system paths
    and - if they exist on the filesystem - rewrite them according 
    to the ``changedir``. 
    **default**: True (due to the exists-on-filesystem check it's usually
    safe to try rewriting).

``envtmpdir=path``
    defines a temporary directory for the virtualenv which will be cleared
    each time before the group of test commands is invoked. 
    **default**: ``{envdir}/tmp``

``envlogdir=path``
    defines a directory for logging where tox will put logs of tool 
    invocation. 
    **default**: ``{envdir}/log``

``deps=MULTI-LINE-LIST``
    dependencies to be installed into the environment prior to project
    package installation.  Each line defines a dependency, which will be
    passed to easy_install/pip for processing.  It usually can be a file, 
    and URL or a package name. 

``downloadcache=path``
    (pip only) use this directory for caching downloads - this defaults to the 
    environment variable ``PIP_DOWNLOAD_CACHE`` if it is set. 
    **default**: no download cache will be used. 
    **note**: if creating multiple environments use of a download cache greatly 
    speeds up the testing process. 

``distribute=True|False``
    Set to ``False`` if you want to use setuptools_ instead of the default
    distribute_ in the virtual environment. 
    **default:** True. 

``sitepackages=True|False``
    Set to ``True`` if you want to create virtual environments that also 
    have access to globally installed packages.  **default:** False, meaning
    that virtualenvs will be created with ``--no-site-packages`` by default. 

Substitutions
---------------------

Any ``key=value`` setting in an ini-file can make use
of value substitution through the ``{...}`` string-substitution pattern. 

Globally available substitutions
+++++++++++++++++++++++++++++++++++++++++++

``{toxinidir}`` 
    the directory where tox.ini is located 

``{toxworkdir}`` 
    the directory where virtual environments are created and sub directories
    for packaging reside. 

``{homedir}``
    the user-home directory path.

``{distdir}`` 
    the directory where sdist-packages will be created in 

``{distshare}`` 
    the directory where sdist-packages will be copied to so that
    they may be accessed by other processes or tox runs. 
    
substitutions for virtualenv-related sections 
++++++++++++++++++++++++++++++++++++++++++++++++++++++

``{envname}``
    the name of the virtual environment 
``{envpython}``
    path to the virtual Python interpreter 
``{envdir}``
    directory of the the virtualenv hierarchy
``{envbindir}``
    directory where executables are located 
``{envtmpdir}``
    the environment temporary directory 
``{envlogdir}`` 
    the environment log directory 


environment variable substitutions
+++++++++++++++++++++++++++++++++++++++++++

If you specify a substitution string like this::

    {env:KEY}

then the value will be retrieved as ``os.environ['KEY']`` 
and raise an Error if the environment variable 
does not exist. 

.. _`command positional substitution`: 
.. _`positional substitution`: 

substitutions for positional arguments in commands
++++++++++++++++++++++++++++++++++++++++++++++++++++++

When you specify positional arguments to a ``tox`` run like this::

    tox arg1 arg2 

these arguments will textually replace the ``[.*]`` pattern in
any ``command`` specification. 

Use a double ``--`` if you also want to pass options to an underlying
test command, for example::

    tox -- --opt1 ARG1

will make the `--opt1 ARG1`` appear in all test commands where ``[]`` was 
specified.  By default (see ``args_are_paths`` setting), ``tox`` rewrites 
each positional argument if it is a relative path and exists on the 
filesystem to become a path relative to the ``changedir`` setting. 

Other Rules and notes
=========================

* ``path`` specifications: if a specified ``path`` is a relative path 
  it will be considered as relative to the ``toxinidir``, the directory 
  where the configuration file resides. 

.. include:: links.txt
