From 227b8a3bf1302626339be3c35e3e4102fe8bc874 Mon Sep 17 00:00:00 2001 From: Daniel Gröber Date: Sun, 16 Dec 2018 03:55:26 +0100 Subject: Comments [ci skip] --- lib/Distribution/Helper.hs | 9 +++---- src/CabalHelper/Compiletime/Types.hs | 46 +++++++++++++++++--------------- src/CabalHelper/Shared/InterfaceTypes.hs | 2 ++ tests/CompileTest.hs | 1 - 4 files changed, 30 insertions(+), 28 deletions(-) diff --git a/lib/Distribution/Helper.hs b/lib/Distribution/Helper.hs index 2f9493e..d8fcdf7 100644 --- a/lib/Distribution/Helper.hs +++ b/lib/Distribution/Helper.hs @@ -143,19 +143,18 @@ import qualified CabalHelper.Compiletime.Compat.ProgramDb as ProgDb import Distribution.System (buildPlatform) import Distribution.Text (display) import Distribution.Verbosity (silent, deafening) ---import Distribution.Package (packageName, packageVersion) import Distribution.Simple.GHC as GHC (configure) -- $type-conventions -- Throughout the API we use the following conventions for type variables: -- --- * @pt@ stands for "project type", when instantiated is always of kind +-- * @pt@ stands for "project type", when instantiated it is always of kind -- 'ProjType'. -- -- * @c@ stands for "cache". It is used internally to make the cache -- inaccessible for some parts of the implementation. Users of the API may --- ignore it. See the internal 'qeCacheRef' field accessor of 'QueryEnv' for --- details. +-- completely ignore this parameter. See the internal 'qeCacheRef' field +-- accessor of 'QueryEnv' for details. -- | A lazy, cached, query against a package's Cabal configuration. Use @@ -443,7 +442,7 @@ readProjInfo qe pc pcm = withVerbosity $ do let ?cprogs = cprogs in let ?progs = qePrograms qe in GHC.listCabalVersions (Just (sppGlobalPkgDb proj_paths)) - -- ^ See [Note Stack Cabal Version] + -- ^ See [Note Stack Cabal Version] return ProjInfo { piCabalVersion = cabalVer , piProjConfModTimes = pcm 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 diff --git a/src/CabalHelper/Shared/InterfaceTypes.hs b/src/CabalHelper/Shared/InterfaceTypes.hs index fa31d7b..c54a508 100644 --- a/src/CabalHelper/Shared/InterfaceTypes.hs +++ b/src/CabalHelper/Shared/InterfaceTypes.hs @@ -91,6 +91,8 @@ data ChComponentInfo = ChComponentInfo -- be built in memory and instead needs proper build output. } deriving (Eq, Ord, Read, Show) +-- TODO: we know the source-dir now so we can resolve ChSetupEntrypoint +-- internally data ChEntrypoint = ChSetupEntrypoint -- ^ Almost like 'ChExeEntrypoint' but -- @main-is@ could either be @"Setup.hs"@ -- or @"Setup.lhs"@. Since we don't know diff --git a/tests/CompileTest.hs b/tests/CompileTest.hs index 47ae2e3..19727c4 100644 --- a/tests/CompileTest.hs +++ b/tests/CompileTest.hs @@ -28,7 +28,6 @@ import CabalHelper.Compiletime.Compat.Version import CabalHelper.Compiletime.Compat.Parsec import CabalHelper.Compiletime.Cabal import CabalHelper.Compiletime.Compile ---import CabalHelper.Compiletime.Program.CabalInstall import CabalHelper.Compiletime.Program.GHC import CabalHelper.Compiletime.Types import CabalHelper.Shared.Common -- cgit v1.2.3