haskell · sorki · May 1, 2026 · May 1, 2026 · May 2, 2026 · May 2, 2026
diff --git a/Cabal-syntax/src/Distribution/Types/InstalledPackageInfo.hs b/Cabal-syntax/src/Distribution/Types/InstalledPackageInfo.hs
@@ -42,8 +42,10 @@ data InstalledPackageInfo = InstalledPackageInfo
     sourcePackageId :: PackageId
   , sourceLibName :: LibraryName
   , installedComponentId_ :: ComponentId
+  , installedSublibs :: [InstalledPackageInfo]
   , libVisibility :: LibraryVisibility
   , installedUnitId :: UnitId
+  , installedInstanceUnitId :: InstanceUnitId
   , -- INVARIANT: if this package is definite, OpenModule's
     -- OpenUnitId directly records UnitId.  If it is
     -- indefinite, OpenModule is always an OpenModuleVar
@@ -135,6 +137,8 @@ emptyInstalledPackageInfo =
     , sourceLibName = LMainLibName
     , installedComponentId_ = mkComponentId ""
     , installedUnitId = mkUnitId ""
+    , installedInstanceUnitId = mkInstanceUnitId $ mkUnitId ""
+    , installedSublibs = mempty
     , instantiatedWith = []
     , compatPackageKey = ""
     , license = Left SPDX.NONE

diff --git a/Cabal-syntax/src/Distribution/Types/InstalledPackageInfo/FieldGrammar.hs b/Cabal-syntax/src/Distribution/Types/InstalledPackageInfo/FieldGrammar.hs
@@ -61,6 +61,7 @@ ipiFieldGrammar
      , c (Identity LibraryVisibility)
      , c (Identity PackageName)
      , c (Identity UnitId)
+     , c (Identity InstanceUnitId)
      , c (Identity UnqualComponentName)
      , c (List FSep (Identity AbiDependency) AbiDependency)
      , c (List FSep (Identity UnitId) UnitId)
@@ -85,6 +86,7 @@ ipiFieldGrammar =
     <@> blurFieldGrammar basic basicFieldGrammar
     -- Basic fields
     <@> optionalFieldDef "id" L.installedUnitId (mkUnitId "")
+    <@> optionalFieldDef "instance-id" L.installedInstanceUnitId (mkInstanceUnitId $ mkUnitId "")
     <@> optionalFieldDefAla "instantiated-with" InstWith L.instantiatedWith []
     <@> optionalFieldDefAla "key" CompatPackageKey L.compatPackageKey ""
     <@> optionalFieldDefAla "license" SpecLicenseLenient L.license (Left SPDX.NONE)
@@ -134,6 +136,7 @@ ipiFieldGrammar =
         (PackageIdentifier pn _basicVersion)
         (combineLibraryName ln _basicLibName)
         (mkComponentId "") -- installedComponentId_, not in use
+        mempty -- installedSublibs
         _basicLibVisibility
       where
         MungedPackageName pn ln = _basicName

diff --git a/Cabal-syntax/src/Distribution/Types/InstalledPackageInfo/Lens.hs b/Cabal-syntax/src/Distribution/Types/InstalledPackageInfo/Lens.hs
@@ -10,7 +10,7 @@ import Prelude ()
 import Distribution.Backpack (OpenModule)
 import Distribution.License (License)
 import Distribution.ModuleName (ModuleName)
-import Distribution.Package (AbiHash, ComponentId, PackageIdentifier, UnitId)
+import Distribution.Package (AbiHash, ComponentId, InstanceUnitId, PackageIdentifier, UnitId)
 import Distribution.Types.InstalledPackageInfo (AbiDependency, ExposedModule, InstalledPackageInfo)
 import Distribution.Types.LibraryName (LibraryName)
 import Distribution.Types.LibraryVisibility (LibraryVisibility)
