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


-- | Simple interface to some of Cabal's configuration state, mainly used by ghc-mod
--   
--   Cabal's little helper provides access to build information gathered by
--   <tt>cabal</tt> when configuring a project. Specifically we're
--   interested in retrieving enough information to bring up a compiler
--   session, using the GHC API, which is similar to running <tt>cabal
--   repl</tt> in a project.
--   
--   While simple in principle this is complicated by the fact that the
--   information Cabal writes to disk is in an unstable format and only
--   really accessible through the Cabal API itself.
--   
--   Since we do not want to bind the user of a development tool which
--   utilises this library to a specific version of Cabal we compile the
--   code which interfaces with the Cabal library's API on the user's
--   machine, at runtime, against whichever version of Cabal was used to
--   write the on disk information for a given project.
--   
--   If this version of Cabal is not available on the users machine
--   anymore, which is fairly likely since cabal-install is usually linked
--   statically, we have support for compiling the Cabal library also. In
--   this case the library is installed into a private, isolated, package
--   database in <tt>$XDG_CACHE_HOME/cabal-helper</tt> so as to not
--   interfere with the user's package database.
@package cabal-helper
@version 0.8.0.2


module Distribution.Helper

-- | A lazy, cached, query against a package's Cabal configuration. Use
--   <a>runQuery</a> to execute it.
data Query m a

-- | <tt>runQuery env query</tt>. Run a <a>Query</a> under a given
--   <a>QueryEnv</a>.
runQuery :: Monad m => QueryEnv -> Query m a -> m a

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

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

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

-- | The version of GHC the project is configured to use
compilerVersion :: MonadIO m => Query m (String, Version)

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

-- | 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)]

-- | A <a>Query</a> to run on all components of a package. Use
--   <a>components</a> to get a regular <a>Query</a>.
data ComponentQuery m a

-- | Run a ComponentQuery on all components of the package.
components :: Monad m => ComponentQuery m (ChComponentName -> b) -> Query m [b]

-- | Only search path related GHC options.
ghcSrcOptions :: MonadIO m => ComponentQuery m [String]

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

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

-- | All options Cabal would pass to GHC.
ghcOptions :: MonadIO m => ComponentQuery m [String]

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

-- | 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 => ComponentQuery m ChEntrypoint

-- | The component has a non-default module renaming, so needs build output
--   ().
needsBuildOutput :: MonadIO m => ComponentQuery m NeedsBuildOutput

-- | Environment for running a <a>Query</a>. The real constructor is not
--   exposed, the field accessors are however. See below. Use the
--   <a>mkQueryEnv</a> smart constructor to construct one.
data QueryEnv

-- | <tt>mkQueryEnv projdir distdir</tt>. Smart constructor for
--   <a>QueryEnv</a>. Sets fields <a>qeProjectDir</a> and <a>qeDistDir</a>
--   to <tt>projdir</tt> and <tt>distdir</tt> respectively and provides
--   sensible defaults for the other fields.
mkQueryEnv :: FilePath -> FilePath -> QueryEnv

-- | Field accessor for <a>QueryEnv</a>. Defines 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

-- | Field accessor for <a>QueryEnv</a>.
qePrograms :: QueryEnv -> Programs

-- | Field accessor for <a>QueryEnv</a>. Defines path to the project
--   directory, i.e. a directory containing a <tt>project.cabal</tt> file
qeProjectDir :: QueryEnv -> FilePath

-- | Field accessor for <a>QueryEnv</a>. Defines path to the <tt>dist/</tt>
--   directory, <i>builddir</i> in Cabal terminology.
qeDistDir :: QueryEnv -> FilePath

-- | Field accessor for <a>QueryEnv</a>. Defines where to look for the
--   Cabal library when linking the helper.
qeCabalPkgDb :: QueryEnv -> Maybe FilePath

-- | Field accessor for <a>QueryEnv</a>. If <tt>dist/setup-config</tt>
--   wasn't written by this version of Cabal an error is thrown when
--   running the query.
qeCabalVer :: QueryEnv -> Maybe Version

-- | Paths or names of various programs we need.
data Programs
Programs :: FilePath -> FilePath -> FilePath -> Programs

-- | The path to the <tt>cabal</tt> program.
[cabalProgram] :: Programs -> FilePath

-- | The path to the <tt>ghc</tt> program.
[ghcProgram] :: Programs -> FilePath

-- | The path to the <tt>ghc-pkg</tt> program. If not changed it will be
--   derived from the path to <a>ghcProgram</a>.
[ghcPkgProgram] :: Programs -> FilePath

-- | Default all programs to their unqualified names, i.e. they will be
--   searched for on <tt>PATH</tt>.
defaultPrograms :: Programs
newtype ChModuleName
ChModuleName :: String -> ChModuleName
data ChComponentName
ChSetupHsName :: ChComponentName
ChLibName :: ChComponentName
ChSubLibName :: String -> ChComponentName
ChFLibName :: 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] -> [ChModuleName] -> ChEntrypoint
[chExposedModules] :: ChEntrypoint -> [ChModuleName]
[chOtherModules] :: ChEntrypoint -> [ChModuleName]
[chSignatures] :: ChEntrypoint -> [ChModuleName]
ChExeEntrypoint :: FilePath -> [ChModuleName] -> ChEntrypoint
[chMainIs] :: ChEntrypoint -> FilePath
[chOtherModules] :: ChEntrypoint -> [ChModuleName]
data NeedsBuildOutput
ProduceBuildOutput :: NeedsBuildOutput
NoBuildOutput :: NeedsBuildOutput
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)

-- | 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 ()

-- | 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 GHC.Base.Functor m => GHC.Base.Functor (Distribution.Helper.ComponentQuery m)
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 GHC.Exception.Exception Distribution.Helper.LibexecNotFoundError
instance GHC.Show.Show Distribution.Helper.LibexecNotFoundError
instance (GHC.Base.Functor m, GHC.Base.Monad m) => Data.Functor.Bind.Class.Apply (Distribution.Helper.ComponentQuery m)
instance Control.Monad.Trans.Class.MonadTrans Distribution.Helper.Query
