Demote TargetString document TargetSelector. Reorder TargetString
section. Rename use of userTarget naming convention to match new type
names.

Drop use of term "build" from error messages since these errors will
appear for many commands, not just the build command.

Rename UserBuildTarget to TargetString, to match the previous renaming
of BuildTarget to TargetSelector. Also rename the corresponding
functions.

So there's now just one error type rather than two, and errors are
returned rather than reported directly.

Now that we have squashed together the two phases of the target
selector parsing and resolving, we also want to do the same with the
error reporting for the two phases. And to make it possible to customise
the error messages for different commands we have the reporting being
done explicitly and separately.

This means that in the majority of cases we can report errors in the
command line arguments prior to running the solver. This is a much
better state of affairs. Previously we had to wait many seconds (or
sometime more) before being able to report problems. Worse, with the
previous scheme the solver may fail to find a solution and so we'd
end up reporting that rather than the problem with the user's target.

Reduce it from info to debug and put it in a more sensible place where
we can also report if it's parallel or serial more easily.

This is part of the refactoring to resolve command line build targets
without first having to run the solver and produce the elaborated
install plan.

Previously runProjectPreBuildPhase would do all the early steps
including finding the project root and establishing the project
config and the local packages. This patch splits those early steps
out into a separate pass in the project orchestration. It also
eliminates the need for the hookPrePlanning and since there's then
only one hook left we don't bother to name the PreBuildHooks.

Having split getting the project config from constructing the install
plan we can simplify how the project config is handled. This lets us
pass just one set of ProjectConfig to resolveBuildTimeSettings rather
than parts of both the persistent and the cli ProjectConfig.

Previously we had a rebuildInstallPlan that does everything up to
producing the elaborated install plan. This included reading the project
config and all the local package description files etc.

It is useful to split this latter aspect out separately. The reason for
this is that we would really prefer to resolve command line build
targets without first having to run the solver and produce the
elaborated install plan. We would prefer to be able to report mistakes
in the build targets more or less instantly rather than having to wait
many seconds (or sometime more) before being able to report problems.
Worse, with the current scheme the solver may fail to find a solution
and so we'll end up reporting that rather than the problem with the
user's build target. Indeed problems with a build target are most likely
to happen when the project config is messed up (or not what users
expect, or before they understand the model) and those are the cases
where it's most likely that there is no project solution.

So this is a step towards being able to do all target resolution prior
to solving.

Also make the qualifiers case insensitive

It is not actually canonical for directories with vs without a trailing
slash. This bug is present in newer directory releases, older versions
work correctly.

Filed as https://github.com/haskell/directory/issues/63

Comments, error messages and updated example inputs.

So instead of a big set of matcher functions and and one big render
funtion, we split it up so that each form of syntax is a thing on its
own with both the matcher and renderer for that form. Then we collect up
all the various syntax forms.

This makes the pairing much easier, and much clearer when we add new
forms of syntax.

Handy for debugging and testing

Add shortcut behaviour to matchPlusShadowing. This does not change the
semantics, just avoids computing unnecessary matches.

We're going to generalise it and the name will no longer be appropriate.
We'll add the ability to select all packages, or to select only certain
kinds of components in a package. So this makes it less like a resolved
target and more or an expression that needs further work to resolve to
a set of targets.

We already have the SubComponentTarget type so we can use this to better
factor the BuildTarget type, and simplify conversions.

The way it is currently implemented is incompatible with the new target
checking code, since it really selects everything, including things that
are not buildable. This leads directly to failre when we check that the
things the user has asked to build are in fact buildable.

So far they just build the exe bench and don't do the next steps,
but they do at least select the right components to build.

Also bring the existing test command into sync with the others.

Rather than having it appear in the [other] section. I've just guessed
at where it ought to go. Suggestions welcome.

This is slightly tricky stuff to write since it has to be concise,
clear, accurate and make sense without too much context. This and
the examples should be reviewed with comparison to the user guide.

It looks like CmdHaddock was based on the CmdConfigure template and so
copied some bits that don't make sense for it. Change those bits to be
the same as for build.

In particular for printing the plan, the configure command always
behaves as if it is in --dry-run mode, but that's not appropriate for
the haddock command. The other change is to follow the standard pattern
for the runProjectBuildPhase / runProjectPostBuildPhase and the handling
of the --dry-run option, which is handled internally by those and does
not need to be handled explicitly in CmdHaddock.

And also reject --only-dependencies for the haddock command.

The --only-dependencies it is only used in build, so we move the
rendering of the errors that arise from that to that build command
module so the error message text can be more context specific.

Instead of expressing the intention in terms of PackageTargets, it now
takes helper functions that select the components to use for a package
target or a component target. These helpers are given the set of
AvailableTargets and they can do error checking and return failures.

This allows the build,configure,haddock,repl implementations to have
their own behaviour and error checking and reporting for selecting
targets.

The full details of error reporting are not covered yet.

selectTargets would also prune to to the targets, and optionally prune
to dependencies only. These aspects are now pulled out into the callers
in the various Cmd{Build,Repl,etc} modules.

It will make more sense to do it this way once we're doing more explicit
error checking in the callers.

Previously the resolveUserBuildTargets would return a PackageName which
meant we would subsequently select all versions of that package that
occur in the project during target selection (resolveAndCheckTargets).
Using PackageId means we only pick one version (though in future we may
still need to disambiguate multiple instances, or targets from multiple
active profiles)

This is one major part of a new implementation of translating from high
level user intentions of what to build into the detail of what specific
components to build.

This part collects and summarises information on what component are
available as targets. Each available target one has enough status info
to determine if we can possibly select the target or if not why not.

This information will be used by each command (build, repl, test etc) to
select the specific targets that a user intention refers to (and to
provide them enough information to be able to produce reasonable error
messages).

Collecting and summarising this info is unfortunately non-trivial
because as part of install plan elaboration we omit components that
cannot be built but these are still components that users could try to
refer to, so we have to reconstruct the info about the omitted
components. It's plausible that we may want to revise the elaborated
install plan representation to make this easier.

Previously it took the specification for the targets to build in terms
of PackageTarget which is a high-ish level specification of which
components to build. It is high level in the sense that it says things
like BuildDefaultComponents which still have to be elaborated into the
specific components.

This elaboration from the higher level intention of what to build into
what components to build specifically has to vary between different
commands (build, repl, run, test, bench) and it can also fail. These
features make it not a good fit to do within plan pruning. Instead it
is better to have plan pruning take the lower level specification of
what to build in terms of components and to do the conversion of high
level to low level separately. That will allow us to do it differently
for different commands and deal with failures better.

This patch does one step: it changes pruneInstallPlanToTargets from
taking [PackageTarget] to [ComponentTarget] and as an intermediate step
in refactoring it converts the existing elaboratePackageTargets code to
convert from the [PackageTarget] to [ComponentTarget] which is then used
by the calling code in ProjectOrchestration. The next step will be to
replace the elaboratePackageTargets with something more flexible and
that can handle errors better.

And push compatSubComponentTargets inside nubComponentTargets. The
motivation for this is we'll be exporting nubComponentTargets and using
it from the ProjectOrchestration as part of revised target handling.

The pruneInstallPlanToTargets function had two main passes. Split the
first pass into two passes. This simplifies things a bit and helps
clarify the fact that setting the root targets is something we do prior
to taking the dep closure.