[feat] Add 'zc.buildout' mode to 'extra-paths'

This mode is similar to 'legacy' mode as it uses only the paths of
the currently running distributions for zc.buildout and dependencies,
but unlike 'legacy' mode it respects the order in which these appear
in sys.path, avoiding unexpected results.

This is now set to the default because it is closer to 'legacy' mode
and because it has a nice property: running in succession

  `buildout buildout:extra-paths= bootstrap` (1)
  `bin/buildout` (2)

will result in the (1) installing zc.buildout and its dependencies
in /eggs in isolation from the environment, and (2) using only the
paths of these in /eggs, i.e. continuing to operate in isolation,
even without setting extra-paths explictly.

Before this change, (2) would have still used  the whole `sys.path`
unless extra-paths was set otherwise.

With this change, we can remove 'extra-paths=legacy' in the tests
that previously required it.

doc/getting-started.rst

@@ -113,7 +113,6 @@ update our Buildout configuration to add a ``bobo`` part:
 
   [buildout]
   parts = bobo
-  extra-paths = legacy
 
   [bobo]
   recipe = zc.recipe.egg
@@ -427,7 +426,6 @@ where you list them, as in:
    >>> prefix = """
    ... [buildout]
    ... parts = bobo
-   ... extra-paths = legacy
    ... """
    >>> with open('buildout.cfg', 'w') as f:
    ...     _ = f.write(prefix)
@@ -460,7 +458,6 @@ The more common way to pin a version is using a ``versions`` section:
 
   [buildout]
   parts = bobo server
-  extra-paths = legacy
 
   [bobo]
   recipe = zc.recipe.egg

doc/topics/optimizing.rst

@@ -21,7 +21,6 @@ Buildout work better:
     >>> write("""\
     ... [buildout]
     ... parts = bobo
-    ... extra-paths = legacy
     ... [bobo]
     ... recipe=zc.recipe.egg
     ... eggs=bobo

doc/topics/variables-extending-and-substitutions.rst

@@ -248,7 +248,6 @@ is typically used to set up a shared egg or cache directory, as in:
     >>> write("""\
     ... [buildout]
     ... parts = bobo
-    ... extra-paths = legacy
     ... [bobo]
     ... recipe=zc.recipe.egg
     ... eggs=bobo

src/zc/buildout/buildout.py

@@ -374,7 +374,7 @@ _buildout_default_options = _annotate_section({
     'develop-eggs-directory': 'develop-eggs',
     'eggs-directory': 'eggs',
     'executable': sys.executable,
-    'extra-paths': 'sys.path',
+    'extra-paths': 'zc.buildout',
     'find-links': '',
     'install-from-cache': 'false',
     'installed': '.installed.cfg',
@@ -626,6 +626,21 @@ class Buildout(DictMixin):
             # special case: sys.path
             extra_paths = sys.path
             options['extra-paths'] = ' '.join(extra_paths)
+        elif extra_paths == 'zc.buildout':
+            # special case: only zc.buildout and its dependencies
+            # but in the order they appear in sys.path, unlike legacy
+            old_extra_paths = zc.buildout.easy_install.extra_paths(
+              [d.location for d in pkg_resources.working_set])
+            try:
+                buildout_and_setuptools_dists = set(
+                    zc.buildout.easy_install.install(['zc.buildout'], None,
+                        check_picked=False))
+            finally:
+                zc.buildout.easy_install.extra_paths(old_extra_paths)
+            extra_paths = [
+                d.location for d in pkg_resources.working_set
+                if d in buildout_and_setuptools_dists]
+            options['extra-paths'] = ' '.join(extra_paths)
         else:
             extra_paths = extra_paths.split()
         zc.buildout.easy_install.extra_paths(extra_paths)