From 432edcbbc0c5663fca9c7f21aa4090a348f4704a Mon Sep 17 00:00:00 2001 From: Paul Moore Date: Wed, 14 Mar 2018 10:04:47 +0000 Subject: [PATCH] Document PEP 518 support --- docs/reference/pip.rst | 64 +++++++++++++++++++++++++++++++++++++----- 1 file changed, 57 insertions(+), 7 deletions(-) diff --git a/docs/reference/pip.rst b/docs/reference/pip.rst index c5a1201f5..e2bed8ec7 100644 --- a/docs/reference/pip.rst +++ b/docs/reference/pip.rst @@ -72,14 +72,16 @@ Build System Interface ====================== Pip builds packages by invoking the build system. Presently, the only supported -build system is ``setuptools``, but future developments to the Python packaging -infrastructure are expected to include support for other build systems. As -well as package building, the build system is also invoked to install packages -direct from source. +build system is ``setuptools``, but in the future, pip will support `PEP517`_ +which allows projects to specify an alternative build system in a +``pyproject.toml`` file. As well as package building, the build system is also +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 - -all build actions are defined in terms of the specific ``setup.py`` command -line that will be run to invoke the required action. +The current interface to the build system is via the ``setup.py`` command line +script - all build actions are defined in terms of the specific ``setup.py`` +command line that will be run to invoke the required action. 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 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 ~~~~~~~~~~~~~~~~~~~