Distribution.Client.SolverInstallPlan

cabal-install-3.12.1.0: The command-line interface for Cabal and Hackage.

Copyright | (c) Duncan Coutts 2008
License | BSD-like
Maintainer | duncan@community.haskell.org
Stability | provisional
Portability | portable
Safe Haskell | None
Language | Haskell2010

Distribution.Client.SolverInstallPlan

Contents

- Operations on `SolverInstallPlan`s
- Checking validity of plans
  - Details on invalid plans
  - Querying the install plan

Description

The `SolverInstallPlan` is the graph of packages produced by the dependency solver, and specifies at the package-granularity what things are going to be installed. To put it another way: the dependency solver produces a `SolverInstallPlan`, which is then consumed by various other parts of Cabal.

Synopsis

- data SolverInstallPlan = SolverInstallPlan {
  - planIndex :: !SolverPlanIndex
  - planIndepGoals :: !IndependentGoals
  }
- type SolverPlanPackage = ResolverPackage UnresolvedPkgLoc
- data ResolverPackage loc
  - = PreExisting InstSolverPackage
  - | Configured (SolverPackage loc)
- new :: IndependentGoals -> SolverPlanIndex -> Either [SolverPlanProblem] SolverInstallPlan
- toList :: SolverInstallPlan -> [SolverPlanPackage]
- toMap :: SolverInstallPlan -> Map SolverId SolverPlanPackage
- remove :: (SolverPlanPackage -> Bool) -> SolverInstallPlan -> Either [SolverPlanProblem] SolverInstallPlan
- showPlanIndex :: [SolverPlanPackage] -> String
- showInstallPlan :: SolverInstallPlan -> String
- valid :: IndependentGoals -> SolverPlanIndex -> Bool
- closed :: SolverPlanIndex -> Bool
- consistent :: SolverPlanIndex -> Bool
- acyclic :: SolverPlanIndex -> Bool
- data SolverPlanProblem
  - = PackageMissingDeps SolverPlanPackage [PackageIdentifier]
  - | PackageCycle [SolverPlanPackage]
  - | PackageInconsistency PackageName [(PackageIdentifier, Version)]
  - | PackageStateInvalid SolverPlanPackage SolverPlanPackage
- showPlanProblem :: SolverPlanProblem -> String
- problems :: IndependentGoals -> SolverPlanIndex -> [SolverPlanProblem]
- dependencyClosure :: SolverInstallPlan -> [SolverId] -> [SolverPlanPackage]
- reverseDependencyClosure :: SolverInstallPlan -> [SolverId] -> [SolverPlanPackage]
- topologicalOrder :: SolverInstallPlan -> [SolverPlanPackage]
- reverseTopologicalOrder :: SolverInstallPlan -> [SolverPlanPackage]

# Documentation

data SolverInstallPlan #

Constructors

SolverInstallPlan |
Fields planIndex :: !SolverPlanIndex planIndepGoals :: !IndependentGoals

#### Instances

Instances details

Structured SolverInstallPlan # |
Instance details Defined in Distribution.Client.SolverInstallPlan Methods structure :: Proxy SolverInstallPlan -> Structure # structureHash' :: Tagged SolverInstallPlan MD5
Binary SolverInstallPlan # |
Instance details Defined in Distribution.Client.SolverInstallPlan Methods put :: SolverInstallPlan -> Put # get :: Get SolverInstallPlan # putList :: [SolverInstallPlan] -> Put #
Generic SolverInstallPlan # |
Instance details Defined in Distribution.Client.SolverInstallPlan Associated Types
type Rep SolverInstallPlan |
Instance details Defined in Distribution.Client.SolverInstallPlan type Rep SolverInstallPlan
Methods from :: SolverInstallPlan -> Rep SolverInstallPlan x # to :: Rep SolverInstallPlan x -> SolverInstallPlan #
type Rep SolverInstallPlan # |
Instance details Defined in Distribution.Client.SolverInstallPlan type Rep SolverInstallPlan

type SolverPlanPackage = ResolverPackage UnresolvedPkgLoc #

data ResolverPackage loc #

The dependency resolver picks either pre-existing installed packages or it picks source packages along with package configuration.

This is like the `PlanPackage` but with fewer cases.

Constructors

PreExisting InstSolverPackage |
Configured (SolverPackage loc) |

#### Instances

Instances details

