Distribution.Helper

cabal-helper-0.7.2.0: Simple interface to some of Cabal's configuration state used by ghc-mod

Safe Haskell | None
Language | Haskell2010

Distribution.Helper

Contents

- Running Queries
- Queries against Cabal's on disk state
- Result types
- General information
- Stuff that cabal-install really should export
- Managing `dist/`
- $libexec related error handling

Synopsis

- data Programs = Programs {
  - cabalProgram :: FilePath
  - ghcProgram :: FilePath
  - ghcPkgProgram :: FilePath
  }
- defaultPrograms :: Programs
- data QueryEnv
- qeReadProcess :: QueryEnv -> FilePath -> [String] -> String -> IO String
- qePrograms :: QueryEnv -> Programs
- qeProjectDir :: QueryEnv -> FilePath
- qeDistDir :: QueryEnv -> FilePath
- qeCabalPkgDb :: QueryEnv -> Maybe FilePath
- qeCabalVer :: QueryEnv -> Maybe Version
- defaultQueryEnv :: FilePath -> FilePath -> QueryEnv
- data Query m a
- runQuery :: Monad m => QueryEnv -> Query m a -> m a
- packageDbStack :: MonadIO m => Query m [ChPkgDb]
- entrypoints :: MonadIO m => Query m [(ChComponentName, ChEntrypoint)]
- sourceDirs :: MonadIO m => Query m [(ChComponentName, [FilePath])]
- ghcOptions :: MonadIO m => Query m [(ChComponentName, [String])]
- ghcSrcOptions :: MonadIO m => Query m [(ChComponentName, [String])]
- ghcPkgOptions :: MonadIO m => Query m [(ChComponentName, [String])]
- ghcMergedPkgOptions :: MonadIO m => Query m [String]
- ghcLangOptions :: MonadIO m => Query m [(ChComponentName, [String])]
- pkgLicenses :: MonadIO m => Query m [(String, [(String, Version)])]
- flags :: MonadIO m => Query m [(String, Bool)]
- configFlags :: MonadIO m => Query m [(String, Bool)]
- nonDefaultConfigFlags :: MonadIO m => Query m [(String, Bool)]
- packageId :: MonadIO m => Query m (String, Version)
- compilerVersion :: MonadIO m => Query m (String, Version)
- newtype ChModuleName = ChModuleName String
- data ChComponentName
  - = ChSetupHsName
  - | ChLibName String
  - | ChExeName String
  - | ChTestName String
  - | ChBenchName String
- data ChPkgDb
  - = ChPkgGlobal
  - | ChPkgUser
  - | ChPkgSpecific FilePath
- data ChEntrypoint
  - = ChSetupEntrypoint
  - | ChLibEntrypoint {
    - chExposedModules :: [ChModuleName]
    - chOtherModules :: [ChModuleName]
    }
  - | ChExeEntrypoint {
    - chMainIs :: FilePath
    - chOtherModules :: [ChModuleName]
    }
- buildPlatform :: (FilePath -> [String] -> String -> IO String) -> IO String
- getSandboxPkgDb :: (FilePath -> [String] -> String -> IO String) -> FilePath -> Version -> IO (Maybe FilePath)
- prepare :: MonadIO m => (FilePath -> [String] -> String -> IO String) -> FilePath -> FilePath -> m ()
- prepare' :: MonadIO m => QueryEnv -> m ()
- reconfigure :: MonadIO m => (FilePath -> [String] -> String -> IO String) -> Programs -> [String] -> m ()
- writeAutogenFiles :: MonadIO m => (FilePath -> [String] -> String -> IO String) -> FilePath -> FilePath -> m ()
- writeAutogenFiles' :: MonadIO m => QueryEnv -> m ()
- data LibexecNotFoundError = LibexecNotFoundError String FilePath
- libexecNotFoundError :: String -> FilePath -> String -> String

# Documentation

data Programs #

Paths or names of various programs we need.

Constructors

Programs |
Fields cabalProgram :: FilePath ghcProgram :: FilePath ghcPkgProgram :: FilePath

Instances

