From cb814edcdc962ff4e724489ce454dee1dc9edb96 Mon Sep 17 00:00:00 2001 From: Phil de Joux Date: Wed, 20 May 2026 13:29:01 -0400 Subject: [PATCH] PreExisting, Configured, Installed haddocks - Fake admonition with @@ - Try to explain the type arguments - Fix a grammar typo "package that aren't" - Replace @...@ with heading - Use monotype in warning - Move 'PackageInstalled' note --- .../src/Distribution/Client/InstallPlan.hs | 40 ++++++++++++------- 1 file changed, 25 insertions(+), 15 deletions(-) diff --git a/cabal-install/src/Distribution/Client/InstallPlan.hs b/cabal-install/src/Distribution/Client/InstallPlan.hs index bb427f44a2c..73b6a9054e1 100644 --- a/cabal-install/src/Distribution/Client/InstallPlan.hs +++ b/cabal-install/src/Distribution/Client/InstallPlan.hs @@ -18,7 +18,20 @@ -- Stability : provisional -- Portability : portable -- --- Package installation plan +-- Package installation plan. +-- +-- === Warning +-- +-- 'ConfiguredPackage', 'GenericReadyPackage' and 'GenericPlanPackage' +-- intentionally have no 'Distribution.Package.PackageInstalled' instance. +-- +-- @PackageInstalled@ returns only library dependencies, but for a package that +-- isn't yet installed we know many more kinds of dependencies (setup +-- dependencies, exe, test-suite, benchmark, ..). Any functions that operate on +-- dependencies in @cabal-install@ should consider what to do with these +-- dependencies; if we give a @PackageInstalled@ instance it would be too easy +-- to get this wrong (and, for instance, call graph traversal functions from +-- @Cabal@ rather than from @cabal-install@). module Distribution.Client.InstallPlan ( InstallPlan , GenericInstallPlan @@ -158,21 +171,18 @@ import qualified Distribution.Compat.Graph as Graph -- have problems with inconsistent dependencies. -- On the other hand it is true that every closed sub plan is valid. --- | Packages in an install plan --- --- NOTE: 'ConfiguredPackage', 'GenericReadyPackage' and 'GenericPlanPackage' --- intentionally have no 'PackageInstalled' instance. `This is important: --- PackageInstalled returns only library dependencies, but for package that --- aren't yet installed we know many more kinds of dependencies (setup --- dependencies, exe, test-suite, benchmark, ..). Any functions that operate on --- dependencies in cabal-install should consider what to do with these --- dependencies; if we give a 'PackageInstalled' instance it would be too easy --- to get this wrong (and, for instance, call graph traversal functions from --- Cabal rather than from cabal-install). Instead, see 'PackageInstalled'. +-- | Packages in an install plan, either pre-existing installed `ipkg` packages +-- or source `srcpkg` packages. data GenericPlanPackage ipkg srcpkg - = PreExisting ipkg - | Configured srcpkg - | Installed srcpkg + = -- | A package that is already installed. These have fixed dependencies + -- having already been built. + PreExisting ipkg + | -- | A package that is not yet installed but is configured and constrained + -- in its dependencies. + Configured srcpkg + | -- | An installed package that is also available as a source package meaning + -- that it could be re-installed if required. + Installed srcpkg deriving (Eq, Show, Generic) displayGenericPlanPackage :: (IsUnit ipkg, IsUnit srcpkg) => GenericPlanPackage ipkg srcpkg -> String