-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Simple interface to some of Cabal's configuration state used by ghc-mod
--   
--   <tt>cabal-helper</tt> provides a library which wraps the internal use
--   of an executable to lift the restrictions imposed by linking against
--   versions of GHC before <tt>7.10</tt>. This has the pleasant side
--   effect of isolating the user from having to deal with Cabal version
--   changes manually as <tt>cabal-helper</tt> can simply recompile it's
--   helper program automatically as needed.
--   
--   <tt>cabal-helper</tt> uses a wrapper executable to compile the actual
--   cabal-helper executable at runtime while linking against an arbitrary
--   version of Cabal. This runtime-compiled helper executable is then used
--   to extract various bits and peices from Cabal's on disk state
--   (dist/setup-config) written by it's configure command.
--   
--   In addition to this the wrapper executable also supports installing
--   any version of Cabal from hackage in case it cannot be found in any
--   available package database. The wrapper installs these instances of
--   the Cabal library into a private package database so as to not
--   interfere with the user's packages.
--   
--   Furthermore the wrapper supports one special case namely reading a
--   state file for Cabal itself. This is needed as Cabal compiles it's
--   Setup.hs using itself and not using any version of Cabal installed in
--   any package database.
--   
--   <tt>cabal-helper</tt> can compile with <tt>Cabal &gt;= 1.14</tt> but
--   requires <tt>Cabal &gt;= 1.16</tt> at runtime.
@package cabal-helper
@version 0.7.3.0

module Distribution.Helper

-- | Paths or names of various programs we need.
data Programs
Programs :: FilePath -> FilePath -> FilePath -> Programs
[cabalProgram] :: Programs -> FilePath
[ghcProgram] :: Programs -> FilePath
[ghcPkgProgram] :: Programs -> FilePath
defaultPrograms :: Programs
data QueryEnv

-- | How to start the cabal-helper process. Useful if you need to capture
--   stderr output from the helper.
qeReadProcess :: QueryEnv -> FilePath -> [String] -> String -> IO String
qePrograms :: QueryEnv -> Programs

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

-- | Path to the <tt>dist/</tt> directory
qeDistDir :: QueryEnv -> FilePath

-- | Where to look for the Cabal library when linking the helper
qeCabalPkgDb :: QueryEnv -> Maybe FilePath

-- | If <tt>dist/setup-config</tt> wasn't written by this version of Cabal
--   throw an error
qeCabalVer :: QueryEnv -> Maybe Version
defaultQueryEnv :: FilePath -> FilePath -> QueryEnv

-- | Caches helper executable result so it doesn't have to be run more than
--   once as reading in Cabal's <tt>LocalBuildInfo</tt> datatype from disk
--   is very slow but running all possible queries against it at once is
--   cheap.
data Query m a

-- | <tt>runQuery query distdir</tt>. Run a <a>Query</a>. <tt>distdir</tt>
--   is where Cabal's <tt>setup-config</tt> file is located.
runQuery :: Monad m => QueryEnv -> Query m a -> m a

-- | List of package databases to use.
packageDbStack :: MonadIO m => Query m [ChPkgDb]

-- | Modules or files Cabal would have the compiler build directly. Can be
--   used to compute the home module closure for a component.
entrypoints :: MonadIO m => Query m [(ChComponentName, ChEntrypoint)]

-- | A component's <tt>source-dirs</tt> field, beware as if this is empty
--   implicit behaviour in GHC kicks in.
sourceDirs :: MonadIO m => Query m [(ChComponentName, [FilePath])]

-- | All options cabal would pass to GHC.
ghcOptions :: MonadIO m => Query m [(ChComponentName, [String])]

-- | Only search path related GHC options.
ghcSrcOptions :: MonadIO m => Query m [(ChComponentName, [String])]

-- | Only package related GHC options, sufficient for things don't need to
--   access any home modules.
ghcPkgOptions :: MonadIO m => Query m [(ChComponentName, [String])]

-- | Like <tt>ghcPkgOptions</tt> but for the whole package not just one
--   component
ghcMergedPkgOptions :: MonadIO m => Query m [String]

-- | Only language related options, i.e. <tt>-XSomeExtension</tt>
ghcLangOptions :: MonadIO m => Query m [(ChComponentName, [String])]

-- | Get the licenses of the packages the current project is linking
--   against.
pkgLicenses :: MonadIO m => Query m [(String, [(String, Version)])]

-- | Flag definitions from cabal file
flags :: MonadIO m => Query m [(String, Bool)]

