diff --git a/pep-0517.txt b/pep-0517.txt index 950470a46..0854bf79b 100644 --- a/pep-0517.txt +++ b/pep-0517.txt @@ -527,17 +527,80 @@ The new restrictions for sdists built by PEP 517 backends are: - The source tree contained in an sdist is expected to include the ``pyproject.toml`` file. +==================== + Evolutionary notes +==================== + +A goal here is to make it as simple as possible to convert old-style +sdists to new-style sdists. (E.g., this is one motivation for +supporting dynamic build requirements.) The ideal would be that there +would be a single static ``pyproject.toml`` that could be dropped into any +"version 0" VCS checkout to convert it to the new shiny. This is +probably not 100% possible, but we can get close, and it's important +to keep track of how close we are... hence this section. + +A rough plan would be: Create a build system package +(``setuptools_pypackage`` or whatever) that knows how to speak +whatever hook language we come up with, and convert them into calls to +``setup.py``. This will probably require some sort of hooking or +monkeypatching to setuptools to provide a way to extract the +``setup_requires=`` argument when needed, and to provide a new version +of the sdist command that generates the new-style format. This all +seems doable and sufficient for a large proportion of packages (though +obviously we'll want to prototype such a system before we finalize +anything here). (Alternatively, these changes could be made to +setuptools itself rather than going into a separate package.) + +But there remain two obstacles that mean we probably won't be able to +automatically upgrade packages to the new format: + +1) There currently exist packages which insist on particular packages + being available in their environment before setup.py is + executed. This means that if we decide to execute build scripts in + an isolated virtualenv-like environment, then projects will need to + check whether they do this, and if so then when upgrading to the + new system they will have to start explicitly declaring these + dependencies (either via ``setup_requires=`` or via static + declaration in ``pyproject.toml``). + +2) There currently exist packages which do not declare consistent + metadata (e.g. ``egg_info`` and ``bdist_wheel`` might get different + ``install_requires=``). When upgrading to the new system, projects + will have to evaluate whether this applies to them, and if so they + will need to stop doing that. + + +================== + Rejected options +================== + +* We discussed making the wheel and sdist hooks build unpacked directories + containing the same contents as their respective archives. In some cases this + could avoid the need to pack and unpack an archive, but this seems like + premature optimisation. It's advantageous for tools to work with archives + as the canonical interchange formats (especially for wheels, where the archive + format is already standardised). Close control of archive creation is + important for reproducible builds. And it's not clear that tasks requiring an + unpacked distribution will be more common than those requiring an archive. +* We considered an extra hook to copy files to a build directory before invoking + ``build_wheel``. Looking at existing build systems, we found that passing + a build directory into ``build_wheel`` makes more sense for many tools than + pre-emptively copying files into a build directory. + =================================== - Comparison to competing proposals + Appendix A: Comparison to PEP 516 =================================== -The primary difference between this and competing proposals (in -particular, PEP 516) is +:pep:`516` is a competing proposal to specify a build system interface, which +has now been rejected in favour of this PEP. The primary difference is that our build backend is defined via a Python hook-based interface rather than a command-line based interface. -We do *not* expect that this will, by itself, intrinsically reduce the -complexity calling into the backend, because build frontends will +This appendix documents the arguments advanced for this PEP over PEP 516. + +We do *not* expect that specifying Python hooks rather than command line +interfaces will, by itself, reduce the +complexity of calling into the backend, because build frontends will in any case want to run hooks inside a child -- this is important to isolate the build frontend itself from the backend code and to better control the build backends execution environment. So under both @@ -861,66 +924,6 @@ above, there are a few other differences in this proposal: but these aren't normative anyway. -==================== - Evolutionary notes -==================== - -A goal here is to make it as simple as possible to convert old-style -sdists to new-style sdists. (E.g., this is one motivation for -supporting dynamic build requirements.) The ideal would be that there -would be a single static ``pyproject.toml`` that could be dropped into any -"version 0" VCS checkout to convert it to the new shiny. This is -probably not 100% possible, but we can get close, and it's important -to keep track of how close we are... hence this section. - -A rough plan would be: Create a build system package -(``setuptools_pypackage`` or whatever) that knows how to speak -whatever hook language we come up with, and convert them into calls to -``setup.py``. This will probably require some sort of hooking or -monkeypatching to setuptools to provide a way to extract the -``setup_requires=`` argument when needed, and to provide a new version -of the sdist command that generates the new-style format. This all -seems doable and sufficient for a large proportion of packages (though -obviously we'll want to prototype such a system before we finalize -anything here). (Alternatively, these changes could be made to -setuptools itself rather than going into a separate package.) - -But there remain two obstacles that mean we probably won't be able to -automatically upgrade packages to the new format: - -1) There currently exist packages which insist on particular packages - being available in their environment before setup.py is - executed. This means that if we decide to execute build scripts in - an isolated virtualenv-like environment, then projects will need to - check whether they do this, and if so then when upgrading to the - new system they will have to start explicitly declaring these - dependencies (either via ``setup_requires=`` or via static - declaration in ``pyproject.toml``). - -2) There currently exist packages which do not declare consistent - metadata (e.g. ``egg_info`` and ``bdist_wheel`` might get different - ``install_requires=``). When upgrading to the new system, projects - will have to evaluate whether this applies to them, and if so they - will need to stop doing that. - - -================== - Rejected options -================== - -* We discussed making the wheel and sdist hooks build unpacked directories - containing the same contents as their respective archives. In some cases this - could avoid the need to pack and unpack an archive, but this seems like - premature optimisation. It's advantageous for tools to work with archives - as the canonical interchange formats (especially for wheels, where the archive - format is already standardised). Close control of archive creation is - important for reproducible builds. And it's not clear that tasks requiring an - unpacked distribution will be more common than those requiring an archive. -* We considered an extra hook to copy files to a build directory before invoking - ``build_wheel``. Looking at existing build systems, we found that passing - a build directory into ``build_wheel`` makes more sense for many tools than - pre-emptively copying files into a build directory. - =========== Copyright ===========