IsNode (ResolverPackage loc) |
Instance details Defined in Distribution.Solver.Types.ResolverPackage Associated Types
type Key (ResolverPackage loc) |
Instance details Defined in Distribution.Solver.Types.ResolverPackage type Key (ResolverPackage loc) = SolverId
Methods nodeKey :: ResolverPackage loc -> Key (ResolverPackage loc) # nodeNeighbors :: ResolverPackage loc -> [Key (ResolverPackage loc)] #
Package (ResolverPackage loc) |
Instance details Defined in Distribution.Solver.Types.ResolverPackage Methods packageId :: ResolverPackage loc -> PackageIdentifier #
Structured loc => Structured (ResolverPackage loc) |
Instance details Defined in Distribution.Solver.Types.ResolverPackage Methods structure :: Proxy (ResolverPackage loc) -> Structure # structureHash' :: Tagged (ResolverPackage loc) MD5
Binary loc => Binary (ResolverPackage loc) |
Instance details Defined in Distribution.Solver.Types.ResolverPackage Methods put :: ResolverPackage loc -> Put # get :: Get (ResolverPackage loc) # putList :: [ResolverPackage loc] -> Put #
Generic (ResolverPackage loc) |
Instance details Defined in Distribution.Solver.Types.ResolverPackage Associated Types
type Rep (ResolverPackage loc) |
Instance details Defined in Distribution.Solver.Types.ResolverPackage type Rep (ResolverPackage loc) = D1 ('MetaData "ResolverPackage" "Distribution.Solver.Types.ResolverPackage" "cabal-install-solver-3.12.1.0-BcLJX5rVQuejx1qrKAH5j" 'False) (C1 ('MetaCons "PreExisting" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 InstSolverPackage)) :+: C1 ('MetaCons "Configured" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 (SolverPackage loc))))
Methods from :: ResolverPackage loc -> Rep (ResolverPackage loc) x # to :: Rep (ResolverPackage loc) x -> ResolverPackage loc #
Show loc => Show (ResolverPackage loc) |
Instance details Defined in Distribution.Solver.Types.ResolverPackage Methods showsPrec :: Int -> ResolverPackage loc -> ShowS # show :: ResolverPackage loc -> String # showList :: [ResolverPackage loc] -> ShowS #
Eq loc => Eq (ResolverPackage loc) |
Instance details Defined in Distribution.Solver.Types.ResolverPackage Methods (==) :: ResolverPackage loc -> ResolverPackage loc -> Bool # (/=) :: ResolverPackage loc -> ResolverPackage loc -> Bool #
type Key (ResolverPackage loc) |
Instance details Defined in Distribution.Solver.Types.ResolverPackage type Key (ResolverPackage loc) = SolverId
type Rep (ResolverPackage loc) |
Instance details Defined in Distribution.Solver.Types.ResolverPackage type Rep (ResolverPackage loc) = D1 ('MetaData "ResolverPackage" "Distribution.Solver.Types.ResolverPackage" "cabal-install-solver-3.12.1.0-BcLJX5rVQuejx1qrKAH5j" 'False) (C1 ('MetaCons "PreExisting" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 InstSolverPackage)) :+: C1 ('MetaCons "Configured" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 (SolverPackage loc))))

# Operations on `SolverInstallPlan`s

new :: IndependentGoals -> SolverPlanIndex -> Either [SolverPlanProblem] SolverInstallPlan #

Build an installation plan from a valid set of resolved packages.

toList :: SolverInstallPlan -> [SolverPlanPackage] #

toMap :: SolverInstallPlan -> Map SolverId SolverPlanPackage #

remove :: (SolverPlanPackage -> Bool) -> SolverInstallPlan -> Either [SolverPlanProblem] SolverInstallPlan #

Remove packages from the install plan. This will result in an error if there are remaining packages that depend on any matching package. This is primarily useful for obtaining an install plan for the dependencies of a package or set of packages without actually installing the package itself, as when doing development.

showPlanIndex :: [SolverPlanPackage] -> String #

showInstallPlan :: SolverInstallPlan -> String #

# Checking validity of plans

valid :: IndependentGoals -> SolverPlanIndex -> Bool #

A valid installation plan is a set of packages that is `acyclic`, `closed` and `consistent`. Also, every `ConfiguredPackage` in the plan has to have a valid configuration (see `configuredPackageValid`).

- if the result is `False` use `problems` to get a detailed list.

closed :: SolverPlanIndex -> Bool #

An installation plan is closed if for every package in the set, all of its dependencies are also in the set. That is, the set is closed under the dependency relation.

- if the result is `False` use `brokenPackages` to find out which packages depend on packages not in the index.

consistent :: SolverPlanIndex -> Bool #

An installation plan is consistent if all dependencies that target a single package name, target the same version.

This is slightly subtle. It is not the same as requiring that there be at most one version of any package in the set. It only requires that of packages which have more than one other package depending on them. We could actually make the condition even more precise and say that different versions are OK so long as they are not both in the transitive closure of any other package (or equivalently that their inverse closures do not intersect). The point is we do not want to have any packages depending directly or indirectly on two different versions of the same package. The current definition is just a safe approximation of that.

- if the result is `False` use `dependencyInconsistencies` to find out which packages are.

acyclic :: SolverPlanIndex -> Bool #

The graph of packages (nodes) and dependencies (edges) must be acyclic.

- if the result is `False` use `dependencyCycles` to find out which packages are involved in dependency cycles.

## Details on invalid plans

data SolverPlanProblem #

Constructors

PackageMissingDeps SolverPlanPackage [PackageIdentifier] |
PackageCycle [SolverPlanPackage] |
PackageInconsistency PackageName [(PackageIdentifier, Version)] |
PackageStateInvalid SolverPlanPackage SolverPlanPackage |

showPlanProblem :: SolverPlanProblem -> String #

problems :: IndependentGoals -> SolverPlanIndex -> [SolverPlanProblem] #

For an invalid plan, produce a detailed list of problems as human readable error messages. This is mainly intended for debugging purposes. Use `showPlanProblem` for a human readable explanation.

## Querying the install plan

dependencyClosure :: SolverInstallPlan -> [SolverId] -> [SolverPlanPackage] #

Compute the dependency closure of a package in a install plan

reverseDependencyClosure :: SolverInstallPlan -> [SolverId] -> [SolverPlanPackage] #

topologicalOrder :: SolverInstallPlan -> [SolverPlanPackage] #

reverseTopologicalOrder :: SolverInstallPlan -> [SolverPlanPackage] #