Eq Programs # |
Methods (==) :: Programs -> Programs -> Bool # (/=) :: Programs -> Programs -> Bool #
Ord Programs # |
Methods compare :: Programs -> Programs -> Ordering # (<) :: Programs -> Programs -> Bool # (<=) :: Programs -> Programs -> Bool # (>) :: Programs -> Programs -> Bool # (>=) :: Programs -> Programs -> Bool # max :: Programs -> Programs -> Programs # min :: Programs -> Programs -> Programs #
Read Programs # |
Methods readsPrec :: Int -> ReadS Programs # readList :: ReadS [Programs] # readPrec :: ReadPrec Programs # readListPrec :: ReadPrec [Programs] #
Show Programs # |
Methods showsPrec :: Int -> Programs -> ShowS # show :: Programs -> String # showList :: [Programs] -> ShowS #
Generic Programs # |
Associated Types type Rep Programs :: * -> * # Methods from :: Programs -> Rep Programs x # to :: Rep Programs x -> Programs #
type Rep Programs # |
type Rep Programs = D1 (MetaData "Programs" "Distribution.Helper" "cabal-helper-0.7.2.0-FH8IN284FwsJWBNgbaXomn" False) (C1 (MetaCons "Programs" PrefixI True) ((:*:) (S1 (MetaSel (Just Symbol "cabalProgram") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 FilePath)) ((:*:) (S1 (MetaSel (Just Symbol "ghcProgram") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 FilePath)) (S1 (MetaSel (Just Symbol "ghcPkgProgram") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 FilePath)))))

defaultPrograms :: Programs #

data QueryEnv #

qeReadProcess :: QueryEnv -> FilePath -> [String] -> String -> IO String #

How to start the cabal-helper process. Useful if you need to capture stderr output from the helper.

qePrograms :: QueryEnv -> Programs #

qeProjectDir :: QueryEnv -> FilePath #

Path to project directory, i.e. the one containing the `project.cabal` file

qeDistDir :: QueryEnv -> FilePath #

Path to the `dist/` directory

qeCabalPkgDb :: QueryEnv -> Maybe FilePath #

Where to look for the Cabal library when linking the helper

qeCabalVer :: QueryEnv -> Maybe Version #

If `dist/setup-config` wasn't written by this version of Cabal throw an error

defaultQueryEnv #

Arguments

:: FilePath | Path to project directory, i.e. the one containing the `project.cabal` file
-> FilePath | Path to the `dist/` directory
-> QueryEnv |

# Running Queries

data Query m a #

Caches helper executable result so it doesn't have to be run more than once as reading in Cabal's `LocalBuildInfo` datatype from disk is very slow but running all possible queries against it at once is cheap.

Instances

MonadTrans Query # |
Methods lift :: Monad m => m a -> Query m a #
Monad m => Monad (Query m) # |
Methods (>>=) :: Query m a -> (a -> Query m b) -> Query m b # (>>) :: Query m a -> Query m b -> Query m b # return :: a -> Query m a # fail :: String -> Query m a #
Functor m => Functor (Query m) # |
Methods fmap :: (a -> b) -> Query m a -> Query m b # (<$) :: a -> Query m b -> Query m a #
Monad m => Applicative (Query m) # |
Methods pure :: a -> Query m a # (<*>) :: Query m (a -> b) -> Query m a -> Query m b # (*>) :: Query m a -> Query m b -> Query m b # (<*) :: Query m a -> Query m b -> Query m a #
MonadIO m => MonadIO (Query m) # |
Methods liftIO :: IO a -> Query m a #

runQuery :: Monad m => QueryEnv -> Query m a -> m a #

`runQuery query distdir`. Run a `Query`. `distdir` is where Cabal's `setup-config` file is located.

# Queries against Cabal's on disk state

packageDbStack :: MonadIO m => Query m [ChPkgDb] #

List of package databases to use.

entrypoints :: MonadIO m => Query m [(ChComponentName, ChEntrypoint)] #

Modules or files Cabal would have the compiler build directly. Can be used to compute the home module closure for a component.

sourceDirs :: MonadIO m => Query m [(ChComponentName, [FilePath])] #

A component's `source-dirs` field, beware as if this is empty implicit behaviour in GHC kicks in.

ghcOptions :: MonadIO m => Query m [(ChComponentName, [String])] #

All options cabal would pass to GHC.

