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


-- | Adds executable dependencies to the Cabal build
--   
--   Please see the README on GitHub at
--   <a>https://github.com/deech/cabal-build-programs#readme</a>
@package cabal-build-programs
@version 0.1.0.0

module Distribution.Simple.BuildPrograms

-- | The custom field to use in Cabal stanza to specify external programs.
--   In a ~.cabal~ file use:
--   
--   <pre>
--   x-build-programs: p1,p2,p3
--   </pre>
--   
--   whereas in the ~package.yaml~ of a <a>Stack</a> or <a>hpack</a>
--   project you must use (note that "p1,p2,p3" are quoted):
--   
--   <pre>
--   verbatim:
--     x-build-programs: "p1,p2,p3"
--   </pre>
buildProgramsCustomField :: String

-- | This function is the easiest way to use this library in your
--   <tt>Setup.hs</tt>.
--   
--   The default <tt>Setup.hs</tt>:
--   
--   <pre>
--   import Distribution.Simple
--   main = defaultMain
--   </pre>
--   
--   becomes:
--   
--   <pre>
--   import Distribution.Simple.BuildPrograms -- &lt;- only change
--   main = defaultMain
--   </pre>
defaultMain :: IO ()

-- | Directly access the <a>UserHooks</a> that back <a>defaultMain</a> when
--   you need finer grained control, they are backed by
--   <a>simpleUserHooks</a>:
--   
--   <pre>
--   import Distribution.Simple.BuildPrograms
--   import Distribution.Simple(defaultMainWithHooks)
--   main = defaultMainWithHooks buildProgramUserHooks
--   </pre>
buildProgramsUserHooks :: UserHooks

-- | This is the lowest level function provided by this library for use in
--   a highly customized <tt>Setup.hs</tt> scripts. Most of the other
--   functions wrap it in some way.
--   
--   <a>LocalBuildInfo</a> is a large datastructure that holds all the
--   information required to build a project, this function gathers up only
--   the components that need to be built ( or loaded in GHCi ), extracts
--   the programs in the "x-build-programs" fields, checks that they exist
--   and adds them as <tt>ConfiguredProgram</tt> to the <a>ProgramDb</a> of
--   the provided <a>LocalBuildInfo</a> and returns a new
--   <a>LocalBuildInfo</a> with the new <a>ProgramDb</a>.
--   
--   If any of the programs are cannot be found a formatted error message
--   is returned.
--   
--   The expectation is that it is called from a <a>buildHook</a> or a
--   <a>replHook</a> at some point before the components are built.
localBuildInfoWithBuildPrograms :: Args -> Verbosity -> [Program] -> PackageDescription -> LocalBuildInfo -> IO (Either String LocalBuildInfo)

-- | Used internally it figures out which components to build, extracts the
--   required external programs into a lookup table. To make debugging
--   easier I made it public so you print the table.
componentBuildPrograms :: Verbosity -> PackageDescription -> LocalBuildInfo -> Args -> IO [(Component, [String])]