Distribution.Client.ProjectOrchestration

Parse a bunch of command line args as TargetSelectors, failing with an error if any are unrecognised. The possible target selectors are based on the available packages (and their locations).

Throw an exception with a formatted message if there are any problems.

Given a set of TargetSelectors, resolve which UnitIds and ComponentTargets they ought to refer to.

The idea is that every user target identifies one or more roots in the ElaboratedInstallPlan, which we will use to determine the closure of what packages need to be built, dropping everything from the plan that is unnecessary. This closure and pruning is done by pruneInstallPlanToTargets and this needs to be told the roots in terms of UnitIds and the ComponentTargets within those.

This means we first need to translate the TargetSelectors into the UnitIds and ComponentTargets. This translation has to be different for the different command line commands, like build, repl etc. For example the command build pkgfoo could select a different set of components in pkgfoo than repl pkgfoo. The build command would select any library and all executables, whereas repl would select the library or a single executable. Furthermore, both of these examples could fail, and fail in different ways and each needs to be able to produce helpful error messages.

So resolveTargets takes two helpers: one to select the targets to be used by user targets that refer to a whole package (TargetPackage), and another to check user targets that refer to a component (or a module or file within a component). These helpers can fail, and use their own error type. Both helpers get given the AvailableTarget info about the component(s).

While commands vary quite a bit in their behaviour about which components to select for a whole-package target, most commands have the same behaviour for checking a user target that refers to a specific component. To help with this commands can use selectComponentTargetBasic, either directly or as a basis for their own selectComponentTarget implementation.

The set of components to build, represented as a mapping from UnitIds to the ComponentTargets within the unit that will be selected (e.g. selected to build, test or repl).

Associated with each ComponentTarget is the set of TargetSelectors that matched this target. Typically this is exactly one, but in general it is possible to for different selectors to match the same target. This extra information is primarily to help make helpful error messages.

Get all target selectors.

Get all unique target selectors.

A target selector is expression selecting a set of components (as targets for a actions like build, run, test etc). A target selector corresponds to the user syntax for referring to targets on the command line.

From the users point of view a target can be many things: packages, dirs, component names, files etc. Internally we consider a target to be a specific component (or module/file within a component), and all the users' notions of targets are just different ways of referring to these component targets.

So target selectors are expressions in the sense that they are interpreted to refer to one or more components. For example a TargetPackage gets interpreted differently by different commands to refer to all or a subset of components within the package.

The syntax has lots of optional parts:

[ package name | package dir | package .cabal file ]
[ [lib:|exe:] component name ]
[ module name | source file ]

Does this TargetPackage selector arise from syntax referring to a package in the current directory (e.g. tests or no giving no explicit target at all) or does it come from syntax referring to a package name or location.

Type alias so we can use the shorter name PackageId.

An available target represents a component within a package that a user command could plausibly refer to. In this sense, all the components defined within the package are things the user could refer to, whether or not it would actually be possible to build that component.

In particular the available target contains an AvailableTargetStatus which informs us about whether it's actually possible to select this component to be built, and if not why not. This detail makes it possible for command implementations (like build, test etc) to accurately report why a target cannot be used.

Note that the type parameter is used to help enforce that command implementations can only select targets that can actually be built (by forcing them to return the k value for the selected targets). In particular resolveTargets makes use of this (with k as (UnitId, ComponentName')) to identify the targets thus selected.

The status of a an AvailableTarget component. This tells us whether it's actually possible to select this component to be built, and if not why not.

This tells us whether a target ought to be built by default, or only if specifically requested. The policy is that components like libraries and executables are built by default by build, but test suites and benchmarks are not, unless this is overridden in the project configuration.

Specific targets within a package or component to act on e.g. to build, haddock or open a repl.

Either the component as a whole or detail about a file or module target within a component.

A basic selectComponentTarget implementation to use or pass to resolveTargets, that does the basic checks that the component is buildable and isn't a test suite or benchmark that is disabled. This can also be used to do these basic checks as part of a custom impl that

Utility used by repl and run to check if the targets spans multiple components, since those commands do not support multiple components.

Wrapper around pruneInstallPlanToTargets that adjusts for the extra unneeded info in the TargetsMap.

How pruneInstallPlanToTargets should interpret the per-package ComponentTargets: as build, repl or haddock targets.

Try to remove the given targets from the install plan.

This is not always possible.

It is not always possible to prune to only the dependencies of a set of targets. It may be the case that removing a package leaves something else that still needed the pruned package.

This lists all the packages that would be broken, and their dependencies that would be missing if we did prune.

Print a user-oriented presentation of the install plan, indicating what will be built.