[Distutils] build system abstraction PEP, take #2

[Robert Collins]

Updated with:
 - the pep 0508 reference
 - reviews from github
 - document --prefix and --root to develop.

-Rob

diff --git a/build-system-abstraction.rst b/build-system-abstraction.rst
index d36b7d5..762cd88 100644
--- a/build-system-abstraction.rst
+++ b/build-system-abstraction.rst
@@ -40,9 +40,9 @@ easy-install.
 As PEP-426 [#pep426]_ is draft, we cannot utilise the metadata format it
 defined. However PEP-427 wheels are in wide use and fairly well specified, so
 we have adopted the METADATA format from that for specifying distribution
-dependencies. However something was needed for communicating bootstrap
-requirements and build requirements - but a thin JSON schema is sufficient
-when overlaid over the new dependency specification PEP.
+dependencies and general project metadata. PEP-0508 [#pep508] provides a self
+contained language for describing a dependency, which we encapsulate in a thin
+JSON schema to describe bootstrap dependencies.

 Motivation
 ==========
@@ -123,6 +123,8 @@ PYTHON

         ${PYTHON} -m foo

+PYTHONPATH
+    Used to control sys.path per the normal Python mechanisms.

 Subcommands
 -----------
@@ -164,7 +166,7 @@ wheel -d OUTPUT_DIR

         flit wheel -d /tmp/pip-build_1234

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

@@ -173,6 +175,20 @@ develop
     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 root option is used to define an alternative root within which the
+    command should operate.
+
+    For instance::
+
+        flit develop --root /tmp/ --prefix /usr/local
+
+    Should install scripts within `/tmp/usr/local/bin`, even if the Python
+    environment in use reports that the sys.prefix is `/usr/` which would lead
+    to using `/tmp/usr/bin/`. Similar logic applies for package files etc.
+
 The build environment
 ---------------------

@@ -326,7 +342,7 @@ had.  Minutes from that were posted to the list [#minutes]_.
 This specification is a translation of the consensus reached there into PEP
 form, along with some arbitrary choices on the minor remaining questions.

-The basic heuristic for the design has to been to focus on introducing an
+The basic heuristic for the design has been to focus on introducing an
 abstraction without requiring development not strictly tied to the
 abstraction. Where the gap is small to improvements, or the cost of using the
 existing interface is very high, then we've taken on having the improvement as
@@ -343,7 +359,7 @@ CLI).
 The use of 'develop' as a command is because there is no PEP specifying the
 interoperability of things that do what 'setuptools develop' does - so we'll
 need to define that before pip can take on the responsibility for doing the
-'develop' step. Once thats done we can issue a successor PEP to this one.
+'develop' step. Once that's done we can issue a successor PEP to this one.

 The use of a command line API rather than a Python API is a little
 contentious. Fundamentally anything can be made to work, and the pip
@@ -410,8 +426,8 @@ References
 .. [#strformat] The Python string formatting syntax.
    (https://docs.python.org/3.1/library/string.html#format-string-syntax)

-.. [#dependencyspec] Dependency specification language PEP.
-   (https://github.com/pypa/interoperability-peps/pull/56)
+.. [#pep508] Dependency specification language PEP.
+   (https://www.python.org/dev/peps/pep-0508/)

 Copyright
 =========


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