mirror of https://github.com/pypa/pip
Document PEP 518 support
This commit is contained in:
parent
9f942d00fc
commit
432edcbbc0
|
@ -72,14 +72,16 @@ Build System Interface
|
||||||
======================
|
======================
|
||||||
|
|
||||||
Pip builds packages by invoking the build system. Presently, the only supported
|
Pip builds packages by invoking the build system. Presently, the only supported
|
||||||
build system is ``setuptools``, but future developments to the Python packaging
|
build system is ``setuptools``, but in the future, pip will support `PEP517`_
|
||||||
infrastructure are expected to include support for other build systems. As
|
which allows projects to specify an alternative build system in a
|
||||||
well as package building, the build system is also invoked to install packages
|
``pyproject.toml`` file. As well as package building, the build system is also
|
||||||
direct from source.
|
invoked to install packages direct from source. This is handled by invoking
|
||||||
|
the build system to build a wheel, and then installing from that wheel. The
|
||||||
|
built wheel is cached locally by pip to avoid repeated identical builds.
|
||||||
|
|
||||||
The interface to the build system is via the ``setup.py`` command line script -
|
The current interface to the build system is via the ``setup.py`` command line
|
||||||
all build actions are defined in terms of the specific ``setup.py`` command
|
script - all build actions are defined in terms of the specific ``setup.py``
|
||||||
line that will be run to invoke the required action.
|
command line that will be run to invoke the required action.
|
||||||
|
|
||||||
Setuptools Injection
|
Setuptools Injection
|
||||||
~~~~~~~~~~~~~~~~~~~~
|
~~~~~~~~~~~~~~~~~~~~
|
||||||
|
@ -111,6 +113,54 @@ unexpected byte sequences to Python-style hexadecimal escape sequences
|
||||||
(``"\x80\xff"``, etc). However, it is still possible for output to be displayed
|
(``"\x80\xff"``, etc). However, it is still possible for output to be displayed
|
||||||
using an incorrect encoding (mojibake).
|
using an incorrect encoding (mojibake).
|
||||||
|
|
||||||
|
PEP 518 Support
|
||||||
|
~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
Pip supports projects declaring dependencies that are required at install time
|
||||||
|
using a ``pyproject.toml`` file, in the form described in `PEP518`_. When
|
||||||
|
building a project, pip will install the required dependencies locally, and
|
||||||
|
make them available to the build process.
|
||||||
|
|
||||||
|
As noted in the PEP, the minimum requirements for pip to be able to build a
|
||||||
|
project are::
|
||||||
|
|
||||||
|
[build-system]
|
||||||
|
# Minimum requirements for the build system to execute.
|
||||||
|
requires = ["setuptools", "wheel"]
|
||||||
|
|
||||||
|
``setuptools`` and ``wheel`` **must** be included in any ``pyproject.toml``
|
||||||
|
provided by a project - pip will assume these as a default, but will not add
|
||||||
|
them to an explicitly supplied list in a project supplied ``pyproject.toml``
|
||||||
|
file. Once `PEP517`_ support is added, this restriction will be lifted and
|
||||||
|
alternative build tools will be allowed.
|
||||||
|
|
||||||
|
When making build requirements available, pip does so in an *isolated
|
||||||
|
environment*. That is, pip does not install those requirements into the user's
|
||||||
|
``site-packages``, but rather installs them in a temporary directory which it
|
||||||
|
adds to the user's ``sys.path`` for the duration of the build. This ensures
|
||||||
|
that build requirements are handled independently of the user's runtime
|
||||||
|
environment. For example, a project that needs a recent version of setuptools
|
||||||
|
to build can still be installed, even if the user has an older version
|
||||||
|
installed (and without silently replacing that version).
|
||||||
|
|
||||||
|
In certain cases, projects (or redistributors) may have workflows that
|
||||||
|
explicitly manage the build environment. For such workflows, build isolation
|
||||||
|
can be problematic. If this is the case, pip provides a
|
||||||
|
``--no-build-isolation`` flag to disable build isolation. Users supplying this
|
||||||
|
flag are responsible for ensuring the build environment is managed
|
||||||
|
appropriately.
|
||||||
|
|
||||||
|
The current implementation of `PEP518`_ in pip requires that any dependencies
|
||||||
|
specified in ``pyproject.toml`` are available as wheels. This is a technical
|
||||||
|
limitation of the implementation - dependencies only available as source would
|
||||||
|
require a build step of their own, which would recursively invoke the `PEP518`_
|
||||||
|
dependency installation process. The potentially unbounded recursion involved
|
||||||
|
was not considered acceptable, and so installation of build dependencies from
|
||||||
|
source has been disabled until a safe resolution of this issue has been found.
|
||||||
|
|
||||||
|
.. _PEP517: http://www.python.org/dev/peps/pep-0517/
|
||||||
|
.. _PEP518: http://www.python.org/dev/peps/pep-0518/
|
||||||
|
|
||||||
Future Developments
|
Future Developments
|
||||||
~~~~~~~~~~~~~~~~~~~
|
~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
|
Loading…
Reference in New Issue