[Distutils] abstract build system PEP update

[Robert Collins]

I've just pushed this up.

- provide space for config of other things in pypa.json via convention
- document PATH as a reliable variable
- capture the sdist discussion
- remove --root from develop: it isn't needed after discussion on IRC.

-Rob

diff --git a/build-system-abstraction.rst b/build-system-abstraction.rst
index a6e4712..56464f1 100644
--- a/build-system-abstraction.rst
+++ b/build-system-abstraction.rst
@@ -68,12 +68,15 @@ modelled on pip's existing use of the setuptools
setup.py interface.
 pypa.json
 ---------

-The file ``pypa.json`` acts as neutron configuration file for pip and other
+The file ``pypa.json`` acts as neutral configuration file for pip and other
 tools that want to build source trees to consult for configuration. The
 absence of a ``pypa.json`` file in a Python source tree implies a setuptools
 or setuptools compatible build system.

-The JSON has the following schema. Extra keys are ignored.
+The JSON has the following schema. Extra keys are ignored, which permits the
+use of ``pypa.json`` as a configuration file for other related tools. If doing
+that the chosen keys must be namespaced - e.g. ``flit`` with keys under that
+rather than (say) ``build`` or other generic keys.

 schema
     The version of the schema. This PEP defines version "1".  Defaults to "1"
@@ -130,6 +133,9 @@ Available environment variables
 These variables are set by the caller of the build system and will always be
 available.

+PATH
+    The standard system path.
+
 PYTHON
     As for format variables.

@@ -176,7 +182,7 @@ wheel -d OUTPUT_DIR

         flit wheel -d /tmp/pip-build_1234

-develop [--prefix PREFIX] [--root ROOT]
+develop [--prefix PREFIX]
     Command to do an in-place 'development' installation of the project.
     Stdout and stderr have no semantic meaning.

@@ -185,8 +191,11 @@ develop [--prefix PREFIX] [--root ROOT]
     that doing so will cause use operations like ``pip install -e foo`` to
     fail.

-    The prefix option is used for defining an alternative prefix within the
-    installation root.
+    The prefix option is used for defining an alternative prefix for the
+    installation. While setuptools has ``--root`` and ``--user`` options,
+    they can be done equivalently using ``--prefix``, and pip or other
+    tools that accept ``--root`` or ``--user`` options should translate
+    appropriately.

     The root option is used to define an alternative root within which the
     command should operate.
@@ -403,6 +412,13 @@ the setuptools shim is in use (with older pip
versions), or an environment
 marker ready pip is in use. The setuptools shim can take care of exploiting
 the difference older pip versions require.

+We discussed having an sdist verb. The main driver for this was to make sure
+that build systems were able to produce sdists that pip can build - but this is
+circular: the whole point of this PEP is to let pip consume such sdists
+reliably and without requiring an implementation of setuptools. Further, while
+most everyone agrees that encouraging sdists to be uploaded to PyPI, there
+wasn't complete consensus on that.
+
 References
 ==========



-- 
Robert Collins <rbtcollins at hpe.com>
Distinguished Technologist
HP Converged Cloud