@@ -27,6 +27,10 @@ installedUnitId :: Lens' InstalledPackageInfo UnitId
 installedUnitId f s = fmap (\x -> s{T.installedUnitId = x}) (f (T.installedUnitId s))
 {-# INLINE installedUnitId #-}
 
+installedInstanceUnitId :: Lens' InstalledPackageInfo InstanceUnitId
+installedInstanceUnitId f s = fmap (\x -> s{T.installedInstanceUnitId = x}) (f (T.installedInstanceUnitId s))
+{-# INLINE installedInstanceUnitId #-}
+
 installedComponentId_ :: Lens' InstalledPackageInfo ComponentId
 installedComponentId_ f s = fmap (\x -> s{T.installedComponentId_ = x}) (f (T.installedComponentId_ s))
 {-# INLINE installedComponentId_ #-}

diff --git a/Cabal-syntax/src/Distribution/Types/UnitId.hs b/Cabal-syntax/src/Distribution/Types/UnitId.hs
@@ -13,6 +13,9 @@ module Distribution.Types.UnitId
   , newSimpleUnitId
   , mkLegacyUnitId
   , getHSLibraryName
+  , InstanceUnitId
+  , mkInstanceUnitId
+  , unInstanceUnitId
   ) where
 
 import Distribution.Compat.Prelude
@@ -131,3 +134,16 @@ instance Parsec DefUnitId where
 -- is to ensure that the 'DefUnitId' invariant holds.
 unsafeMkDefUnitId :: UnitId -> DefUnitId
 unsafeMkDefUnitId = DefUnitId
+
+-- | A 'UnitId' for an instance (group of components). Typically
+-- this matches a main library 'UnitId'
+newtype InstanceUnitId = InstanceUnitId {unInstanceUnitId :: UnitId}
+  deriving (Generic, Read, Show, Eq, Ord, Data, Binary, NFData, Pretty)
+
+instance Structured InstanceUnitId
+
+instance Parsec InstanceUnitId where
+  parsec = InstanceUnitId <$> parsec
+
+mkInstanceUnitId :: UnitId -> InstanceUnitId
+mkInstanceUnitId = InstanceUnitId
diff --git a/Cabal-tests/tests/ParserTests/ipi/Includes2.cabal b/Cabal-tests/tests/ParserTests/ipi/Includes2.cabal
@@ -1,6 +1,7 @@
 name: z-Includes2-z-mylib
 version: 0.1.0.0
 id: Includes2-0.1.0.0-inplace-mylib+3gY9SyjX86dBypHcOaev1n
+instance-id: Includes2-0.1.0.0-inplace-mylib+3gY9SyjX86dBypHcOaev1n
 instantiated-with: Database=Includes2-0.1.0.0-inplace-mysql:Database.MySQL
 package-name: Includes2
 lib-name: mylib

diff --git a/Cabal-tests/tests/ParserTests/ipi/Includes2.expr b/Cabal-tests/tests/ParserTests/ipi/Includes2.expr
@@ -9,10 +9,13 @@ InstalledPackageInfo {
     (UnqualComponentName "mylib"),
   installedComponentId_ =
   ComponentId "",
+  installedSublibs = [],
   libVisibility =
   LibraryVisibilityPrivate,
   installedUnitId = UnitId
     "Includes2-0.1.0.0-inplace-mylib+3gY9SyjX86dBypHcOaev1n",
+  installedInstanceUnitId = InstanceUnitId
+    (UnitId "Includes2-0.1.0.0-inplace-mylib+3gY9SyjX86dBypHcOaev1n"),
   instantiatedWith = [
     _×_
       (ModuleName "Database")

diff --git a/Cabal-tests/tests/ParserTests/ipi/Includes2.format b/Cabal-tests/tests/ParserTests/ipi/Includes2.format
@@ -3,6 +3,7 @@ version:              0.1.0.0
 package-name:         Includes2
 lib-name:             mylib
 id:                   Includes2-0.1.0.0-inplace-mylib+3gY9SyjX86dBypHcOaev1n
+instance-id:          Includes2-0.1.0.0-inplace-mylib+3gY9SyjX86dBypHcOaev1n
 instantiated-with:    Database=Includes2-0.1.0.0-inplace-mysql:Database.MySQL
 key:                  Includes2-0.1.0.0-inplace-mylib+3gY9SyjX86dBypHcOaev1n
 license:              BSD3

diff --git a/Cabal-tests/tests/ParserTests/ipi/internal-preprocessor-test.expr b/Cabal-tests/tests/ParserTests/ipi/internal-preprocessor-test.expr
@@ -8,10 +8,13 @@ InstalledPackageInfo {
   sourceLibName = LMainLibName,
   installedComponentId_ =
   ComponentId "",
+  installedSublibs = [],
   libVisibility =
   LibraryVisibilityPublic,
   installedUnitId = UnitId
     "internal-preprocessor-test-0.1.0.0",
+  installedInstanceUnitId = InstanceUnitId
+    (UnitId ""),
   instantiatedWith = [],
   compatPackageKey =
   "internal-preprocessor-test-0.1.0.0",

diff --git a/Cabal-tests/tests/ParserTests/ipi/issue-2276-ghc-9885.expr b/Cabal-tests/tests/ParserTests/ipi/issue-2276-ghc-9885.expr
@@ -8,10 +8,13 @@ InstalledPackageInfo {
   sourceLibName = LMainLibName,
   installedComponentId_ =
   ComponentId "",
+  installedSublibs = [],
   libVisibility =
   LibraryVisibilityPublic,
   installedUnitId = UnitId
     "transformers-0.5.2.0",
+  installedInstanceUnitId = InstanceUnitId
+    (UnitId ""),
   instantiatedWith = [],
   compatPackageKey =
   "transformers-0.5.2.0",

diff --git a/Cabal-tests/tests/ParserTests/ipi/transformers.cabal b/Cabal-tests/tests/ParserTests/ipi/transformers.cabal
@@ -1,6 +1,7 @@
 name: transformers
 version: 0.5.2.0
 id: transformers-0.5.2.0
+instance-id: transformers-0.5.2.0
 key: transformers-0.5.2.0
 license: BSD3
 maintainer: Ross Paterson <R.Paterson@city.ac.uk>

diff --git a/Cabal-tests/tests/ParserTests/ipi/transformers.expr b/Cabal-tests/tests/ParserTests/ipi/transformers.expr
@@ -8,10 +8,13 @@ InstalledPackageInfo {
   sourceLibName = LMainLibName,
   installedComponentId_ =
   ComponentId "",
+  installedSublibs = [],
   libVisibility =
   LibraryVisibilityPublic,
   installedUnitId = UnitId
     "transformers-0.5.2.0",
+  installedInstanceUnitId = InstanceUnitId
+    (UnitId "transformers-0.5.2.0"),
   instantiatedWith = [],
   compatPackageKey =
   "transformers-0.5.2.0",

diff --git a/Cabal-tests/tests/ParserTests/ipi/transformers.format b/Cabal-tests/tests/ParserTests/ipi/transformers.format
@@ -2,6 +2,7 @@ name:                 transformers
 version:              0.5.2.0
 visibility:           public
 id:                   transformers-0.5.2.0
+instance-id:          transformers-0.5.2.0
 key:                  transformers-0.5.2.0
 license:              BSD3
 maintainer:           Ross Paterson <R.Paterson@city.ac.uk>

diff --git a/Cabal-tests/tests/UnitTests/Distribution/Utils/Structured.hs b/Cabal-tests/tests/UnitTests/Distribution/Utils/Structured.hs
@@ -33,4 +33,4 @@ md5CheckGenericPackageDescription proxy = md5Check proxy
 
 md5CheckLocalBuildInfo :: Proxy LocalBuildInfo -> Assertion
 md5CheckLocalBuildInfo proxy = md5Check proxy
-    0x78979713e08179ab070d6ab10cd5ef6c
+    0xe394537933f4b964768db669ff128aa7
diff --git a/Cabal-tree-diff/src/Data/TreeDiff/Instances/Cabal.hs b/Cabal-tree-diff/src/Data/TreeDiff/Instances/Cabal.hs
@@ -27,7 +27,7 @@ import Distribution.Types.AbiHash                  (AbiHash)
 import Distribution.Types.ComponentId              (ComponentId)
 import Distribution.Types.DumpBuildInfo            (DumpBuildInfo)
 import Distribution.Types.PackageVersionConstraint
-import Distribution.Types.UnitId                   (DefUnitId, UnitId)
+import Distribution.Types.UnitId                   (DefUnitId, InstanceUnitId, UnitId)
 import Distribution.Utils.NubList                  (NubList)
 import Distribution.Utils.Path                     (SymbolicPathX)
 import Distribution.Utils.ShortText                (ShortText, fromShortText)
@@ -113,6 +113,7 @@ instance ToExpr ForeignLibOption
 instance ToExpr ForeignLibType
 instance ToExpr HaddockTarget
 instance ToExpr IncludeRenaming
+instance ToExpr InstanceUnitId
 instance ToExpr InstalledPackageInfo
 instance ToExpr KnownRepoType
 instance ToExpr LegacyExeDependency

diff --git a/Cabal/src/Distribution/Backpack/Configure.hs b/Cabal/src/Distribution/Backpack/Configure.hs
@@ -67,6 +67,7 @@ configureComponentLocalBuildInfos
   -> Bool -- deterministic
   -> Flag String -- configIPID
   -> Flag ComponentId -- configCID
+  -> Flag InstanceUnitId -- configIUID
   -> PackageDescription
   -> ([PreExistingComponent], [ConfiguredPromisedComponent])
   -> FlagAssignment -- configConfigurationsFlags
@@ -81,6 +82,7 @@ configureComponentLocalBuildInfos
   deterministic
   ipid_flag
   cid_flag
+  iuid_flag
   pkg_descr
   (prePkgDeps, promisedPkgDeps)
   flags
@@ -127,6 +129,7 @@ configureComponentLocalBuildInfos
         deterministic
         ipid_flag
         cid_flag
+        iuid_flag
         pkg_descr
         conf_pkg_map
         (map fst graph0)
@@ -391,6 +394,7 @@ mkLinkedComponentsLocalBuildInfo comp rcs = map go rcs
            in LibComponentLocalBuildInfo
                 { componentPackageDeps = cpds
                 , componentUnitId = this_uid
+                , componentInstanceUnitId = this_instance_uid
                 , componentComponentId = this_cid
                 , componentInstantiatedWith = insts
                 , componentIsIndefinite_ = is_indefinite
@@ -445,6 +449,7 @@ mkLinkedComponentsLocalBuildInfo comp rcs = map go rcs
             }
       where
         this_uid = rc_uid rc
+        this_instance_uid = rc_instance_id rc
         this_open_uid = rc_open_uid rc
         this_cid = rc_cid rc
         cname = componentName (rc_component rc)

diff --git a/Cabal/src/Distribution/Backpack/ConfiguredComponent.hs b/Cabal/src/Distribution/Backpack/ConfiguredComponent.hs
@@ -1,3 +1,5 @@
+{-# LANGUAGE PatternSynonyms #-}
+
 -- | See <https://github.com/ezyang/ghc-proposals/blob/backpack/proposals/0000-backpack.rst>
 module Distribution.Backpack.ConfiguredComponent
   ( ConfiguredComponent (..)
@@ -22,7 +24,7 @@ import Distribution.CabalSpecVersion
 import Distribution.Package
 import Distribution.PackageDescription
 import Distribution.Simple.BuildToolDepends
-import Distribution.Simple.Flag (Flag)
+import Distribution.Simple.Flag (Flag, pattern Flag, pattern NoFlag)
 import Distribution.Simple.LocalBuildInfo
 import Distribution.Types.AnnotatedId
 import Distribution.Types.ComponentInclude
@@ -43,6 +45,7 @@ import qualified Text.PrettyPrint as PP
 data ConfiguredComponent = ConfiguredComponent
   { cc_ann_id :: AnnotatedId ComponentId
   -- ^ Unique identifier of component, plus extra useful info.
+  , cc_instance_unit_id :: InstanceUnitId
   , cc_component :: Component
   -- ^ The fragment of syntax from the Cabal file describing this
   -- component.
@@ -98,11 +101,12 @@ dispConfiguredComponent cc =
 mkConfiguredComponent
   :: PackageDescription
   -> ComponentId
+  -> InstanceUnitId
   -> [AnnotatedId ComponentId] -- lib deps
   -> [AnnotatedId ComponentId] -- exe deps
   -> Component
   -> LogProgress ConfiguredComponent
-mkConfiguredComponent pkg_descr this_cid lib_deps exe_deps component = do
+mkConfiguredComponent pkg_descr this_cid this_iuid lib_deps exe_deps component = do
   -- Resolve each @mixins@ into the actual dependency
   -- from @lib_deps@.
   explicit_includes <- forM (mixins bi) $ \(Mixin pn ln rns) -> do
@@ -142,6 +146,7 @@ mkConfiguredComponent pkg_descr this_cid lib_deps exe_deps component = do
             , ann_pid = package pkg_descr
             , ann_cname = componentName component
             }
+      , cc_instance_unit_id = this_iuid
       , cc_component = component
       , cc_public = is_public
       , cc_exe_deps = exe_deps
@@ -170,11 +175,12 @@ type ConfiguredComponentMap =
 toConfiguredComponent
   :: PackageDescription
   -> ComponentId
+  -> InstanceUnitId
   -> ConfiguredComponentMap
   -> ConfiguredComponentMap
   -> Component
   -> LogProgress ConfiguredComponent
-toConfiguredComponent pkg_descr this_cid lib_dep_map exe_dep_map component = do
+toConfiguredComponent pkg_descr this_cid this_iuid lib_dep_map exe_dep_map component = do
   lib_deps <-
     if newPackageDepsBehaviour pkg_descr
       then fmap concat $
@@ -202,6 +208,7 @@ toConfiguredComponent pkg_descr this_cid lib_dep_map exe_dep_map component = do
   mkConfiguredComponent
     pkg_descr
     this_cid
+    this_iuid
     lib_deps
     exe_deps
     component
@@ -246,6 +253,7 @@ toConfiguredComponent'
   -> Bool -- deterministic
   -> Flag String -- configIPID (todo: remove me)
   -> Flag ComponentId -- configCID
+  -> Flag InstanceUnitId -- configIUID
   -> ConfiguredComponentMap
   -> Component
   -> LogProgress ConfiguredComponent
@@ -256,12 +264,14 @@ toConfiguredComponent'
   deterministic
   ipid_flag
   cid_flag
+  iuid_flag
   dep_map
   component = do
     cc <-
       toConfiguredComponent
         pkg_descr
         this_cid
+        this_iuid
         dep_map
         dep_map
         component
@@ -279,6 +289,10 @@ toConfiguredComponent'
           (package pkg_descr)
           (componentName component)
           (Just (deps, flags))
+      this_iuid =
+        case iuid_flag of
+          Flag iuid -> iuid
+          NoFlag -> mkInstanceUnitId $ mkUnitId $ unComponentId this_cid
       deps =
         [ ann_id aid | m <- Map.elems dep_map, aid <- Map.elems m
         ]
@@ -308,6 +322,7 @@ toConfiguredComponents
   -> Bool -- deterministic
   -> Flag String -- configIPID
   -> Flag ComponentId -- configCID
+  -> Flag InstanceUnitId -- configIUID
   -> PackageDescription
   -> ConfiguredComponentMap
   -> [Component]
@@ -318,6 +333,7 @@ toConfiguredComponents
   deterministic
   ipid_flag
   cid_flag
+  iuid_flag
   pkg_descr
   dep_map
   comps =
@@ -332,6 +348,7 @@ toConfiguredComponents
             deterministic
             ipid_flag
             cid_flag
+            iuid_flag
             m
             component
         return (extendConfiguredComponentMap cc m, cc)

diff --git a/Cabal/src/Distribution/Backpack/LinkedComponent.hs b/Cabal/src/Distribution/Backpack/LinkedComponent.hs
@@ -50,6 +50,8 @@ import Text.PrettyPrint (Doc, hang, hsep, quotes, text, vcat, ($+$))
 data LinkedComponent = LinkedComponent
   { lc_ann_id :: AnnotatedId ComponentId
   -- ^ Uniquely identifies linked component
+  , lc_instance_id :: InstanceUnitId
+  -- ^ Uniquely identifies instance (group of components)
   , lc_component :: Component
   -- ^ Corresponds to 'cc_component'.
   , lc_exe_deps :: [AnnotatedId OpenUnitId]
@@ -128,6 +130,7 @@ toLinkedComponent
   pkg_map
   ConfiguredComponent
     { cc_ann_id = aid@AnnotatedId{ann_id = this_cid}
+    , cc_instance_unit_id = iuid
     , cc_component = component
     , cc_exe_deps = exe_deps
     , cc_public = is_public
@@ -378,6 +381,7 @@ toLinkedComponent
     return $
       LinkedComponent
         { lc_ann_id = aid
+        , lc_instance_id = iuid
         , lc_component = component
         , lc_public = is_public
         , -- These must be executables