ghcSrcOptions :: MonadIO m => Query m [(ChComponentName, [String])] #

Only search path related GHC options.

ghcPkgOptions :: MonadIO m => Query m [(ChComponentName, [String])] #

Only package related GHC options, sufficient for things don't need to access any home modules.

ghcMergedPkgOptions :: MonadIO m => Query m [String] #

Like `ghcPkgOptions` but for the whole package not just one component

ghcLangOptions :: MonadIO m => Query m [(ChComponentName, [String])] #

Only language related options, i.e. `-XSomeExtension`

pkgLicenses :: MonadIO m => Query m [(String, [(String, Version)])] #

Get the licenses of the packages the current project is linking against.

flags :: MonadIO m => Query m [(String, Bool)] #

Flag definitions from cabal file

configFlags :: MonadIO m => Query m [(String, Bool)] #

Flag assignments from setup-config

nonDefaultConfigFlags :: MonadIO m => Query m [(String, Bool)] #

Flag assignments from setup-config which differ from the default setting. This can also include flags which cabal decided to modify, i.e. don't rely on these being the flags set by the user directly.

packageId :: MonadIO m => Query m (String, Version) #

Package identifier, i.e. package name and version

compilerVersion :: MonadIO m => Query m (String, Version) #

The version of GHC the project is configured to use

# Result types

newtype ChModuleName #

Constructors

ChModuleName String |

Instances