-- | Flag assignments from setup-config
configFlags :: 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.
nonDefaultConfigFlags :: MonadIO m => Query m [(String, Bool)]

-- | Package identifier, i.e. package name and version
packageId :: MonadIO m => Query m (String, Version)

-- | The version of GHC the project is configured to use
compilerVersion :: MonadIO m => Query m (String, Version)
newtype ChModuleName
ChModuleName :: String -> ChModuleName
data ChComponentName
ChSetupHsName :: ChComponentName
ChLibName :: String -> ChComponentName
ChExeName :: String -> ChComponentName
ChTestName :: String -> ChComponentName
ChBenchName :: String -> ChComponentName
data ChPkgDb
ChPkgGlobal :: ChPkgDb
ChPkgUser :: ChPkgDb
ChPkgSpecific :: FilePath -> ChPkgDb
data ChEntrypoint

-- | Almost like <a>ChExeEntrypoint</a> but <tt>main-is</tt> could either
--   be <tt>"Setup.hs"</tt> or <tt>"Setup.lhs"</tt>. Since we don't know
--   where the source directory is you have to find these files.
ChSetupEntrypoint :: ChEntrypoint
ChLibEntrypoint :: [ChModuleName] -> [ChModuleName] -> ChEntrypoint
[chExposedModules] :: ChEntrypoint -> [ChModuleName]
[chOtherModules] :: ChEntrypoint -> [ChModuleName]
ChExeEntrypoint :: FilePath -> [ChModuleName] -> ChEntrypoint
[chMainIs] :: ChEntrypoint -> FilePath
[chOtherModules] :: ChEntrypoint -> [ChModuleName]
buildPlatform :: (FilePath -> [String] -> String -> IO String) -> IO String

-- | Get the path to the sandbox package-db in a project
getSandboxPkgDb :: (FilePath -> [String] -> String -> IO String) -> FilePath -> Version -> IO (Maybe FilePath)

-- | <i>Deprecated: Will be replaced by prepare' in the next major
--   release</i>
prepare :: MonadIO m => (FilePath -> [String] -> String -> IO String) -> FilePath -> FilePath -> m ()

-- | Make sure the appropriate helper executable for the given project is
--   installed and ready to run queries.
prepare' :: MonadIO m => QueryEnv -> m ()

-- | Run <tt>cabal configure</tt>
reconfigure :: MonadIO m => (FilePath -> [String] -> String -> IO String) -> Programs -> [String] -> m ()

-- | <i>Deprecated: Will be replaced by writeAutogenFiles' in the next
--   major release</i>
writeAutogenFiles :: MonadIO m => (FilePath -> [String] -> String -> IO String) -> FilePath -> FilePath -> m ()

-- | Create <tt>cabal_macros.h</tt> and <tt>Paths_&lt;pkg&gt;</tt> possibly
--   other generated files in the usual place.
writeAutogenFiles' :: MonadIO m => QueryEnv -> m ()

-- | This exception is thrown by all <a>runQuery</a> 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 <a>libexecNotFoundError</a>.
data LibexecNotFoundError
LibexecNotFoundError :: String -> FilePath -> LibexecNotFoundError
libexecNotFoundError :: String -> FilePath -> String -> String
instance Control.Monad.IO.Class.MonadIO m => Control.Monad.IO.Class.MonadIO (Distribution.Helper.Query m)
instance GHC.Base.Monad m => GHC.Base.Monad (Distribution.Helper.Query m)
instance GHC.Base.Monad m => GHC.Base.Applicative (Distribution.Helper.Query m)
instance GHC.Base.Functor m => GHC.Base.Functor (Distribution.Helper.Query m)
instance GHC.Show.Show Distribution.Helper.SomeLocalBuildInfo
instance GHC.Read.Read Distribution.Helper.SomeLocalBuildInfo
instance GHC.Classes.Ord Distribution.Helper.SomeLocalBuildInfo
instance GHC.Classes.Eq Distribution.Helper.SomeLocalBuildInfo
instance GHC.Generics.Generic Distribution.Helper.Programs
instance GHC.Read.Read Distribution.Helper.Programs
instance GHC.Show.Show Distribution.Helper.Programs
instance GHC.Classes.Ord Distribution.Helper.Programs
instance GHC.Classes.Eq Distribution.Helper.Programs
instance Control.Monad.Trans.Class.MonadTrans Distribution.Helper.Query
instance GHC.Exception.Exception Distribution.Helper.LibexecNotFoundError
instance GHC.Show.Show Distribution.Helper.LibexecNotFoundError
