From 7b73a44589021152193f0f644fa26b8e7ba99efb Mon Sep 17 00:00:00 2001 From: Jean Abou Samra Date: Thu, 23 Nov 2023 00:48:18 +0100 Subject: [PATCH] PEP 517: Final editing to fit the PUG --- .../specifications/build-system-interface.rst | 54 +++++++++++-------- 1 file changed, 31 insertions(+), 23 deletions(-) diff --git a/source/specifications/build-system-interface.rst b/source/specifications/build-system-interface.rst index 781b8d797..badc6f45a 100644 --- a/source/specifications/build-system-interface.rst +++ b/source/specifications/build-system-interface.rst @@ -1,3 +1,5 @@ +.. _build-system-interface: + ====================== Build system interface ====================== @@ -6,6 +8,11 @@ This specifications describes a standardized interface for installation tools like ``pip`` to interact with package source trees and source distributions. +The project's chosen build system is read from the :ref:`[build-system] +table ` of the ``pyproject.toml`` file. +The ``requires`` key defines the build requirements and the +``build-backend`` key specifies a build backend object to use. + Terminology =========== @@ -27,9 +34,10 @@ lxml==2.4.0``, pip is acting as an integration frontend. Build requirements ================== -This PEP places a number of additional requirements on the "build requirements" -section of ``pyproject.toml``. These are intended to ensure that projects do -not create impossible to satisfy conditions with their build requirements. +This specification places a number of requirements on the ``requires`` +key from the ``[build-system]`` section of ``pyproject.toml``. These are +intended to ensure that projects do not create impossible to satisfy +conditions with their build requirements. - Project build requirements will define a directed graph of requirements (project A needs B to build, B needs C and D, etc.) This graph MUST NOT @@ -53,9 +61,11 @@ avoiding external build dependencies (usually by vendoring them). Build backend interface ======================== -The build backend object is expected to have attributes which provide -some or all of the following hooks. The common ``config_settings`` -argument is described after the individual hooks. +The build backend object is looked up according to the ``build-backend`` +field of the ``[build-system]`` table. It is expected to have attributes +which provide some or all of the following hooks. The common +``config_settings`` argument is described after the individual hooks. + Mandatory hooks --------------- @@ -124,6 +134,8 @@ for a wheel, it should fall back to building a wheel directly. The backend does not need to define this exception type if it would never raise it. + + Optional hooks -------------- @@ -135,9 +147,10 @@ get_requires_for_build_wheel def get_requires_for_build_wheel(config_settings=None): ... -This hook MUST return an additional list of strings containing :pep:`508` -dependency specifications, above and beyond those specified in the -``pyproject.toml`` file, to be installed when calling the ``build_wheel`` or +This hook MUST return an additional list of strings containing +:ref:`dependency specifiers `, above and +beyond those specified in the ``pyproject.toml`` file, to be +installed when calling the ``build_wheel`` or ``prepare_metadata_for_build_wheel`` hooks. Example:: @@ -165,7 +178,7 @@ directory, and a build frontend MUST preserve, but otherwise ignore, such files; the intention here is that in cases where the metadata depends on build-time decisions, the build backend may need to record these decisions in -some convenient format for re-use by the actual wheel-building step. +some convenient format for reuse by the actual wheel-building step. This must return the basename (not the full path) of the ``.dist-info`` directory it creates, as a unicode string. @@ -190,16 +203,8 @@ dependency specifications, above and beyond those specified in the If not defined, the default implementation is equivalent to ``return []``. -.. note:: Editable installs +.. todo:: Import :pep:`660` (editable installs) here. - This PEP originally specified another hook, ``install_editable``, to do an - editable install (as with ``pip install -e``). It was removed due to the - complexity of the topic, but may be specified in a later PEP. - - Briefly, the questions to be answered include: what reasonable ways existing - of implementing an 'editable install'? Should the backend or the frontend - pick how to make an editable install? And if the frontend does, what does it - need from the backend to do so. Config settings --------------- @@ -327,7 +332,7 @@ environment that meets the above criteria. For example, simply installing all build-requirements into the global environment would be sufficient to build any compliant package -- but this would be sub-optimal for a number of reasons. This section contains -non-normative advice to frontend implementors. +non-normative advice to frontend implementers. A build frontend SHOULD, by default, create an isolated environment for each build, containing only the standard library and any @@ -421,13 +426,16 @@ the locations in ``backend-path``. History ======= -The following changes were made to this PEP after the initial reference +This specification was originally proposed and approved as :pep:`517`. + +The following changes were made to this specification after the initial reference implementation was released in pip 19.0. * Cycles in build requirements were explicitly prohibited. * Support for in-tree backends and self-hosting of backends was added by the introduction of the ``backend-path`` key in the ``[build-system]`` table. -* Clarified that the ``setuptools.build_meta:__legacy__`` :pep:`517` backend is +* Clarified that the ``setuptools.build_meta:__legacy__`` backend is an acceptable alternative to directly invoking ``setup.py`` for source trees - that don't specify ``build-backend`` explicitly. + that don't specify ``build-backend`` explicitly. (This clarification + is now in the :ref:`pyproject.toml specification `.)