Distribution.Client.Dependency

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

Copyright | (c) David Himmelstrup 2005 Bjorn Bringert 2007 Duncan Coutts 2008
License | BSD-like
Maintainer | cabal-devel@gmail.com
Stability | provisional
Portability | portable
Safe Haskell | None
Language | Haskell2010

Distribution.Client.Dependency

Contents

- The main package dependency resolver
- Alternate, simple resolver that does not do dependencies recursively
- Constructing resolver policies
  - Standard policy
  - Extra policy options
  - Policy utils

Description

Top level interface to dependency resolution.

Synopsis

- data DepResolverParams
- resolveDependencies :: Platform -> CompilerInfo -> PkgConfigDb -> DepResolverParams -> Progress String String SolverInstallPlan
- data Progress step fail done
  - = Step step (Progress step fail done)
  - | Fail fail
  - | Done done
- foldProgress :: (step -> a -> a) -> (fail -> a) -> (done -> a) -> Progress step fail done -> a
- resolveWithoutDependencies :: DepResolverParams -> Either [ResolveNoDepsError] [UnresolvedSourcePackage]
- data PackageProperty
  - = PackagePropertyVersion VersionRange
  - | PackagePropertyInstalled
  - | PackagePropertySource
  - | PackagePropertyFlags FlagAssignment
  - | PackagePropertyStanzas [OptionalStanza]
- data PackageConstraint = PackageConstraint ConstraintScope PackageProperty
- scopeToplevel :: PackageName -> ConstraintScope
- data PackagesPreferenceDefault
  - = PreferAllLatest
  - | PreferAllOldest
  - | PreferAllInstalled
  - | PreferLatestForSelected
- data PackagePreference
  - = PackageVersionPreference PackageName VersionRange
  - | PackageInstalledPreference PackageName InstalledPreference
  - | PackageStanzasPreference PackageName [OptionalStanza]
- basicInstallPolicy :: InstalledPackageIndex -> SourcePackageDb -> [PackageSpecifier UnresolvedSourcePackage] -> DepResolverParams
- standardInstallPolicy :: InstalledPackageIndex -> SourcePackageDb -> [PackageSpecifier UnresolvedSourcePackage] -> DepResolverParams
- data PackageSpecifier pkg
  - = NamedPackage PackageName [PackageProperty]
  - | SpecificSourcePackage pkg
- upgradeDependencies :: DepResolverParams -> DepResolverParams
- reinstallTargets :: DepResolverParams -> DepResolverParams
- addConstraints :: [LabeledPackageConstraint] -> DepResolverParams -> DepResolverParams
- addPreferences :: [PackagePreference] -> DepResolverParams -> DepResolverParams
- setPreferenceDefault :: PackagesPreferenceDefault -> DepResolverParams -> DepResolverParams
- setReorderGoals :: ReorderGoals -> DepResolverParams -> DepResolverParams
- setCountConflicts :: CountConflicts -> DepResolverParams -> DepResolverParams
- setFineGrainedConflicts :: FineGrainedConflicts -> DepResolverParams -> DepResolverParams
- setMinimizeConflictSet :: MinimizeConflictSet -> DepResolverParams -> DepResolverParams
- setIndependentGoals :: IndependentGoals -> DepResolverParams -> DepResolverParams
- setAvoidReinstalls :: AvoidReinstalls -> DepResolverParams -> DepResolverParams
- setShadowPkgs :: ShadowPkgs -> DepResolverParams -> DepResolverParams
- setStrongFlags :: StrongFlags -> DepResolverParams -> DepResolverParams
- setAllowBootLibInstalls :: AllowBootLibInstalls -> DepResolverParams -> DepResolverParams
- setOnlyConstrained :: OnlyConstrained -> DepResolverParams -> DepResolverParams
- setMaxBackjumps :: Maybe Int -> DepResolverParams -> DepResolverParams
- setEnableBackjumping :: EnableBackjumping -> DepResolverParams -> DepResolverParams
- setSolveExecutables :: SolveExecutables -> DepResolverParams -> DepResolverParams
- setGoalOrder :: Maybe (Variable QPN -> Variable QPN -> Ordering) -> DepResolverParams -> DepResolverParams
- setSolverVerbosity :: Verbosity -> DepResolverParams -> DepResolverParams
- removeLowerBounds :: AllowOlder -> DepResolverParams -> DepResolverParams
- removeUpperBounds :: AllowNewer -> DepResolverParams -> DepResolverParams
- addDefaultSetupDependencies :: (UnresolvedSourcePackage -> Maybe [Dependency]) -> DepResolverParams -> DepResolverParams
- addSetupCabalMinVersionConstraint :: Version -> DepResolverParams -> DepResolverParams
- addSetupCabalMaxVersionConstraint :: Version -> DepResolverParams -> DepResolverParams

