1packaging 2========= 3 4Although one can use tox to develop and test applications one of its most popular 5usage is to help library creators. Libraries need first to be packaged, so then 6they can be installed inside a virtual environment for testing. To help with this 7tox implements PEP-517_ and PEP-518_. This means that by default 8tox will build source distribution out of source trees. Before running test commands 9``pip`` is used to install the source distribution inside the build environment. 10 11To create a source distribution there are multiple tools out there and with PEP-517_ and PEP-518_ 12you can easily use your favorite one with tox. Historically tox 13only supported ``setuptools``, and always used the tox host environment to build 14a source distribution from the source tree. This is still the default behavior. 15To opt out of this behaviour you need to set isolated builds to true. 16 17setuptools 18---------- 19Using the ``pyproject.toml`` file at the root folder (alongside ``setup.py``) one can specify 20build requirements. 21 22.. code-block:: toml 23 24 [build-system] 25 requires = [ 26 "setuptools >= 35.0.2", 27 "setuptools_scm >= 2.0.0, <3" 28 ] 29 build-backend = "setuptools.build_meta" 30 31.. code-block:: ini 32 33 # tox.ini 34 [tox] 35 isolated_build = True 36 37flit 38---- 39flit_ requires ``Python 3``, however the generated source 40distribution can be installed under ``python 2``. Furthermore it does not require a ``setup.py`` 41file as that information is also added to the ``pyproject.toml`` file. 42 43.. code-block:: toml 44 45 [build-system] 46 requires = ["flit >= 1.1"] 47 build-backend = "flit.buildapi" 48 49 [tool.flit.metadata] 50 module = "package_toml_flit" 51 author = "Happy Harry" 52 author-email = "happy@harry.com" 53 home-page = "https://github.com/happy-harry/is" 54 55.. code-block:: ini 56 57 # tox.ini 58 [tox] 59 isolated_build = True 60 61 [tox:.package] 62 # note tox will use the same python version as under what tox is installed to package 63 # so unless this is python 3 you can require a given python version for the packaging 64 # environment via the basepython key 65 basepython = python3 66 67 68poetry 69------ 70poetry_ requires ``Python 3``, however the generated source 71distribution can be installed under ``python 2``. Furthermore it does not require a ``setup.py`` 72file as that information is also added to the ``pyproject.toml`` file. 73 74.. code-block:: toml 75 76 [build-system] 77 requires = ["poetry >= 0.12, <1"] 78 build-backend = "poetry.masonry.api" 79 80 [tool.poetry] 81 name = "package_toml_poetry" 82 version = "0.1.0" 83 description = "" 84 authors = ["Name <email@email.com>"] 85 86.. code-block:: ini 87 88 # tox.ini 89 [tox] 90 isolated_build = True 91 92 [tox:.package] 93 # note tox will use the same python version as under what tox is installed to package 94 # so unless this is python 3 you can require a given python version for the packaging 95 # environment via the basepython key 96 basepython = python3 97 98.. include:: ../links.rst 99