Commit 5faa5ef7 authored by Edward Z. Yang's avatar Edward Z. Yang

Explanation for Cabal PackageIndex.

Signed-off-by: default avatarEdward Z. Yang <>
parent 62c31614
......@@ -10,7 +10,50 @@
-- Maintainer :
-- Portability : portable
-- An index of packages.
-- An index of packages whose primary key is 'UnitId'. Public libraries
-- are additionally indexed by 'PackageName' and 'Version'.
-- Technically, these are an index of *units* (so we should eventually
-- rename it to 'UnitIndex'); but in the absence of internal libraries
-- or Backpack each unit is equivalent to a package.
-- 'PackageIndex' is parametric over what it actually records, and it
-- is used in two ways:
-- * The 'InstalledPackageIndex' (defined here) contains a graph of
-- 'InstalledPackageInfo's representing the packages in a
-- package database stack. It is used in a variety of ways:
-- * The primary use to let Cabal access the same installed
-- package database which is used by GHC during compilation.
-- For example, this data structure is used by 'ghc-pkg'
-- and 'Cabal' to do consistency checks on the database
-- (are the references closed).
-- * Given a set of dependencies, we can compute the transitive
-- closure of dependencies. This is to check if the versions
-- of packages are consistent, and also needed by multiple
-- tools (Haddock must be explicitly told about the every
-- transitive package to do cross-package linking;
-- preprocessors must know about the include paths of all
-- transitive dependencies.)
-- * The 'PlanIndex' (defined in 'Distribution.Client.InstallPlan'),
-- contains a graph of 'GenericPlanPackage'. Ignoring its type
-- parameters for a moment, a 'PlanIndex' is an extension of the
-- 'InstalledPackageIndex' to also record nodes for packages
-- which are *planned* to be installed, but not actually
-- installed yet. A 'PlanIndex' containing only 'PreExisting'
-- packages is essentially a 'PackageIndex'.
-- 'PlanIndex'es actually require some auxiliary information, so
-- most users interact with a 'GenericInstallPlan'. This type is
-- specialized as an 'ElaboratedInstallPlan' (for @cabal
-- new-build@) or an 'InstallPlan' (for @cabal install@).
-- This 'PackageIndex' is NOT to be confused with
-- 'Distribution.Client.PackageIndex', which indexes packages only by
-- 'PackageName' (this makes it suitable for indexing source packages,
-- for which we don't know 'UnitId's.)
module Distribution.Simple.PackageIndex (
-- * Package index data type
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment