From a59d7b1f56ff7d206bbddcd3647ab39e46a7c4aa Mon Sep 17 00:00:00 2001 From: Daniel Gröber Date: Tue, 30 Jul 2019 20:35:00 +0200 Subject: Update API docs of main types --- src/CabalHelper/Compiletime/Types.hs | 120 +++++++++++++++++++++++++++-------- 1 file changed, 93 insertions(+), 27 deletions(-) (limited to 'src/CabalHelper/Compiletime/Types.hs') diff --git a/src/CabalHelper/Compiletime/Types.hs b/src/CabalHelper/Compiletime/Types.hs index edbcd46..cded136 100644 --- a/src/CabalHelper/Compiletime/Types.hs +++ b/src/CabalHelper/Compiletime/Types.hs @@ -42,13 +42,21 @@ import Data.List.NonEmpty (NonEmpty) import Data.Map.Strict (Map) --import qualified Data.Map.Strict as Strict --- | The kind of project being managed by a 'QueryEnv' (pun intended). +-- | The kind of project being managed by a 'QueryEnv' (pun intended). Used +-- as a phantom-type variable throughout to make the project type being +-- passed into various functions correspond to the correct implementation. data ProjType - = V1 -- ^ @cabal v1-build@ project, see 'DistDirV1' - | V2 -- ^ @cabal v2-build@ project, see 'DistDirV2' + = V1 -- ^ @cabal v1-build@ project. + | V2 -- ^ @cabal v2-build@ project. | Stack -- ^ @stack@ project. deriving (Eq, Ord, Show, Read) +-- | A "singleton" datatype for 'ProjType' which allows us to establish a +-- correspondence between a runtime representation of 'ProjType' to the +-- compile-time value at the type level. +-- +-- If you just want to know the runtime 'ProjType' use 'demoteSProjType' to +-- convert to that. data SProjType pt where SCabal :: !(SCabalProjType pt) -> SProjType pt SStack :: SProjType 'Stack @@ -69,28 +77,81 @@ demoteSProjType (SCabal SCV1) = V1 demoteSProjType (SCabal SCV2) = V2 demoteSProjType SStack = Stack --- | Location of project sources. The project type of a given directory can be --- determined by trying to access a set of marker files. See below. +-- | Location of a project context. Usually a project's top-level source +-- code directory or a project type specific config file. +-- +-- To find any recognized default project contexts in a given directory +-- use 'Distribution.Helper.Discover.findProjects'. +-- +-- Build tools usually allow the user to specify the location of their +-- project config files manually, so we also support passing this path here +-- with the @*File@ constructors. +-- +-- === Correspondence with Project Source Directory +-- +-- Note that the project's source directory does not necessarily correspond +-- to the directory containing the project config file, though in some +-- cases it does. +-- +-- For example cabal-V2 allows the @cabal.project@ file to be positively +-- anywhere in the filesystem when specified via the @--cabal-project@ +-- command-line flag, corresponding to the 'ProjLocV2File' constructor +-- here. This config file can then refer to package directories with +-- absolute paths in the @packages:@ declaration. +-- +-- Hence it isn't actually possible to find the whole project's toplevel +-- source directory given just a 'ProjLoc'. However the packages within a +-- project have a well defined source directory. +-- +-- Unfortunately we do not expose the concept of a "package" in the API to +-- abstract the differences between the project types. Instead each 'Unit' +-- (which is conceptually part of a "package") carries the corresponding +-- package source directory in 'uPackageDir'. Together with a 'Unit' query +-- such as 'projectUnits' you can thus get the source directory for each +-- unit. +-- +-- If you need to present this in a per-package view rather than a per-unit +-- view you should be able to use the source directory as a key to +-- determine which units to group into a package. data ProjLoc (pt :: ProjType) where - -- | A @cabal v1-build@ project directory can be identified by one file - -- ending in @.cabal@ existing in the directory. More than one such files - -- existing is a user error. Note: For this project type the concepts of - -- project and package coincide. + -- | A fully specified @cabal v1-build@ project context. Here you can + -- specify both the path to the @.cabal@ file and the source directory + -- of the package. The cabal file path corresponds to the + -- @--cabal-file=PATH@ flag on the @cabal@ command line. + -- + -- Note that More than one such files existing in a package directory + -- is a user error and cabal might still complain about that but we + -- won't. + -- + -- Also note that for this project type the concepts of project and + -- package coincide. ProjLocV1CabalFile :: { plCabalFile :: !FilePath, plPackageDir :: !FilePath } -> ProjLoc 'V1 - -- | A @cabal v1-build@ project directory. Same as 'ProjLocV1CabalFile' but - -- will search for the cabal file for you. If more than one @.cabal@ file - -- exists it will shamelessly throw an obscure exception. + -- | A @cabal v1-build@ project context. Essentially the same as + -- 'ProjLocV1CabalFile' but this will dynamically search for the cabal + -- file for you as cabal-install does by default. + -- + -- If more than one @.cabal@ file exists in the given directory we will + -- shamelessly throw a obscure exception when using this in the API so + -- prefer 'ProjLocV1CabalFile' if you don't want that to happen. This + -- mainly exists for easy upgrading from the @cabal-helper-0.8@ series. ProjLocV1Dir :: { plPackageDir :: !FilePath } -> ProjLoc 'V1 - -- | A @cabal v2-build@ project\'s marker file is called - -- @cabal.project@. This configuration file points to the packages that make - -- up this project. + -- | A @cabal v2-build@ project context. The path to the + -- @cabal.project@ file, though you can call it whatever you like. This + -- configuration file then points to the packages that make up this + -- project. This corresponds to the @--cabal-project=PATH@ flag on the + -- @cabal@ command line. ProjLocV2File :: { plCabalProjectFile :: !FilePath } -> ProjLoc 'V2 + + -- | This is equivalent to 'ProjLocV2File' but using the default + -- @cabal.project@ file name. ProjLocV2Dir :: { plV2Dir :: !FilePath } -> ProjLoc 'V2 - -- | A @stack@ project\'s marker file is called @stack.yaml@. This - -- configuration file points to the packages that make up this project. + -- | A @stack@ project context. Specify the path to the @stack.yaml@ + -- file here. This configuration file then points to the packages that + -- make up this project. Corresponds to @stack@'s @--stack-yaml=PATH@ + -- command line flag if different from the default name, @stack.yaml@. ProjLocStackYaml :: { plStackYaml :: !FilePath } -> ProjLoc 'Stack deriving instance Show (ProjLoc pt) @@ -107,13 +168,13 @@ projTypeOfProjLoc ProjLocV2Dir{} = SCabal SCV2 projTypeOfProjLoc ProjLocStackYaml{} = SStack -- | A build directory for a certain project type. The @pt@ type variable --- must match the value of 'ProjLoc'. This is enforced by the type system --- so you can't get this wrong :) +-- must be compatible with the 'ProjLoc' used. This is enforced by the type +-- system so you can't get this wrong. data DistDir (pt :: ProjType) where -- | A build-directory for cabal, aka. dist-dir in Cabal -- terminology. 'SCabalProjType' specifies whether we should use -- /v2-build/ or /v1-build/. This choice must correspond to - -- 'ProjLoc'\'s project type. + -- 'ProjLoc' \'s project type. DistDirCabal :: !(SCabalProjType pt) -> !FilePath -> DistDir pt -- | A build-directory for stack, aka. /work-dir/. Optionally override @@ -133,7 +194,7 @@ projTypeOfDistDir DistDirStack{} = SStack -- Say you have: -- -- @ --- {-# LANGUAGE DataKinds, GADTS #-} +-- {-\# LANGUAGE DataKinds, GADTS \#-} -- data K = A | B | ... -- data Q k where -- QA :: ... -> Q 'A @@ -209,13 +270,18 @@ data QueryCache pt = QueryCache newtype DistDirLib = DistDirLib FilePath deriving (Eq, Ord, Read, Show) --- | 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'. +-- | A 'Unit' is essentially a "build target". It is used to refer to a set +-- of components (exes, libs, tests etc.) which are managed by a certain +-- instance of the Cabal build-system[1]. We may get information on the +-- components in a unit by retriving the corresponding 'UnitInfo'. +-- +-- \[1]: No I'm not talking about the cabal-install /build-tool/, I'm +-- talking about the Cabal /build-system/. Note the distinction. Both +-- cabal-install and Stack use the Cabal build-system (aka @lib:Cabal@) +-- underneath. -- --- Note that a 'Unit' value is only valid within the 'QueryEnv' context it was --- created in. However this is not enforced in the API. +-- Note that a 'Unit' value is only valid within the 'QueryEnv' context it +-- was created in. However this is not enforced by the API. data Unit pt = Unit { uUnitId :: !UnitId , uPackageDir :: !FilePath -- cgit v1.2.3