aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorDaniel Gröber <dxld@darkboxed.org>2019-08-21 03:38:51 +0200
committerDaniel Gröber (dxld) <dxld@darkboxed.org>2019-09-17 17:48:26 +0200
commitaa09ba5d1be03b92c1b19d486dad26ed624689a1 (patch)
tree720bc7c2207d037784f640c611c56f70038e9fe0
parent83fa1ceb414f51caa1e17f2e5ac3908b3f6c4107 (diff)
Update some code docs
-rw-r--r--lib/Distribution/Helper.hs5
-rw-r--r--src/CabalHelper/Compiletime/Program/Stack.hs8
-rw-r--r--src/CabalHelper/Compiletime/Types.hs29
3 files changed, 26 insertions, 16 deletions
diff --git a/lib/Distribution/Helper.hs b/lib/Distribution/Helper.hs
index e46293d..386d86e 100644
--- a/lib/Distribution/Helper.hs
+++ b/lib/Distribution/Helper.hs
@@ -687,9 +687,8 @@ invokeHelper
-- installed and ready to run queries.
--
-- The idea is you can run this at a convinient time instead of having the
--- helper compilation happen during a time-sensitive user
--- interaction. @caba-helper@ will however do this automatically as needed
--- if you don't.
+-- helper compilation happen during a time-sensitive user interaction. This
+-- will however happen automatically as needed if you don't run it first.
prepare :: Query pt ()
prepare = Query $ \qe -> do
pre_info <- getPreInfo qe
diff --git a/src/CabalHelper/Compiletime/Program/Stack.hs b/src/CabalHelper/Compiletime/Program/Stack.hs
index 45f90ab..0f9e46d 100644
--- a/src/CabalHelper/Compiletime/Program/Stack.hs
+++ b/src/CabalHelper/Compiletime/Program/Stack.hs
@@ -48,6 +48,14 @@ import CabalHelper.Shared.Common
getPackage :: QueryEnvI c 'Stack -> CabalFile -> IO (Package 'Stack)
getPackage qe cabal_file@(CabalFile cabal_file_path) = do
let pkgdir = takeDirectory cabal_file_path
+ -- this is kind of a hack but works even for unicode package names and
+ -- besides stack even enforces this naming convention unlike cabal. This
+ -- is the error you get if the names don't match:
+ --
+ -- cabal file path foo-bla.cabal does not match the package name it defines.
+ -- Please rename the file to: foo.cabal
+ -- For more information, see:
+ -- https://github.com/commercialhaskell/stack/issues/317
let pkg_name = dropExtension $ takeFileName cabal_file_path
look <- paths qe pkgdir
let distdirv1_rel = look "dist-dir:"
diff --git a/src/CabalHelper/Compiletime/Types.hs b/src/CabalHelper/Compiletime/Types.hs
index a269210..6591513 100644
--- a/src/CabalHelper/Compiletime/Types.hs
+++ b/src/CabalHelper/Compiletime/Types.hs
@@ -225,28 +225,27 @@ data Ex a = forall x. Ex (a x)
-- | Environment for running a 'Query'. The constructor is not exposed in the
-- API to allow extending it with more fields without breaking user code.
--
--- To create a 'QueryEnv' use the 'mkQueryEnv' smart constructor instead. The
+-- To create a 'QueryEnv' use the 'mkQueryEnv' smart constructor instead. Some
-- field accessors are exported and may be used to override the defaults filled
-- in by 'mkQueryEnv'. See below.
--
-- Note that this environment contains an 'IORef' used as a cache. If you want
-- to take advantage of this you should not simply discard the value returned by
-- the smart constructor after one use.
---
--- If you do not wish to use the built-in caching feel free to discard the
--- 'QueryEnv' value though.
type QueryEnv pt = QueryEnvI QueryCache pt
data QueryEnvI c (pt :: ProjType) = QueryEnv
{ qeReadProcess :: !ReadProcessWithCwdAndEnv
- -- ^ Field accessor for 'QueryEnv'. Function used to to start
- -- processes. Useful if you need to, for example, redirect standard error
- -- output of programs started by cabal-helper.
+ -- ^ Field accessor for 'QueryEnv'. Function used to to start processes
+ -- and capture output. Useful if you need to, for example, redirect
+ -- standard error output of programs started by cabal-helper.
, qeCallProcess :: !(CallProcessWithCwdAndEnv ())
+ -- ^ Field accessor for 'QueryEnv'. Function used to to start processes
+ -- without capturing output. See also 'qeReadProcess'.
, qePrograms :: !Programs
- -- ^ Field accessor for 'QueryEnv'.
+ -- ^ Field accessor for 'QueryEnv'. Paths to various programs we use.
, qeProjLoc :: !(ProjLoc pt)
-- ^ Field accessor for 'QueryEnv'. Defines path to the project directory,
@@ -337,7 +336,11 @@ data Package' units = Package
-- underneath.
--
-- Note that a 'Unit' value is only valid within the 'QueryEnv' context it
--- was created in. However this is not enforced by the API.
+-- was created in, this is however this is not enforced by the
+-- API. Furthermore if the user changes the underlying project
+-- configuration while your application is running even a properly scoped
+-- 'Unit' could become invalid because the component it belongs to was
+-- removed from the cabal file.
data Unit pt = Unit
{ uUnitId :: !UnitId
, uPackage :: !(Package' ())
@@ -380,10 +383,10 @@ uComponentName _ =
-- names that cause trouble here so it's ok to look at them but user packages
-- are free to have any unicode name.
data UnitHeader = UnitHeader
- { uhBrokenPackageId :: !(ByteString, Version)
- -- ^ Name and version of the source package. Don't use this, it's broken
- -- when the package name contains Unicode characters. See 'uiPackageId'
- -- instead. Note: This was fixed by hvr in Cabal HEAD actually.
+ { uhPackageId :: !(ByteString, Version)
+ -- ^ Name and version of the source package. This is only going to be
+ -- usable for unicode package names starting with @Cabal-3.0.0.0@. See
+ -- 'uiPackageId' for an alternative that always works.
, uhSetupId :: !(ByteString, Version)
-- ^ Name and version of the @Setup.hs@ implementation. We expect
-- @"Cabal"@ here, naturally.