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.

Needed for pip wheel + setuptools.wheel.Wheel.install_as_egg.

Now that extra-paths is sys.path by default instead of the legacy
value of the specific paths of zc.buildout and its dependencies,
some tests fail because some eggs in sys.path that were previously
not in extra-paths were instead found on sys.path by package index's
search_path and subsequently installed in ./eggs, whereas they are
now directly seen as already installed at their original location.

Allow DEVELOP_DIST distributions found on sys.path by package index
when they contain a setup.py or pyproject.toml, as a good heuristic
of whether they will be installable or not.

The package index considers may yield dists found on its local
search_path - sys.path by default - in addition to its index_url.

This commit discards such dists as they may not be installable.

Index constructed package indexes by all their parameters.

This option determines what paths zc.buildout will scan for already
installed distributions. This defaults to sys.path and can be set to
an empty value to enable isolation. The special value 'legacy' yields
the previous behavior of scanning specifically the paths of the current
zc.buildout distribution and its dependencies.

In bootstrap we potentially copy eggs from the working set to ./eggs.
We then reconstruct the same working set using the moved locations.

This commits ensures we keep a correct working set order throughout
and that we avoid activating unintended dists.

If a dist in the computed working set is at a location shared with
other dists - such as site-packages - then when generating scripts
these other packages may overshadow the next items on the sys.path
and result in importing a different version than the one installed
and intended by buildout.

To avert this, a sort of the working set was introduced at various
points just before generating a script.

However, that sort put the paths referenced from an `.egg-link` in
./develop-eggs first. This is truly problematic because dists from
site-packages which are not eggs - e.g. dists installed with pip -
can become referenced as `.egg-link` during buildout bootstrap and
the sort then causes site-packages to be one of the first items in
sys.path.

In particular when running buildout bootstrap from a venv in which
zc.buildout was installed by pip, if any one of zc.buildout or its
dependencies from the venv meets the version requirements, then it
can cause the generated bin/buildout to import the dists only from
the venv's site-packages, even when some do not meet requirements.

To fix this, the sort now puts the dists from `./eggs` first as we
know their locations contain only a single dist, and then puts the
dists from ./develop-eggs which have locations inside the buildout
directory before the others.

The previous sort was also activating all the dists from the paths
of the already activated dists.

Note that this also means that any working set must be manipulated
with care in general to avoid activating unintended dists from the
locations of the already activated dists.

Replace `pkg_resources.Environment(ws.entries).best_match(req, ws)`
with `ws.find(req)`.

The first already starts by calling `ws.find(req)` to attempt to find
an already activated dist in the working set, but if none is found it
then proceeds to scan through the entries of the environment - i.e.
the locations of the directly-requested distributions, `ws.entries` -
to activate a dist at these locations if one matches.

This is problematic when directly-requested distributions are found in
a location shared by multiple dists, such as site-packages: this gives
that location precedence over the normal order of locations scanned by
easy_install, and can result in undesired versions being chosen over
versions available in ./eggs or in ./develop-eggs. The random aspect
of this is also problematic, as the order of paths considered will
depend on the order of the directly-requested distributions and where
they are found.

When specifying an alternate URL as fallback, the main URL is always
used for both downloading & uploading from/to networkcache.

If slapos.libnetworkcache is importable, install it in bootstrap and
in buildout upgrade - the places where bin/buildout is (re)generated
- as though it were a dependency of zc.buildout.

This is a hack to propagate libnetworkcache as a soft dependency.

