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