# The main package dependency resolver

data DepResolverParams #

The set of parameters to the dependency resolver. These parameters are relatively low level but many kinds of high level policies can be implemented in terms of adjustments to the parameters.

resolveDependencies :: Platform -> CompilerInfo -> PkgConfigDb -> DepResolverParams -> Progress String String SolverInstallPlan #

Run the dependency solver.

Since this is potentially an expensive operation, the result is wrapped in a a `Progress` structure that can be unfolded to provide progress information, logging messages and the final result or an error.

data Progress step fail done #

A type to represent the unfolding of an expensive long running calculation that may fail. We may get intermediate steps before the final result which may be used to indicate progress and/or logging messages.

Constructors

Step step (Progress step fail done) |
Fail fail |
Done done |

#### Instances

Instances details

Monoid fail => Alternative (Progress step fail) |
Instance details Defined in Distribution.Solver.Types.Progress Methods empty :: Progress step fail a # (<|>) :: Progress step fail a -> Progress step fail a -> Progress step fail a # some :: Progress step fail a -> Progress step fail [a] # many :: Progress step fail a -> Progress step fail [a] #
Applicative (Progress step fail) |
Instance details Defined in Distribution.Solver.Types.Progress Methods pure :: a -> Progress step fail a # (<*>) :: Progress step fail (a -> b) -> Progress step fail a -> Progress step fail b # liftA2 :: (a -> b -> c) -> Progress step fail a -> Progress step fail b -> Progress step fail c # (*>) :: Progress step fail a -> Progress step fail b -> Progress step fail b # (<*) :: Progress step fail a -> Progress step fail b -> Progress step fail a #
Functor (Progress step fail) |
Instance details Defined in Distribution.Solver.Types.Progress Methods fmap :: (a -> b) -> Progress step fail a -> Progress step fail b # (<$) :: a -> Progress step fail b -> Progress step fail a #
Monad (Progress step fail) |
Instance details Defined in Distribution.Solver.Types.Progress Methods (>>=) :: Progress step fail a -> (a -> Progress step fail b) -> Progress step fail b # (>>) :: Progress step fail a -> Progress step fail b -> Progress step fail b # return :: a -> Progress step fail a #

foldProgress :: (step -> a -> a) -> (fail -> a) -> (done -> a) -> Progress step fail done -> a #

Consume a `Progress` calculation. Much like `foldr` for lists but with two base cases, one for a final result and one for failure.

Eg to convert into a simple `Either` result use:

    foldProgress (flip const) Left Right

# Alternate, simple resolver that does not do dependencies recursively

resolveWithoutDependencies :: DepResolverParams -> Either [ResolveNoDepsError] [UnresolvedSourcePackage] #

A simplistic method of resolving a list of target package names to available packages.

Specifically, it does not consider package dependencies at all. Unlike `resolveDependencies`, no attempt is made to ensure that the selected packages have dependencies that are satisfiable or consistent with each other.

It is suitable for tasks such as selecting packages to download for user inspection. It is not suitable for selecting packages to install.

Note: if no installed package index is available, it is OK to pass `mempty`. It simply means preferences for installed packages will be ignored.

# Constructing resolver policies

data PackageProperty #

A package property is a logical predicate on packages.

Constructors

PackagePropertyVersion VersionRange |
PackagePropertyInstalled |
PackagePropertySource |
PackagePropertyFlags FlagAssignment |
PackagePropertyStanzas [OptionalStanza] |