Like for URL that contain credentials, we still skip auth challenge
because it's faster and:
- we only support one auth scheme (basic)
- netrc provides no way to specify realms, which seem anyway to be
  less and less used (https://stackoverflow.com/q/69303610 reports
  that recent browsers don't display them anymore)

See merge request nexedi/slapos.buildout!25

This retries with the alternate URL in case of HTTPError with the main
one.

Used by slapos.recipe.build:download* and slapos.recipe.cmmi recipes.

- Py3: stop using legacy API of urllib.request and
       fix download of http(s) URLs containing user:passwd@
- Py2: avoid OOM when downloading huge files

This is implemented as a method in case we want to make it configurable
via [buildout].

An optimization is to avoid temporary file when possible: a rename
(or hard link) is not always possible (different mount points).

Another one is to not check md5sum twice when using cache file.

Fall-back mode is ignored if an MD5 checksum is given.

In case of checksum mismatch for a cached path, remove it and
download again, mainly to cover the following cases:
- the url content changes and the user updates the checksum
- buildout killed while downloading directly to cache
  (see above optimization)
- shutil.copyfile is interrupted

We want two identical sections at different URL to be able to produce
same signature. This feature is useful for slapos.recipe.cmmi's
shared parts.

This commit may fixup "Support ${:_profile_base_location_}." but is
purposefuly kept separate because it concerns parts signatures which
are an orthogonal feature.

Use a special .pydistutils.cfg in a temporary HOME directory for
the duration of the pip wheel run to prevent build dependencies
specified in a setup_requires from being installed on the fly
without respecting pinned versions.

When there is no pinned version for zc.buildout itself, buildout
adds a ">=<current-version>" requirement to prevent accidental
downgrading. If the current version has a local version label,
this produced an invalid version specifier. To fix this, only
the public part of the current version is used.

Now that we use `pip wheel` + `Wheel.install_as_egg` to produce
genuine eggs, we don't need to workaround the fact that we have
not-actually-egg `.egg` bundles anymore.

If we still do need to allow for non-eggs being installed in `~/.eggs`,
via extensions or others, we should revert this.
See https://github.com/buildout/buildout/pull/352

`pip install <package>` produces a `<package-name>` package folder
and a `<package-name>.dist-info` metadata folder, which is another
format than eggs. Then buildout bundles both folders into a parent
folder `<package.egg>` and tries to act as though it were an egg.

Instead, use `pip wheel` to produce a wheel - which `pip install`
does internally anyway - and `setuptools.Wheel.install_as_egg` to
produce a genuine egg.

This is much cleaner: it consistently produces genuine eggs instead
of sometimes true eggs, sometimes `.dist-info` bundles depending on
whether `pip install` is called or the package was installed from a
`.whl` or `.egg` archive directly.

The only downside it this requires setuptools >= 38.2.3.

Before this, += and -= worked well when applied to keys defined in the
current section or in a section of the same name inherited from a file
extended by the current file, but not to keys inherited from another
section using macro extension <=, because <= substitution happens later
and all the += and -= are already resolved.

e.g.:

```
[macro]
a = 1

[part]
<= macro
a += 2
```

was equivalent to

```
[part]
a = 1
a = 2
```

instead of

```
[part]
a = 1
a += 2
```

Now a partial and brittle support for this is enabled by postponing
+= and -= resolution until <= substitution happens when the current
section contains a <= extension. But this is not guaranteed: if the
current section is overloaded in another file extending the current
one, then += and -= resolution will happend then, before <=.

A consistent solution would be to unify the implementation of
extends= and <= and update sections by taking both into account,
instead of updating based only on extends and computing <= later,
leading to inconsistencies. This could be achieved e.g. by computing
section updates on demand during substitution.
Co-authored-by: Xavier Thompson <xavier.thompson@nexedi.com>

Before this, += and -= worked correctly when applied to a key defined
in a file extended by the current file, but not when the key was in
the same file.

e.g.:

```
[part]
a = this case is
```

```
[buildout]
extends = a.cfg

[part]
a += ok
b = this case is
b += not-ok
```
Co-authored-by: Xavier Thompson <xavier.thompson@nexedi.com>

Before this, sys.exit(1) was called to terminate the program directly.

By default pip installs build dependencies (e.g. setuptools, poetry)
in a temporary folder and temporarily adds it to sys.path in order
to proceed to build the distribution. But we want all distributions
to be installed with buildout and respect pinned versions, so we aim
to prevent pip from installing build dependencies.

Instead, we will install the build dependencies first and pass them
explicitly to zc.recipe.egg via the setup-eggs option.

This commit prevents pip from installing the build dependencies listed
by the `build-system.requires` key in the pyproject.toml file.

It may prevent pip from installing PEP 517 dynamic build dependencies
or setuptools' setup_requires dependencies.
See https://peps.python.org/pep-0517/#get-requires-for-build-wheel

While invoke setup.py certain eggs (like scikit-learn) launch
cetain custom builds (for cython) using subprocess and sys.executable.

This commit aims to preserve the sys.path over the runs, even if an
egg is using subprocess with the same python to build a component of
the egg.

Now specified patches are automatically applied on required eggs as well.

- Support on the fly patches in zc.recipe.egg by ``EGGNAME-patches``,
  ``EGGNAME-patch-options``, ``EGGNAME-patch-binary`` (or
  ``patch-binary``) and ``EGGNAME-patch-revision`` options.

- Support on the fly patches in zc.recipe.egg:custom by ``patches``,
  ``patch-options``, ``patch-binary`` and ``patch-revision`` options.
  (options ``EGGNAME-*`` are also supported as well).

Currently only zc.recipe.egg:custom supports setting environment
variables, and zc.recipe.egg:develop does not.

My motivation for allowing setting environment in :develop is
wendelin.core

    https://lab.nexedi.cn/nexedi/slapos/blob/b5faab3b/component/wendelin.core/buildout.cfg

There we have [wendelin.core] part which installs released egg from
pypi, and [wendelin.core-dev] part which installs wendelin.core from
its latest git version via zc.recipe.egg:develop .

The problem is, wendelin.core for setup.py to work, needs git available,
and with slapos we usually don't have git available on base system, so
we build it by our own and do something like

    [wendelin.core-dev]
    recipe = zc.recipe.egg:develop
    environment = wendelin.core-dev-env

    [wendelin.core-dev-env]
    # wendelin.core-dev needs git to build
    PATH = ${git:location}/bin:%(PATH)s

and the problem is environment does not currently work for
zc.recipe.egg:develop, and thus git is not found -> build fails.

~~~~

In order to support environment in :develop, we just move environment
setting/restoring bits from Custom to Base, and provide Base.install() which
uses this bits. Custom & Develop .install() becomes ._install() which gets
hooked into Base.install() .

I've tested the patch only manually, because currently automated tests are
broken in a lot of places for slapos.buildout and zc.recipe.egg .

/cc @kazuhiko, @Tyagov

To be dropped once all buildout in the wild are able to upgrade to a
version that supports new names in expression of conditional sections
(see previous commit).