1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
|
# `pyproject.toml`
```{versionadded} 10.0
```
Modern Python packages can contain a `pyproject.toml` file, first introduced in
{pep}`518` and later expanded in {pep}`517`, {pep}`621` and {pep}`660`.
This file contains build system requirements and information, which are used by
pip to build the package.
## Build process
The overall process for building a package is:
- Create an isolated build environment.
- Populate the build environment with build dependencies.
- Generate the package's metadata, if necessary and possible.
- Generate a wheel for the package.
The wheel can then be used to perform an installation, if necessary.
### Build Isolation
For building packages using this interface, pip uses an _isolated environment_.
That is, pip will install build-time Python dependencies in a temporary
directory which will be added to `sys.path` for the build commands. This ensures
that build requirements are handled independently of the user's runtime
environment.
For example, a project that needs an older version of setuptools to build can
still be installed, even if the user has an newer version installed (and
without silently replacing that version).
### Build-time dependencies
Introduced in {pep}`518`, the `build-system.requires` key in the
`pyproject.toml` file is a list of requirement specifiers for build-time
dependencies of a package.
```toml
[build-system]
requires = ["setuptools ~= 58.0", "cython ~= 0.29.0"]
```
It is also possible for a build backend to provide dynamically calculated
build dependencies, using {pep}`517`'s `get_requires_for_build_wheel` hook. This
hook will be called by pip, and dependencies it describes will also be installed
in the build environment. For example, newer versions of setuptools expose the
contents of `setup_requires` to pip via this hook.
Build-time requirement specifiers follow {pep}`508`, so it's possible to
reference packages with URLs. For example:
```toml
[build-system]
requires = ["setuptools @ git+https://github.com/pypa/setuptools.git@main"]
```
### Metadata Generation
```{versionadded} 19.0
```
Once the build environment has been created and populated with build-time
dependencies, `pip` will usually need metadata about a package (name, version,
dependencies, and more).
If {pep}`517`'s `prepare_metadata_for_build_wheel` hook is provided by the
build backend, that will be used to generate the packages' metadata. Otherwise,
a wheel will be generated (as described below) and the metadata contained
within such a wheel will be used.
### Wheel Generation
```{versionadded} 19.0
```
For generating a wheel, pip uses the {pep}`517` `build_wheel` hook that has
to be provided by the build backend. The build backend will generate a wheel,
which may involve compiling extension code written in C/C++ (or other
languages).
Wheels generated using this mechanism can be [cached](wheel-caching) for reuse,
to speed up future installations.
### Editable Installation
```{versionadded} 21.3
```
For performing editable installs, pip will use {pep}`660`
`build_wheel_for_editable` hook that has to be provided by the build backend.
The wheels generated using this mechanism are not cached.
```{admonition} Compatibility fallback
If this hook is missing on the build backend _and_ there's a `setup.py` file
in the project, pip will fallback to the legacy setup.py-based editable
installation.
This is considered a stopgap solution until setuptools adds support for
{pep}`660`, at which point this functionality will be removed; following pip's
regular {ref}`deprecation policy <Deprecation Policy>`.
```
### Backend Configuration
Build backends have the ability to accept configuration settings, which can
change the way the build is handled. These settings take the form of a
series of `key=value` pairs. The user can supply configuration settings
using the `--config-settings` command line option (which can be supplied
multiple times, in order to specify multiple settings).
The supplied configuration settings are passed to every backend hook call.
## Build output
It is the responsibility of the build backend to ensure that the output is
in the correct encoding, as described in {pep}`517`. This likely involves
dealing with [the same challenges as pip has for legacy builds](build-output).
## Fallback Behaviour
If a project does not have a `pyproject.toml` file containing a `build-system`
section, it will be assumed to have the following backend settings:
```toml
[build-system]
requires = ["setuptools>=40.8.0", "wheel"]
build-backend = "setuptools.build_meta:__legacy__"
```
If a project has a `build-system` section but no `build-backend`, then:
- It is expected to include `setuptools` and `wheel` as build requirements. An
error is reported if the available version of `setuptools` is not recent
enough.
- The `setuptools.build_meta:__legacy__` build backend will be used.
## Disabling build isolation
This can be disabled using the `--no-build-isolation` flag -- users supplying
this flag are responsible for ensuring the build environment is managed
appropriately, including ensuring that all required build-time dependencies are
installed, since pip does not manage build-time dependencies when this flag is
passed.
## Historical notes
As this feature was incrementally rolled out, there have been various notable
changes and improvements in it.
- setuptools 40.8.0 is the first version of setuptools that offers a
{pep}`517` backend that closely mimics directly executing `setup.py`.
- Prior to pip 18.0, pip only supports installing build requirements from
wheels, and does not support the use of environment markers and extras (only
version specifiers are respected).
- Prior to pip 18.1, build dependencies using `.pth` files are not properly
supported; as a result namespace packages do not work under Python 3.2 and
earlier.
|