#### Instances

Instances details

Structured PackageProperty |
Instance details Defined in Distribution.Solver.Types.PackageConstraint Methods structure :: Proxy PackageProperty -> Structure # structureHash' :: Tagged PackageProperty MD5
Binary PackageProperty |
Instance details Defined in Distribution.Solver.Types.PackageConstraint Methods put :: PackageProperty -> Put # get :: Get PackageProperty # putList :: [PackageProperty] -> Put #
Generic PackageProperty |
Instance details Defined in Distribution.Solver.Types.PackageConstraint Associated Types
type Rep PackageProperty |
Instance details Defined in Distribution.Solver.Types.PackageConstraint type Rep PackageProperty = D1 ('MetaData "PackageProperty" "Distribution.Solver.Types.PackageConstraint" "cabal-install-solver-3.12.1.0-BcLJX5rVQuejx1qrKAH5j" 'False) ((C1 ('MetaCons "PackagePropertyVersion" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 VersionRange)) :+: C1 ('MetaCons "PackagePropertyInstalled" 'PrefixI 'False) (U1 :: Type -> Type)) :+: (C1 ('MetaCons "PackagePropertySource" 'PrefixI 'False) (U1 :: Type -> Type) :+: (C1 ('MetaCons "PackagePropertyFlags" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 FlagAssignment)) :+: C1 ('MetaCons "PackagePropertyStanzas" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 [OptionalStanza])))))
Methods from :: PackageProperty -> Rep PackageProperty x # to :: Rep PackageProperty x -> PackageProperty #
Show PackageProperty |
Instance details Defined in Distribution.Solver.Types.PackageConstraint Methods showsPrec :: Int -> PackageProperty -> ShowS # show :: PackageProperty -> String # showList :: [PackageProperty] -> ShowS #
Eq PackageProperty |
Instance details Defined in Distribution.Solver.Types.PackageConstraint Methods (==) :: PackageProperty -> PackageProperty -> Bool # (/=) :: PackageProperty -> PackageProperty -> Bool #
type Rep PackageProperty |
Instance details Defined in Distribution.Solver.Types.PackageConstraint type Rep PackageProperty = D1 ('MetaData "PackageProperty" "Distribution.Solver.Types.PackageConstraint" "cabal-install-solver-3.12.1.0-BcLJX5rVQuejx1qrKAH5j" 'False) ((C1 ('MetaCons "PackagePropertyVersion" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 VersionRange)) :+: C1 ('MetaCons "PackagePropertyInstalled" 'PrefixI 'False) (U1 :: Type -> Type)) :+: (C1 ('MetaCons "PackagePropertySource" 'PrefixI 'False) (U1 :: Type -> Type) :+: (C1 ('MetaCons "PackagePropertyFlags" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 FlagAssignment)) :+: C1 ('MetaCons "PackagePropertyStanzas" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 [OptionalStanza])))))

data PackageConstraint #

A package constraint consists of a scope plus a property that must hold for all packages within that scope.

Constructors

PackageConstraint ConstraintScope PackageProperty |

#### Instances

Instances details

Show PackageConstraint |
Instance details Defined in Distribution.Solver.Types.PackageConstraint Methods showsPrec :: Int -> PackageConstraint -> ShowS # show :: PackageConstraint -> String # showList :: [PackageConstraint] -> ShowS #
Eq PackageConstraint |
Instance details Defined in Distribution.Solver.Types.PackageConstraint Methods (==) :: PackageConstraint -> PackageConstraint -> Bool # (/=) :: PackageConstraint -> PackageConstraint -> Bool #

scopeToplevel :: PackageName -> ConstraintScope #

Constructor for a common use case: the constraint applies to the package with the specified name when that package is a top-level dependency in the default namespace.

data PackagesPreferenceDefault #

Global policy for all packages to say if we prefer package versions that are already installed locally or if we just prefer the latest available.

Constructors

PreferAllLatest | Always prefer the latest version irrespective of any existing installed version. This is the standard policy for upgrade.
PreferAllOldest | Always prefer the oldest version irrespective of any existing installed version or packages explicitly requested. This is enabled by --prefer-oldest.
PreferAllInstalled | Always prefer the installed versions over ones that would need to be installed. Secondarily, prefer latest versions (eg the latest installed version or if there are none then the latest source version).
PreferLatestForSelected | Prefer the latest version for packages that are explicitly requested but prefers the installed version for any other packages. This is the standard policy for install.

#### Instances

Instances details

Show PackagesPreferenceDefault # |
Instance details Defined in Distribution.Client.Dependency.Types Methods showsPrec :: Int -> PackagesPreferenceDefault -> ShowS # show :: PackagesPreferenceDefault -> String # showList :: [PackagesPreferenceDefault] -> ShowS #

data PackagePreference #

A package selection preference for a particular package.

Preferences are soft constraints that the dependency resolver should try to respect where possible. It is not specified if preferences on some packages are more important than others.

Constructors

PackageVersionPreference PackageName VersionRange | A suggested constraint on the version number.
PackageInstalledPreference PackageName InstalledPreference | If we prefer versions of packages that are already installed.
PackageStanzasPreference PackageName [OptionalStanza] | If we would prefer to enable these optional stanzas (i.e. test suites and/or benchmarks)

## Standard policy

basicInstallPolicy :: InstalledPackageIndex -> SourcePackageDb -> [PackageSpecifier UnresolvedSourcePackage] -> DepResolverParams #

A basic solver policy on which all others are built.

standardInstallPolicy :: InstalledPackageIndex -> SourcePackageDb -> [PackageSpecifier UnresolvedSourcePackage] -> DepResolverParams #

The policy used by all the standard commands, install, fetch, freeze etc (but not the v2-build and related commands).

It extends the `basicInstallPolicy` with a policy on setup deps.

data PackageSpecifier pkg #

A fully or partially resolved reference to a package.

Constructors

NamedPackage PackageName [PackageProperty] | A partially specified reference to a package (either source or installed). It is specified by package name and optionally some required properties. Use a dependency resolver to pick a specific package satisfying these properties.
SpecificSourcePackage pkg | A fully specified source package.

#### Instances

Instances details

Functor PackageSpecifier # |
Instance details Defined in Distribution.Client.Types.PackageSpecifier Methods fmap :: (a -> b) -> PackageSpecifier a -> PackageSpecifier b # (<$) :: a -> PackageSpecifier b -> PackageSpecifier a #
Structured pkg => Structured (PackageSpecifier pkg) # |
Instance details Defined in Distribution.Client.Types.PackageSpecifier Methods structure :: Proxy (PackageSpecifier pkg) -> Structure # structureHash' :: Tagged (PackageSpecifier pkg) MD5
Binary pkg => Binary (PackageSpecifier pkg) # |
Instance details Defined in Distribution.Client.Types.PackageSpecifier Methods put :: PackageSpecifier pkg -> Put # get :: Get (PackageSpecifier pkg) # putList :: [PackageSpecifier pkg] -> Put #
Generic (PackageSpecifier pkg) # |
Instance details Defined in Distribution.Client.Types.PackageSpecifier Associated Types
type Rep (PackageSpecifier pkg) |
Instance details Defined in Distribution.Client.Types.PackageSpecifier type Rep (PackageSpecifier pkg) = D1 ('MetaData "PackageSpecifier" "Distribution.Client.Types.PackageSpecifier" "cabal-install-3.12.1.0-G554PkJj2SpDqyarXp9tbt" 'False) (C1 ('MetaCons "NamedPackage" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 PackageName) :*: S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 [PackageProperty])) :+: C1 ('MetaCons "SpecificSourcePackage" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 pkg)))
Methods from :: PackageSpecifier pkg -> Rep (PackageSpecifier pkg) x # to :: Rep (PackageSpecifier pkg) x -> PackageSpecifier pkg #
Show pkg => Show (PackageSpecifier pkg) # |
Instance details Defined in Distribution.Client.Types.PackageSpecifier Methods showsPrec :: Int -> PackageSpecifier pkg -> ShowS # show :: PackageSpecifier pkg -> String # showList :: [PackageSpecifier pkg] -> ShowS #
Eq pkg => Eq (PackageSpecifier pkg) # |
Instance details Defined in Distribution.Client.Types.PackageSpecifier Methods (==) :: PackageSpecifier pkg -> PackageSpecifier pkg -> Bool # (/=) :: PackageSpecifier pkg -> PackageSpecifier pkg -> Bool #
type Rep (PackageSpecifier pkg) # |
Instance details Defined in Distribution.Client.Types.PackageSpecifier type Rep (PackageSpecifier pkg) = D1 ('MetaData "PackageSpecifier" "Distribution.Client.Types.PackageSpecifier" "cabal-install-3.12.1.0-G554PkJj2SpDqyarXp9tbt" 'False) (C1 ('MetaCons "NamedPackage" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 PackageName) :*: S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 [PackageProperty])) :+: C1 ('MetaCons "SpecificSourcePackage" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 pkg)))

## Extra policy options

upgradeDependencies :: DepResolverParams -> DepResolverParams #

reinstallTargets :: DepResolverParams -> DepResolverParams #

## Policy utils

addConstraints :: [LabeledPackageConstraint] -> DepResolverParams -> DepResolverParams #

addPreferences :: [PackagePreference] -> DepResolverParams -> DepResolverParams #

setPreferenceDefault :: PackagesPreferenceDefault -> DepResolverParams -> DepResolverParams #

setReorderGoals :: ReorderGoals -> DepResolverParams -> DepResolverParams #

setCountConflicts :: CountConflicts -> DepResolverParams -> DepResolverParams #

setFineGrainedConflicts :: FineGrainedConflicts -> DepResolverParams -> DepResolverParams #

setMinimizeConflictSet :: MinimizeConflictSet -> DepResolverParams -> DepResolverParams #

setIndependentGoals :: IndependentGoals -> DepResolverParams -> DepResolverParams #

setAvoidReinstalls :: AvoidReinstalls -> DepResolverParams -> DepResolverParams #

setShadowPkgs :: ShadowPkgs -> DepResolverParams -> DepResolverParams #

setStrongFlags :: StrongFlags -> DepResolverParams -> DepResolverParams #

setAllowBootLibInstalls :: AllowBootLibInstalls -> DepResolverParams -> DepResolverParams #

setOnlyConstrained :: OnlyConstrained -> DepResolverParams -> DepResolverParams #

setMaxBackjumps :: Maybe Int -> DepResolverParams -> DepResolverParams #

setEnableBackjumping :: EnableBackjumping -> DepResolverParams -> DepResolverParams #

setSolveExecutables :: SolveExecutables -> DepResolverParams -> DepResolverParams #

setGoalOrder :: Maybe (Variable QPN -> Variable QPN -> Ordering) -> DepResolverParams -> DepResolverParams #

setSolverVerbosity :: Verbosity -> DepResolverParams -> DepResolverParams #

removeLowerBounds :: AllowOlder -> DepResolverParams -> DepResolverParams #

Dual of `removeUpperBounds`

removeUpperBounds :: AllowNewer -> DepResolverParams -> DepResolverParams #

Remove upper bounds in dependencies using the policy specified by the `AllowNewer` argument (allsomenone).

Note: It's important to apply `removeUpperBounds` after `addSourcePackages`. Otherwise, the packages inserted by `addSourcePackages` won't have upper bounds in dependencies relaxed.

addDefaultSetupDependencies :: (UnresolvedSourcePackage -> Maybe [Dependency]) -> DepResolverParams -> DepResolverParams #

Supply defaults for packages without explicit Setup dependencies

Note: It's important to apply `addDefaultSetupDepends` after `addSourcePackages`. Otherwise, the packages inserted by `addSourcePackages` won't have upper bounds in dependencies relaxed.

addSetupCabalMinVersionConstraint :: Version -> DepResolverParams -> DepResolverParams #

If a package has a custom setup then we need to add a setup-depends on Cabal.

addSetupCabalMaxVersionConstraint :: Version -> DepResolverParams -> DepResolverParams #

Variant of `addSetupCabalMinVersionConstraint` which sets an upper bound on `setup.Cabal` labeled with `ConstraintSetupCabalMaxVersion`.