`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.

Since zc.buildout uses `pip` to install dists, most .egg in ./eggs and
./develop-eggs (in case of dists installed with zc.recipe.egg:custom)
are not actually eggs, but installed wheels with .dist-info format
which have been bundled into a .egg containing .dist-info metadata
folder as well as the actual package folder directly alongside.

Unlike actual eggs, such */*.dist-info bundles are not stepped into
by package_resources when the containing directory is add to the
environment, so each .egg bundle needs to be added individually.

Buildout already does this for bundles in the target directory of
egg installation, usually ./eggs, but e.g. in offline mode there
is no target directory and then already installed .egg bundles
are not detected.

So now every dist path is added to the environment individual,
including for paths where buildout looks for already installed
eggs but will not install eggs to, such as ./develop-eggs, and
also ./eggs in offline mode or when using zc.recipe.egg:custom
and the target is ./develop-eggs and ./eggs is such a scan-from
but don't-install-to path.

This is useful when using OS Python & eggs.

Useless for SlapOS.

Also show `pip install <url-for-tar.gz-of-master-branch-on-gitlab>`.

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

This commit discards such dists when they do not contain a setup.py
nor a pyproject.toml, as a good heuristic of whether they will be
installable or not.

Index constructed package indexes by all their parameters.

This option determines what paths zc.buildout will scan for already
installed distributions. It can be set to an empty value to enable
isolation. The special values 'sys.path', 'legacy' and 'zc.buildout'
expand to particular paths. The default is 'zc.buildout'.

The 'sys.path' mode simply expands to the currrent sys.path.

The 'legacy' mode reproduces the previous behavior of specifically
scanning the paths of the current zc.buildout distribution and its
dependencies using a weird ordering logic that bears no relation to the
order they appear in sys.path - which can produce unexpected results as
other distributions for zc.buildout, pip, wheel and setuptools may take
precedence over the ones currently running.

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

This mode is set to the default because it is closest 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 (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.

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.

If zc.buildout or its dependencies have pinned versions that do not
match the currently running versions, they are now installed in the
local eggs directory from scratch according to the pinned versions.

In offline mode this merely ensures that versions that satisfy the
requirements are already available. This is the case when the eggs
are already installed, or when the running versions are a match to
the pinned versions or the absence of a pinned version.

If after this matching versions of zc.buildout and its dependencies
are not located in the local eggs or develop-eggs directories, they
are copied there as was already the case before.

When generating an environment dict for subprocess calls to pip,
os.environ was accidentally modified despite efforts to copy it
and modify only the copy, as copy.copy(os.environ) is not enough.

[ci skip]

[skip ci]

[ci skip]

[ci skip]

[skip ci]

For example: `[versions:python_version <= "3.9"]`.
Fixes https://github.com/buildout/buildout/issues/621

[skip ci]

[skip ci]

in 3.11