aboutsummaryrefslogtreecommitdiff
path: root/src/CabalHelper/Compiletime
diff options
context:
space:
mode:
authorDaniel Gröber <dxld@darkboxed.org>2018-12-16 03:55:26 +0100
committerDaniel Gröber <dxld@darkboxed.org>2019-01-22 03:06:51 +0100
commit227b8a3bf1302626339be3c35e3e4102fe8bc874 (patch)
tree859d65a957ce5343d237000b894c6eb81c4fa5b6 /src/CabalHelper/Compiletime
parentfe19006b6e4fe1ea3be52fd17c9ff70e24adcd78 (diff)
Comments
[ci skip]
Diffstat (limited to 'src/CabalHelper/Compiletime')
-rw-r--r--src/CabalHelper/Compiletime/Types.hs46
1 files changed, 24 insertions, 22 deletions
diff --git a/src/CabalHelper/Compiletime/Types.hs b/src/CabalHelper/Compiletime/Types.hs
index 5a19261..56f2468 100644
--- a/src/CabalHelper/Compiletime/Types.hs
+++ b/src/CabalHelper/Compiletime/Types.hs
@@ -90,9 +90,12 @@ data DistDir (pt :: ProjType) where
-- /work-dir/. If you just want to use Stack's default set to @Nothing@
DistDirStack :: Maybe RelativePath -> DistDir 'Stack
--- | Environment for running a 'Query' value. The real constructor is
--- not exposed, use the 'mkQueryEnv' smart constructor instead. The field
--- accessors are exported and may be used to override the defaults, see below.
+-- | Environment for running a 'Query' value. The constructor is not exposed in
+-- the API to allow extending the environment without breaking user code.
+--
+-- To create a 'QueryEnv' use the 'mkQueryEnv' smart constructor. The field
+-- accessors are exported and may be used to override the defaults filled in by
+-- 'mkQueryEnv'. See below.
type QueryEnv (pt :: ProjType)
= QueryEnvI QueryCache pt
@@ -117,9 +120,10 @@ data QueryEnvI c (pt :: ProjType) = QueryEnv
-- ^ Field accessor for 'QueryEnv'. Defines path to the @dist/@ or
-- @dist-newstyle/@ directory, aka. /builddir/ in Cabal terminology.
- -- ^ Cache for query results, only accessible when type parameter @cache@ is
- -- instantiated and not forall quantified.
, qeCacheRef :: !(IORef (c pt))
+ -- ^ Cache for query results, only accessible when type parameter @c@ is
+ -- instantiated with 'QueryCache'. This is the case wherever the type alias
+ -- 'QueryEnv' is used.
}
data QueryCache pt = QueryCache
@@ -130,18 +134,10 @@ data QueryCache pt = QueryCache
newtype DistDirLib = DistDirLib FilePath
deriving (Eq, Ord, Read, Show)
--- | Abstractly speaking a Unit consists of a set of components (exes, libs,
--- tests etc.) which are managed by an instance of the Cabal build system. The
--- distinction between a Unit and a set of components is somewhat hard to
--- explain if you're not already familliar with the concept from
--- cabal-install. Luckily for most purposes the details may be ignored.
---
--- We merely use the concept of a Unit for caching purposes. It is necessary to
--- extract the information on all components in a Unit at the same time as we
--- must load all of it into memory before extracting any of it.
---
--- As opposed to components, different 'Unit's can be queried independently
--- since their on-disk information is stored separately.
+-- | A 'Unit' is used as reference to a set of components (exes, libs, tests
+-- etc.) which are managed by an certain instance of the Cabal build system. We
+-- may get information on the components in a unit by retriving the
+-- corresponding 'UnitInfo'.
data Unit pt = Unit
{ uUnitId :: !UnitId
, uPackageDir :: !FilePath
@@ -177,10 +173,10 @@ uComponentName _ =
newtype UnitId = UnitId String
deriving (Eq, Ord, Read, Show)
--- | The information extracted from a 'Unit's on-disk configuration.
+-- | The information extracted from a 'Unit'\'s on-disk configuration cache.
data UnitInfo = UnitInfo
{ uiUnitId :: !UnitId
- -- ^ A unique identifier of this init within the project.
+ -- ^ A unique identifier of this unit within the project.
, uiPackageId :: !(String, Version)
-- ^ The package-name and version this unit belongs to.
@@ -207,10 +203,13 @@ data UnitInfo = UnitInfo
-- i.e. don't rely on these being the flags set by the user directly.
, uiModTimes :: !UnitModTimes
+ -- ^ Key for cache invalidation. When this is not equal to the value
+ -- returned by 'getUnitModTimes' this 'UnitInfo' is considered invalid.
} deriving (Eq, Ord, Read, Show)
--- | Files relevant to the project-scope configuration of a project. We gather
--- them here so we can refer to their paths conveniently.
+-- | Files relevant to the project-scope configuration. We gather them here so
+-- we can refer to their paths conveniently throughout the code. These files are
+-- not necessarily guaranteed to even exist.
data ProjConf pt where
ProjConfV1 ::
{ pcV1CabalFile :: !FilePath
@@ -231,11 +230,14 @@ data ProjConf pt where
newtype ProjConfModTimes = ProjConfModTimes [(FilePath, EpochTime)]
deriving (Eq)
+-- | Project-scope information cache.
data ProjInfo pt = ProjInfo
{ piCabalVersion :: !Version
- , piProjConfModTimes :: !ProjConfModTimes
, piUnits :: !(NonEmpty (Unit pt))
, piImpl :: !(ProjInfoImpl pt)
+ , piProjConfModTimes :: !ProjConfModTimes
+ -- ^ Key for cache invalidation. When this is not equal to the return
+ -- value of 'getProjConfModTime' this 'ProjInfo' is considered invalid.
}
data ProjInfoImpl pt where