Look up `dub.selections.json` files in parent directories too (#2272) ...

* Look up `dub.selections.json` files in parent directories too

In case the root package directory doesn't contain a `dub.selections.json`
file, look in parent directories too and load the first (deepest) one.

This allows using a 'central' `dub.selections.json` file for a repository
containing multiple dub projects, making it automatically apply to all
builds in that source tree if located in the repository root directory
(unless a local `dub.selections.json` overrides it).

Such an 'inherited' selections file is never mutated when running dub for
a nested project, i.e., changes are always saved to a *local*
`dub.selections.json` file.

ToolchainRequirements: Handle '*' while parsing PackageRecipe ...

PR 2926 added the possibility that '*' is serialized to PackageRecipe
instead of '>=0.0.0' but we need the parser to handle it.

Introduce readText and make stripUTF8BOM private

Make 'Dependency.init' invalid and align Any/Invalid property ...

VersionRange has Invalid and Any while Dependency has invalid and any.
One has to go, and it's going to be Dependency's.
In addition, make sure that the 'init' state of Dependency is a known state.

Remove PackageName alias this to toString ...

The alias this was originally added to make the transition
less painful, however due to an overload resolution bug,
it makes it harder at the moment, as thje compiler prefers
calling the deprecated `string` overloads over the
`in PackageName` ones. So remove it and a few hacks along
the way.

Adapt dub.recipe.json to PackageName API

Adapt dub.recipe.sdl to PackageName API

Expand selections file handling to handle new versions ...

Up until now, the selections file has had a `fileVersion` in it,
but that number was always stuck to 1.
In order to make it possible to handle more than one version,
a bit of scaffolding needs to happen in the config parser.
This lays the ground for a version 2 of the selections file.

Introduce PackageName, to fully type a package name ...

Package names being passed around in the Dub codebase are string,
which is problematic as it suffers from validation / semantic issues.
Validation because we cannot impose restrictions on characters
or length easily, and semantic because some functions expect a main
package while some would accept a subpackage. Introducing a type
will remedy both those issues.

Deprecate unused getSubPackagePath ...

While looking at the subpackage code, I was wondering
why more places didn't call getSubPackagePath instead
of getSubPackageName, and that is because subpackages
can only be one level deep.

Trivial: Deprecate string overload of readPackageRecipe ...

To be consistent with the rest of Dub, use NativePath.

Change platform dependency to use a VersionRange ...

Note that this is a breaking change for library users.
It changes the platform dependency to only accept version ranges,
instead of any dependency. The end-users already could only write
VersionRange in there, the type was just too wide.

Move dmd version parser to packagerecipe ...

This module is the only one that uses it, so instead of having
it in a place that looks correct but where it is not used,
move it to packagerecipe and make it private.

Trivial: Reduce import scope in dub.recipe.selection

Update isBasicType usage for Phobos PR 8838 ...

https://github.com/dlang/phobos/pull/8838

Add unittest to test collection of C sources and headers

Merge remote-tracking branch 'upstream/stable' into merge_stable

fix #2587

fix typo(s)

replace std.variant with std.sumtype (#2550) ...

Variant is quite big and runtime heavy, with sumtype we already cover
wrong type cases at compile time.

Reduce dependency on `std.file` (#2547)

Move foreign code from global scope to dub.internal. ...

Avoids conflicting with the actual dub packages when working with dub as a library. Also, even if just by convention, it ensures that dependent code doesn't rely on this code as a public API.

Unify reading and writing files under a single API ...

This removes the range API and instead uses Appender,
while using a limited and centralized set of functions
to read/write from files.
The end goal is to permit dependency injection,
which is a pre-requisite to extending the test-suite.

Do not use Phobos' sumtype, use dyaml's versioned one ...

So that we can compile with older versions of the frontend,
currently v2.097 instead of v2.098.

Minor: Align dub.recipe.selection style with dub.recipe.packagerecipe ...

During review of the PR that switched PackageRecipe parsing to use Configy,
WebFreak pointed out that having an internal, private structure used for
parsing YAML field was preferable to having it at module level.
This aligns the names and the approach used with the one in PackageRecipe.

Trivial: Fix typo in documentation

Use configy library to parse dub.json file ...

This will provide a vastly superior UX to the users:
- They will be warned about typos;
- The type information provided will be more accurate and always include file/line infos
  (e.g. no more 'Invalid SemVer versions');
- We can expose a better recipe struct to library users on the long run,
  by separating the actual data DUB uses from what it reads;
- We can be more descriptive about errors / intent, for example by using `SetInfo`;

Trivial: Remove test about the internals of Dependency ...

Now that Dependency is a proper SumType, this can never happen.

Integrate `dependencyBuildSettings` into dependencies ...

Because those are specified in `dependencies`,
they should be stored alongside them.
Unfortunately this will slihtly increase memory usage in the common case,
but unlikely to a point where it would be problematic.

This is technically a breaking change as a field is getting removed,
however this struct has been manipulated a few times in breaking ways,
and it's unlikely `dependencyBuildSettings` is being used outside of dub,
given how recent it is and how narrow its usage is.
However, as `dependencies` is likely to be widely used, a compatibility
type and an `alias this` are provided not to break client code.

Trivial: Add attributes and documentation to PackageRecipe ...

While the attributes aren't used yet, they are self-descriptive,
and they improve code readability.