Eq ChModuleName # |
Methods (==) :: ChModuleName -> ChModuleName -> Bool # (/=) :: ChModuleName -> ChModuleName -> Bool #
Ord ChModuleName # |
Methods compare :: ChModuleName -> ChModuleName -> Ordering # (<) :: ChModuleName -> ChModuleName -> Bool # (<=) :: ChModuleName -> ChModuleName -> Bool # (>) :: ChModuleName -> ChModuleName -> Bool # (>=) :: ChModuleName -> ChModuleName -> Bool # max :: ChModuleName -> ChModuleName -> ChModuleName # min :: ChModuleName -> ChModuleName -> ChModuleName #
Read ChModuleName # |
Methods readsPrec :: Int -> ReadS ChModuleName # readList :: ReadS [ChModuleName] # readPrec :: ReadPrec ChModuleName # readListPrec :: ReadPrec [ChModuleName] #
Show ChModuleName # |
Methods showsPrec :: Int -> ChModuleName -> ShowS # show :: ChModuleName -> String # showList :: [ChModuleName] -> ShowS #
Generic ChModuleName # |
Associated Types type Rep ChModuleName :: * -> * # Methods from :: ChModuleName -> Rep ChModuleName x # to :: Rep ChModuleName x -> ChModuleName #
type Rep ChModuleName # |
type Rep ChModuleName = D1 (MetaData "ChModuleName" "CabalHelper.Types" "cabal-helper-0.7.2.0-FH8IN284FwsJWBNgbaXomn" True) (C1 (MetaCons "ChModuleName" PrefixI False) (S1 (MetaSel (Nothing Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 String)))

data ChComponentName #

Constructors

ChSetupHsName |
ChLibName String |
ChExeName String |
ChTestName String |
ChBenchName String |

Instances

Eq ChComponentName # |
Methods (==) :: ChComponentName -> ChComponentName -> Bool # (/=) :: ChComponentName -> ChComponentName -> Bool #
Ord ChComponentName # |
Methods compare :: ChComponentName -> ChComponentName -> Ordering # (<) :: ChComponentName -> ChComponentName -> Bool # (<=) :: ChComponentName -> ChComponentName -> Bool # (>) :: ChComponentName -> ChComponentName -> Bool # (>=) :: ChComponentName -> ChComponentName -> Bool # max :: ChComponentName -> ChComponentName -> ChComponentName # min :: ChComponentName -> ChComponentName -> ChComponentName #
Read ChComponentName # |
Methods readsPrec :: Int -> ReadS ChComponentName # readList :: ReadS [ChComponentName] # readPrec :: ReadPrec ChComponentName # readListPrec :: ReadPrec [ChComponentName] #
Show ChComponentName # |
Methods showsPrec :: Int -> ChComponentName -> ShowS # show :: ChComponentName -> String # showList :: [ChComponentName] -> ShowS #
Generic ChComponentName # |
Associated Types type Rep ChComponentName :: * -> * # Methods from :: ChComponentName -> Rep ChComponentName x # to :: Rep ChComponentName x -> ChComponentName #
type Rep ChComponentName # |
type Rep ChComponentName = D1 (MetaData "ChComponentName" "CabalHelper.Types" "cabal-helper-0.7.2.0-FH8IN284FwsJWBNgbaXomn" False) ((:+:) ((:+:) (C1 (MetaCons "ChSetupHsName" PrefixI False) U1) (C1 (MetaCons "ChLibName" PrefixI False) (S1 (MetaSel (Nothing Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 String)))) ((:+:) (C1 (MetaCons "ChExeName" PrefixI False) (S1 (MetaSel (Nothing Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 String))) ((:+:) (C1 (MetaCons "ChTestName" PrefixI False) (S1 (MetaSel (Nothing Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 String))) (C1 (MetaCons "ChBenchName" PrefixI False) (S1 (MetaSel (Nothing Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 String))))))

data ChPkgDb #

Constructors

ChPkgGlobal |
ChPkgUser |
ChPkgSpecific FilePath |

Instances

Eq ChPkgDb # |
Methods (==) :: ChPkgDb -> ChPkgDb -> Bool # (/=) :: ChPkgDb -> ChPkgDb -> Bool #
Ord ChPkgDb # |
Methods compare :: ChPkgDb -> ChPkgDb -> Ordering # (<) :: ChPkgDb -> ChPkgDb -> Bool # (<=) :: ChPkgDb -> ChPkgDb -> Bool # (>) :: ChPkgDb -> ChPkgDb -> Bool # (>=) :: ChPkgDb -> ChPkgDb -> Bool # max :: ChPkgDb -> ChPkgDb -> ChPkgDb # min :: ChPkgDb -> ChPkgDb -> ChPkgDb #
Read ChPkgDb # |
Methods readsPrec :: Int -> ReadS ChPkgDb # readList :: ReadS [ChPkgDb] # readPrec :: ReadPrec ChPkgDb # readListPrec :: ReadPrec [ChPkgDb] #
Show ChPkgDb # |
Methods showsPrec :: Int -> ChPkgDb -> ShowS # show :: ChPkgDb -> String # showList :: [ChPkgDb] -> ShowS #
Generic ChPkgDb # |
Associated Types type Rep ChPkgDb :: * -> * # Methods from :: ChPkgDb -> Rep ChPkgDb x # to :: Rep ChPkgDb x -> ChPkgDb #
type Rep ChPkgDb # |
type Rep ChPkgDb = D1 (MetaData "ChPkgDb" "CabalHelper.Types" "cabal-helper-0.7.2.0-FH8IN284FwsJWBNgbaXomn" False) ((:+:) (C1 (MetaCons "ChPkgGlobal" PrefixI False) U1) ((:+:) (C1 (MetaCons "ChPkgUser" PrefixI False) U1) (C1 (MetaCons "ChPkgSpecific" PrefixI False) (S1 (MetaSel (Nothing Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 FilePath)))))

data ChEntrypoint #

Constructors

ChSetupEntrypoint | Almost like `ChExeEntrypoint` but `main-is` could either be `"Setup.hs"` or `"Setup.lhs"`. Since we don't know where the source directory is you have to find these files.
ChLibEntrypoint |
Fields chExposedModules :: [ChModuleName] chOtherModules :: [ChModuleName]
ChExeEntrypoint |
Fields chMainIs :: FilePath chOtherModules :: [ChModuleName]

Instances

Eq ChEntrypoint # |
Methods (==) :: ChEntrypoint -> ChEntrypoint -> Bool # (/=) :: ChEntrypoint -> ChEntrypoint -> Bool #
Ord ChEntrypoint # |
Methods compare :: ChEntrypoint -> ChEntrypoint -> Ordering # (<) :: ChEntrypoint -> ChEntrypoint -> Bool # (<=) :: ChEntrypoint -> ChEntrypoint -> Bool # (>) :: ChEntrypoint -> ChEntrypoint -> Bool # (>=) :: ChEntrypoint -> ChEntrypoint -> Bool # max :: ChEntrypoint -> ChEntrypoint -> ChEntrypoint # min :: ChEntrypoint -> ChEntrypoint -> ChEntrypoint #
Read ChEntrypoint # |
Methods readsPrec :: Int -> ReadS ChEntrypoint # readList :: ReadS [ChEntrypoint] # readPrec :: ReadPrec ChEntrypoint # readListPrec :: ReadPrec [ChEntrypoint] #
Show ChEntrypoint # |
Methods showsPrec :: Int -> ChEntrypoint -> ShowS # show :: ChEntrypoint -> String # showList :: [ChEntrypoint] -> ShowS #
Generic ChEntrypoint # |
Associated Types type Rep ChEntrypoint :: * -> * # Methods from :: ChEntrypoint -> Rep ChEntrypoint x # to :: Rep ChEntrypoint x -> ChEntrypoint #
type Rep ChEntrypoint # |
type Rep ChEntrypoint = D1 (MetaData "ChEntrypoint" "CabalHelper.Types" "cabal-helper-0.7.2.0-FH8IN284FwsJWBNgbaXomn" False) ((:+:) (C1 (MetaCons "ChSetupEntrypoint" PrefixI False) U1) ((:+:) (C1 (MetaCons "ChLibEntrypoint" PrefixI True) ((:*:) (S1 (MetaSel (Just Symbol "chExposedModules") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 [ChModuleName])) (S1 (MetaSel (Just Symbol "chOtherModules") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 [ChModuleName])))) (C1 (MetaCons "ChExeEntrypoint" PrefixI True) ((:*:) (S1 (MetaSel (Just Symbol "chMainIs") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 FilePath)) (S1 (MetaSel (Just Symbol "chOtherModules") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 [ChModuleName]))))))

# General information

buildPlatform :: (FilePath -> [String] -> String -> IO String) -> IO String #

# Stuff that cabal-install really should export

getSandboxPkgDb #

Arguments

:: (FilePath -> [String] -> String -> IO String) |
-> FilePath | Cabal build platform, i.e. `buildPlatform`
-> Version | GHC version (`cProjectVersion` is your friend)
-> IO (Maybe FilePath) |

Get the path to the sandbox package-db in a project

# Managing `dist/`

prepare :: MonadIO m => (FilePath -> [String] -> String -> IO String) -> FilePath -> FilePath -> m () #

Deprecated: Will be replaced by prepare' in the next major release

prepare' :: MonadIO m => QueryEnv -> m () #

Make sure the appropriate helper executable for the given project is installed and ready to run queries.

reconfigure #

Arguments

:: MonadIO m |
=> (FilePath -> [String] -> String -> IO String) |
-> Programs | Program paths
-> [String] | Command line arguments to be passed to `cabal`
-> m () |

Run `cabal configure`

writeAutogenFiles #

Arguments

:: MonadIO m |
=> (FilePath -> [String] -> String -> IO String) |
-> FilePath | Path to project directory, i.e. the one containing the `project.cabal` file
-> FilePath | Path to the `dist/` directory
-> m () |

Deprecated: Will be replaced by writeAutogenFiles' in the next major release

writeAutogenFiles' :: MonadIO m => QueryEnv -> m () #

Create `cabal_macros.h` and `Paths_<pkg>` possibly other generated files in the usual place.

# $libexec related error handling

data LibexecNotFoundError #

This exception is thrown by all `runQuery` functions if the internal wrapper executable cannot be found. You may catch this and present the user an appropriate error message however the default is to print `libexecNotFoundError`.

Constructors

LibexecNotFoundError String FilePath |

Instances

Show LibexecNotFoundError # |
Methods showsPrec :: Int -> LibexecNotFoundError -> ShowS # show :: LibexecNotFoundError -> String # showList :: [LibexecNotFoundError] -> ShowS #
Exception LibexecNotFoundError # |
Methods toException :: LibexecNotFoundError -> SomeException # fromException :: SomeException -> Maybe LibexecNotFoundError # displayException :: LibexecNotFoundError -> String #

libexecNotFoundError #

Arguments

:: String | Name of the executable we were trying to find
-> FilePath | Path to `$libexecdir`
-> String | URL the user will be directed towards to report a bug.
-> String |