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


-- | Build system library, like Make, but more accurate dependencies.
--   
--   Shake is a Haskell library for writing build systems - designed as a
--   replacement for <tt>make</tt>. See <a>Development.Shake</a> for an
--   introduction, including an example. The homepage contains links to a
--   user manual, an academic paper and further information:
--   <a>https://shakebuild.com</a>
--   
--   To use Shake the user writes a Haskell program that imports
--   <a>Development.Shake</a>, defines some build rules, and calls the
--   <a>Development.Shake.shakeArgs</a> function. Thanks to do notation and
--   infix operators, a simple Shake build system is not too dissimilar
--   from a simple Makefile. However, as build systems get more complex,
--   Shake is able to take advantage of the excellent abstraction
--   facilities offered by Haskell and easily support much larger projects.
--   The Shake library provides all the standard features available in
--   other build systems, including automatic parallelism and minimal
--   rebuilds. Shake also provides more accurate dependency tracking,
--   including seamless support for generated files, and dependencies on
--   system information (e.g. compiler version).
@package shake
@version 0.19.8


-- | This module reexports the six necessary type classes that many rule
--   types must support through <tt>ShakeValue</tt>. You can use this
--   module to define new rules without depending on the <tt>binary</tt>,
--   <tt>deepseq</tt> and <tt>hashable</tt> packages.
module Development.Shake.Classes
class () => Show a
showsPrec :: Show a => Int -> a -> ShowS
show :: Show a => a -> String
showList :: Show a => [a] -> ShowS
class () => Typeable (a :: k)
class () => Eq a
(==) :: Eq a => a -> a -> Bool
(/=) :: Eq a => a -> a -> Bool
class Eq a => Hashable a
hashWithSalt :: Hashable a => Int -> a -> Int
hash :: Hashable a => a -> Int
class () => Binary t
put :: Binary t => t -> Put
get :: Binary t => Get t
putList :: Binary t => [t] -> Put
class () => NFData a
rnf :: NFData a => a -> ()


-- | A module for <a>FilePath</a> operations exposing
--   <a>System.FilePath</a> plus some additional operations.
--   
--   <i>Windows note:</i> The extension methods (<a>&lt;.&gt;</a>,
--   <a>takeExtension</a> etc) use the Posix variants since on Windows
--   <tt>"//*" <a>&lt;.&gt;</a> "txt"</tt> produces <tt>"//*\\.txt"</tt>
--   (which is bad for <a>FilePattern</a> values).
module Development.Shake.FilePath
type FilePath = String
takeDirectory :: FilePath -> FilePath
isPathSeparator :: Char -> Bool
(</>) :: FilePath -> FilePath -> FilePath
isRelative :: FilePath -> Bool
takeDrive :: FilePath -> FilePath
makeRelative :: FilePath -> FilePath -> FilePath
(-<.>) :: FilePath -> String -> FilePath
addTrailingPathSeparator :: FilePath -> FilePath
combine :: FilePath -> FilePath -> FilePath
dropDrive :: FilePath -> FilePath
dropFileName :: FilePath -> FilePath
dropTrailingPathSeparator :: FilePath -> FilePath
equalFilePath :: FilePath -> FilePath -> Bool
extSeparator :: Char
getSearchPath :: IO [FilePath]
hasDrive :: FilePath -> Bool
hasTrailingPathSeparator :: FilePath -> Bool
isAbsolute :: FilePath -> Bool
isDrive :: FilePath -> Bool
isExtSeparator :: Char -> Bool
isExtensionOf :: String -> FilePath -> Bool
isSearchPathSeparator :: Char -> Bool
isValid :: FilePath -> Bool
joinDrive :: FilePath -> FilePath -> FilePath
joinPath :: [FilePath] -> FilePath
makeValid :: FilePath -> FilePath
normalise :: FilePath -> FilePath
pathSeparator :: Char
pathSeparators :: [Char]
replaceBaseName :: FilePath -> String -> FilePath
replaceDirectory :: FilePath -> String -> FilePath
replaceExtensions :: FilePath -> String -> FilePath
replaceFileName :: FilePath -> String -> FilePath
searchPathSeparator :: Char
splitDirectories :: FilePath -> [FilePath]
splitDrive :: FilePath -> (FilePath, FilePath)
splitFileName :: FilePath -> (String, String)
splitPath :: FilePath -> [FilePath]
splitSearchPath :: String -> [FilePath]
stripExtension :: String -> FilePath -> Maybe FilePath
takeBaseName :: FilePath -> String
takeFileName :: FilePath -> FilePath
splitExtension :: FilePath -> (String, String)
takeExtension :: FilePath -> String
replaceExtension :: FilePath -> String -> FilePath
dropExtension :: FilePath -> FilePath
addExtension :: FilePath -> String -> FilePath
hasExtension :: FilePath -> Bool
(<.>) :: FilePath -> String -> FilePath
splitExtensions :: FilePath -> (FilePath, String)
takeExtensions :: FilePath -> String
dropExtensions :: FilePath -> FilePath

-- | Drop the first directory from a <a>FilePath</a>. Should only be used
--   on relative paths.
--   
--   <pre>
--   dropDirectory1 "aaa/bbb" == "bbb"
--   dropDirectory1 "aaa/" == ""
--   dropDirectory1 "aaa" == ""
--   dropDirectory1 "" == ""
--   </pre>
dropDirectory1 :: FilePath -> FilePath

-- | Take the first component of a <a>FilePath</a>. Should only be used on
--   relative paths.
--   
--   <pre>
--   takeDirectory1 "aaa/bbb" == "aaa"
--   takeDirectory1 "aaa/" == "aaa"
--   takeDirectory1 "aaa" == "aaa"
--   </pre>
takeDirectory1 :: FilePath -> FilePath

-- | Replace the first component of a <a>FilePath</a>. Should only be used
--   on relative paths.
--   
--   <pre>
--   replaceDirectory1 "root/file.ext" "directory" == "directory/file.ext"
--   replaceDirectory1 "root/foo/bar/file.ext" "directory" == "directory/foo/bar/file.ext"
--   </pre>
replaceDirectory1 :: FilePath -> String -> FilePath

-- | Make a path relative. Returns Nothing only when the given paths are on
--   different drives. This will try the pure function makeRelative first.
--   If that fails, the paths are canonicalised (removing any indirection
--   and symlinks) and a relative path is derived from there.
--   
--   <pre>
--   &gt; -- Given that "/root/a/" is not a symlink
--   &gt; makeRelativeEx "/root/a/" "/root/b/file.out"
--   Just "../b/file.out"
--   
--   &gt; -- Given that "/root/c/" is a symlink to "/root/e/f/g/"
--   &gt; makeRelativeEx "/root/c/" "/root/b/file.out"
--   Just "../../../b/file.out"
--   
--   &gt; -- On Windows
--   &gt; makeRelativeEx "C:\\foo" "D:\\foo\\bar"
--   Nothing
--   </pre>
makeRelativeEx :: FilePath -> FilePath -> IO (Maybe FilePath)

-- | Normalise a <a>FilePath</a>, applying the rules:
--   
--   <ul>
--   <li>All <a>pathSeparators</a> become <a>pathSeparator</a> (<tt>/</tt>
--   on Linux, <tt>\</tt> on Windows)</li>
--   <li><tt>foo/bar/../baz</tt> becomes <tt>foo/baz</tt> (not universally
--   true in the presence of symlinks)</li>
--   <li><tt>foo/./bar</tt> becomes <tt>foo/bar</tt></li>
--   <li><tt>foo//bar</tt> becomes <tt>foo/bar</tt></li>
--   </ul>
--   
--   This function is not based on the <a>normalise</a> function from the
--   <tt>filepath</tt> library, as that function is quite broken.
normaliseEx :: FilePath -> FilePath

-- | Convert to native path separators, namely <tt>\</tt> on Windows.
toNative :: FilePath -> FilePath

-- | Convert all path separators to <tt>/</tt>, even on Windows.
toStandard :: FilePath -> FilePath

-- | The extension of executables, <tt>"exe"</tt> on Windows and
--   <tt>""</tt> otherwise.
exe :: String


-- | This module is used for defining new types of rules for Shake build
--   systems, e.g. to support values stored in a database. Most users will
--   find the built-in set of rules sufficient. The functions in this
--   module are designed for high-performance, not ease of use or
--   abstraction. As a result, they are difficult to work with and change
--   more often than the other parts of Shake. Before writing a builtin
--   rule you are encouraged to use <a>addOracle</a> or
--   <a>addOracleCache</a> if possible. With all those warnings out the
--   way, read on for the grungy details.
module Development.Shake.Rule

-- | Before looking at this function, you should read the warnings at the
--   top of this module. This function is not often necessary in build
--   systems.
--   
--   Define a builtin rule, passing the functions to run in the right
--   circumstances. The <tt>key</tt> and <tt>value</tt> types will be what
--   is used by <a>apply</a>. As a start, you can use <a>noLint</a> and
--   <a>noIdentity</a> as the first two functions, but are required to
--   supply a suitable <a>BuiltinRun</a>.
--   
--   Raises an error if any other rule exists at this type.
--   
--   For a worked example of writing a rule see
--   <a>https://tech-blog.capital-match.com/posts/5-upgrading-shake.html</a>.
addBuiltinRule :: (RuleResult key ~ value, ShakeValue key, Typeable value, NFData value, Show value, Partial) => BuiltinLint key value -> BuiltinIdentity key value -> BuiltinRun key value -> Rules ()

-- | The action performed by <tt>--lint</tt> for a given
--   <tt>key</tt>/<tt>value</tt> pair. At the end of the build the lint
--   action will be called for each <tt>key</tt> that was built this run,
--   passing the <tt>value</tt> it produced. Return <a>Nothing</a> to
--   indicate the value has not changed and is acceptable, or <a>Just</a>
--   an error message to indicate failure.
--   
--   For builtin rules where the value is expected to change, or has no
--   useful checks to perform. use <a>noLint</a>.
type BuiltinLint key value = key -> value -> IO (Maybe String)

-- | A suitable <a>BuiltinLint</a> that always succeeds.
noLint :: BuiltinLint key value

-- | Produce an identity for a <tt>value</tt> that can be used to do direct
--   equality. If you have a custom notion of equality then the result
--   should return only one member from each equivalence class, as values
--   will be compared for literal equality. The result of the identity
--   should be reasonably short (if it is excessively long, hash it).
--   
--   For rules where the value is never compatible use <a>noIdentity</a>,
--   which returns <a>Nothing</a>. This will disable shared caches of
--   anything that depends on it.
type BuiltinIdentity key value = key -> value -> Maybe ByteString

-- | A suitable <a>BuiltinIdentity</a> that always fails with a runtime
--   error, incompatible with <a>shakeShare</a>. Use this function if you
--   don't care about <a>shakeShare</a>, or if your rule provides a
--   dependency that can never be cached (in which case you should also
--   call <a>historyDisable</a>).
noIdentity :: BuiltinIdentity key value

-- | Define a rule between <tt>key</tt> and <tt>value</tt>. As an example,
--   a typical <a>BuiltinRun</a> will look like:
--   
--   <pre>
--   run key oldStore mode = do
--       ...
--       pure $ RunResult change newStore newValue
--   </pre>
--   
--   Where you have:
--   
--   <ul>
--   <li><tt>key</tt>, how to identify individual artifacts, e.g. with file
--   names.</li>
--   <li><tt>oldStore</tt>, the value stored in the database previously,
--   e.g. the file modification time.</li>
--   <li><tt>mode</tt>, either <a>RunDependenciesSame</a> (none of your
--   dependencies changed, you can probably not rebuild) or
--   <a>RunDependenciesChanged</a> (your dependencies changed, probably
--   rebuild).</li>
--   <li><tt>change</tt>, usually one of either <a>ChangedNothing</a> (no
--   work was required) or <a>ChangedRecomputeDiff</a> (I reran the rule
--   and it should be considered different).</li>
--   <li><tt>newStore</tt>, the new value to store in the database, which
--   will be passed in next time as <tt>oldStore</tt>.</li>
--   <li><tt>newValue</tt>, the result that <a>apply</a> will return when
--   asked for the given <tt>key</tt>.</li>
--   </ul>
type BuiltinRun key value = key -> Maybe ByteString -> RunMode -> Action (RunResult value)

-- | What mode a rule is running in, passed as an argument to
--   <a>BuiltinRun</a>.
data RunMode

-- | My dependencies have not changed.
RunDependenciesSame :: RunMode

-- | At least one of my dependencies from last time have changed, or I have
--   no recorded dependencies.
RunDependenciesChanged :: RunMode

-- | How the output of a rule has changed.
data RunChanged

-- | Nothing has changed.
ChangedNothing :: RunChanged

-- | The stored value has changed, but in a way that should be considered
--   identical (used rarely).
ChangedStore :: RunChanged

-- | I recomputed the value and it was the same.
ChangedRecomputeSame :: RunChanged

-- | I recomputed the value and it was different.
ChangedRecomputeDiff :: RunChanged

-- | The result of <a>BuiltinRun</a>.
data RunResult value
RunResult :: RunChanged -> ByteString -> value -> RunResult value

-- | How has the <a>RunResult</a> changed from what happened last time.
[runChanged] :: RunResult value -> RunChanged

-- | The value to store in the Shake database.
[runStore] :: RunResult value -> ByteString

-- | The value to return from <a>apply</a>.
[runValue] :: RunResult value -> value

-- | Execute a rule, returning the associated values. If possible, the
--   rules will be run in parallel. This function requires that appropriate
--   rules have been added with <a>addBuiltinRule</a>. All <tt>key</tt>
--   values passed to <a>apply</a> become dependencies of the
--   <a>Action</a>.
apply :: (Partial, RuleResult key ~ value, ShakeValue key, Typeable value) => [key] -> Action [value]

-- | Apply a single rule, equivalent to calling <a>apply</a> with a
--   singleton list. Where possible, use <a>apply</a> to allow parallelism.
apply1 :: (Partial, RuleResult key ~ value, ShakeValue key, Typeable value) => key -> Action value

-- | Add a user rule. In general these should be specialised to the type
--   expected by a builtin rule. The user rules can be retrieved by
--   <a>getUserRuleList</a>.
addUserRule :: Typeable a => a -> Rules ()

-- | Get the user rules that were added at a particular type which return
--   <a>Just</a> on a given function. Return all equally applicable rules,
--   paired with the version of the rule (set by <a>versioned</a>). Where
--   rules are specified with <a>alternatives</a> or <a>priority</a> the
--   less-applicable rules will not be returned.
--   
--   If you can only deal with zero/one results, call
--   <a>getUserRuleMaybe</a> or <a>getUserRuleOne</a>, which raise
--   informative errors.
getUserRuleList :: Typeable a => (a -> Maybe b) -> Action [(Int, b)]

-- | A version of <a>getUserRuleList</a> that fails if there is more than
--   one result Requires a <tt>key</tt> for better error messages.
getUserRuleMaybe :: (ShakeValue key, Typeable a) => key -> (a -> Maybe String) -> (a -> Maybe b) -> Action (Maybe (Int, b))

-- | A version of <a>getUserRuleList</a> that fails if there is not exactly
--   one result Requires a <tt>key</tt> for better error messages.
getUserRuleOne :: (ShakeValue key, Typeable a) => key -> (a -> Maybe String) -> (a -> Maybe b) -> Action (Int, b)

-- | Track that a key has been used/read by the action preceding it when
--   <a>shakeLint</a> is active.
lintTrackRead :: ShakeValue key => [key] -> Action ()

-- | Track that a key has been changed/written by the action preceding it
--   when <a>shakeLint</a> is active.
lintTrackWrite :: ShakeValue key => [key] -> Action ()

-- | Allow any matching key recorded with <a>lintTrackRead</a> or
--   <a>lintTrackWrite</a> in this action, after this call, to violate the
--   tracking rules.
lintTrackAllow :: ShakeValue key => (key -> Bool) -> Action ()

-- | Is the history enabled, returns <a>True</a> if you have a
--   <a>shakeShare</a> or <a>shakeCloud</a>, and haven't called
--   <a>historyDisable</a> so far in this rule.
historyIsEnabled :: Action Bool

-- | Save a value to the history. Record the version of any user rule (or
--   <tt>0</tt>), and a payload. Must be run at the end of the rule, after
--   any dependencies have been captured. If history is enabled, stores the
--   information in a cache.
--   
--   This function relies on <tt>produces</tt> to have been called
--   correctly to describe which files were written during the execution of
--   this rule.
historySave :: Int -> ByteString -> Action ()

-- | Load a value from the history. Given a version from any user rule (or
--   <tt>0</tt>), return the payload that was stored by <a>historySave</a>.
--   
--   If this function returns <a>Just</a> it will also have restored any
--   files that were saved by <a>historySave</a>.
historyLoad :: Int -> Action (Maybe ByteString)


-- | This module provides functions for calling command line programs,
--   primarily <a>command</a> and <a>cmd</a>. As a simple example:
--   
--   <pre>
--   <a>command</a> [] "gcc" ["-c",myfile]
--   </pre>
--   
--   The functions from this module are now available directly from
--   <a>Development.Shake</a>. You should only need to import this module
--   if you are using the <a>cmd</a> function in the <a>IO</a> monad.
module Development.Shake.Command

-- | Execute a system command. Before running <a>command</a> make sure you
--   <a>need</a> any files that are used by the command.
--   
--   This function takes a list of options (often just <tt>[]</tt>, see
--   <a>CmdOption</a> for the available options), the name of the
--   executable (either a full name, or a program on the <tt>$PATH</tt>)
--   and a list of arguments. The result is often <tt>()</tt>, but can be a
--   tuple containg any of <a>Stdout</a>, <a>Stderr</a> and <a>Exit</a>.
--   Some examples:
--   
--   <pre>
--   <a>command_</a> [] "gcc" ["-c","myfile.c"]                          -- compile a file, throwing an exception on failure
--   <a>Exit</a> c &lt;- <a>command</a> [] "gcc" ["-c",myfile]                     -- run a command, recording the exit code
--   (<a>Exit</a> c, <a>Stderr</a> err) &lt;- <a>command</a> [] "gcc" ["-c","myfile.c"]   -- run a command, recording the exit code and error output
--   <a>Stdout</a> out &lt;- <a>command</a> [] "gcc" ["-MM","myfile.c"]            -- run a command, recording the output
--   <a>command_</a> [<a>Cwd</a> "generated"] "gcc" ["-c",myfile]               -- run a command in a directory
--   </pre>
--   
--   Unless you retrieve the <a>ExitCode</a> using <a>Exit</a>, any
--   <a>ExitFailure</a> will throw an error, including the <a>Stderr</a> in
--   the exception message. If you capture the <a>Stdout</a> or
--   <a>Stderr</a>, that stream will not be echoed to the console, unless
--   you use the option <a>EchoStdout</a> or <a>EchoStderr</a>.
--   
--   If you use <a>command</a> inside a <tt>do</tt> block and do not use
--   the result, you may get a compile-time error about being unable to
--   deduce <a>CmdResult</a>. To avoid this error, use <a>command_</a>.
--   
--   By default the <tt>stderr</tt> stream will be captured for use in
--   error messages, and also echoed. To only echo pass
--   <tt><a>WithStderr</a> <a>False</a></tt>, which causes no streams to be
--   captured by Shake, and certain programs (e.g. <tt>gcc</tt>) to detect
--   they are running in a terminal.
command :: (Partial, CmdResult r) => [CmdOption] -> String -> [String] -> Action r

-- | A version of <a>command</a> where you do not require any results, used
--   to avoid errors about being unable to deduce <a>CmdResult</a>.
command_ :: Partial => [CmdOption] -> String -> [String] -> Action ()

-- | Build or execute a system command. Before using <a>cmd</a> to run a
--   command, make sure you <a>need</a> any files that are used by the
--   command.
--   
--   <ul>
--   <li><tt>String</tt> arguments are treated as a list of whitespace
--   separated arguments.</li>
--   <li><tt>[String]</tt> arguments are treated as a list of literal
--   arguments.</li>
--   <li><a>CmdOption</a> arguments are used as options.</li>
--   <li><a>CmdArgument</a> arguments, which can be built by <a>cmd</a>
--   itself, are spliced into the containing command.</li>
--   </ul>
--   
--   Typically only string literals should be passed as <tt>String</tt>
--   arguments. When using variables prefer <tt>[myvar]</tt> so that if
--   <tt>myvar</tt> contains spaces they are properly escaped.
--   
--   As some examples, here are some calls, and the resulting command
--   string:
--   
--   <pre>
--   <a>cmd_</a> "git log --pretty=" "oneline"           -- git log --pretty= oneline
--   <a>cmd_</a> "git log --pretty=" ["oneline"]         -- git log --pretty= oneline
--   <a>cmd_</a> "git log" ("--pretty=" ++ "oneline")    -- git log --pretty=oneline
--   <a>cmd_</a> "git log" ("--pretty=" ++ "one line")   -- git log --pretty=one line
--   <a>cmd_</a> "git log" ["--pretty=" ++ "one line"]   -- git log "--pretty=one line"
--   </pre>
--   
--   More examples, including return values, see this translation of the
--   examples given for the <a>command</a> function:
--   
--   <pre>
--   <a>cmd_</a> "gcc -c myfile.c"                                       -- compile a file, throwing an exception on failure
--   <a>Exit</a> c &lt;- <a>cmd</a> "gcc -c" [myfile]                              -- run a command, recording the exit code
--   (<a>Exit</a> c, <a>Stderr</a> err) &lt;- <a>cmd</a> "gcc -c myfile.c"                -- run a command, recording the exit code and error output
--   <a>Stdout</a> out &lt;- <a>cmd</a> "gcc -MM myfile.c"                         -- run a command, recording the output
--   <a>cmd</a> (<a>Cwd</a> "generated") "gcc -c" [myfile] :: <a>Action</a> ()         -- run a command in a directory
--   
--   let gccCommand = <a>cmd</a> "gcc -c" :: <a>CmdArgument</a>                 -- build a sub-command. <a>cmd</a> can return <a>CmdArgument</a> values as well as execute commands
--   cmd (<a>Cwd</a> "generated") gccCommand [myfile]                 -- splice that command into a greater command
--   </pre>
--   
--   If you use <a>cmd</a> inside a <tt>do</tt> block and do not use the
--   result, you may get a compile-time error about being unable to deduce
--   <a>CmdResult</a>. To avoid this error, use <a>cmd_</a>. If you enable
--   <tt>OverloadedStrings</tt> or <tt>OverloadedLists</tt> you may have to
--   give type signatures to the arguments, or use the more constrained
--   <a>command</a> instead.
--   
--   The <a>cmd</a> function can also be run in the <a>IO</a> monad, but
--   then <a>Traced</a> is ignored and command lines are not echoed. As an
--   example:
--   
--   <pre>
--   <a>cmd</a> (<a>Cwd</a> "generated") <a>Shell</a> "gcc -c myfile.c" :: IO ()
--   </pre>
cmd :: (Partial, CmdArguments args) => args :-> Action r

-- | See <a>cmd</a>. Same as <a>cmd</a> except with a unit result.
--   <a>cmd</a> is to <a>cmd_</a> as <a>command</a> is to <a>command_</a>.
cmd_ :: (Partial, CmdArguments args, Unit args) => args :-> Action ()
unit :: m () -> m ()

-- | The arguments to <a>cmd</a> - see <a>cmd</a> for examples and
--   semantics.
newtype CmdArgument
CmdArgument :: [Either CmdOption String] -> CmdArgument

-- | The arguments to <a>cmd</a> - see <a>cmd</a> for examples and
--   semantics.
class CmdArguments t

-- | Arguments to cmd
cmdArguments :: (CmdArguments t, Partial) => CmdArgument -> t

-- | Class to convert an a to a CmdArgument
class IsCmdArgument a

-- | Conversion to a CmdArgument
toCmdArgument :: IsCmdArgument a => a -> CmdArgument

-- | A type annotation, equivalent to the first argument, but in variable
--   argument contexts, gives a clue as to what return type is expected
--   (not actually enforced).
type a :-> t = a

-- | Collect the <tt>stdout</tt> of the process. If used, the
--   <tt>stdout</tt> will not be echoed to the terminal, unless you include
--   <a>EchoStdout</a>. The value type may be either <a>String</a>, or
--   either lazy or strict <tt>ByteString</tt>.
--   
--   Note that most programs end their output with a trailing newline, so
--   calling <tt>ghc --numeric-version</tt> will result in <a>Stdout</a> of
--   <tt>"6.8.3\n"</tt>. If you want to automatically trim the resulting
--   string, see <a>StdoutTrim</a>.
newtype Stdout a
Stdout :: a -> Stdout a
[fromStdout] :: Stdout a -> a

-- | Like <a>Stdout</a> but remove all leading and trailing whitespaces.
newtype StdoutTrim a
StdoutTrim :: a -> StdoutTrim a
[fromStdoutTrim] :: StdoutTrim a -> a

-- | Collect the <tt>stderr</tt> of the process. If used, the
--   <tt>stderr</tt> will not be echoed to the terminal, unless you include
--   <a>EchoStderr</a>. The value type may be either <a>String</a>, or
--   either lazy or strict <tt>ByteString</tt>.
newtype Stderr a
Stderr :: a -> Stderr a
[fromStderr] :: Stderr a -> a

-- | Collect the <tt>stdout</tt> and <tt>stderr</tt> of the process. If
--   used, the <tt>stderr</tt> and <tt>stdout</tt> will not be echoed to
--   the terminal, unless you include <a>EchoStdout</a> and
--   <a>EchoStderr</a>. The value type may be either <a>String</a>, or
--   either lazy or strict <tt>ByteString</tt>.
newtype Stdouterr a
Stdouterr :: a -> Stdouterr a
[fromStdouterr] :: Stdouterr a -> a

-- | Collect the <a>ExitCode</a> of the process. If you do not collect the
--   exit code, any <a>ExitFailure</a> will cause an exception.
newtype Exit
Exit :: ExitCode -> Exit
[fromExit] :: Exit -> ExitCode

-- | Collect the <a>ProcessHandle</a> of the process. If you do collect the
--   process handle, the command will run asyncronously and the call to
--   <a>cmd</a> / <a>command</a> will return as soon as the process is
--   spawned. Any <a>Stdout</a> / <a>Stderr</a> captures will return empty
--   strings.
newtype Process
Process :: ProcessHandle -> Process
[fromProcess] :: Process -> ProcessHandle

-- | Collect the time taken to execute the process. Can be used in
--   conjunction with <a>CmdLine</a> to write helper functions that print
--   out the time of a result.
--   
--   <pre>
--   timer :: (<a>CmdResult</a> r, MonadIO m) =&gt; (forall r . <a>CmdResult</a> r =&gt; m r) -&gt; m r
--   timer act = do
--       (<a>CmdTime</a> t, <a>CmdLine</a> x, r) &lt;- act
--       liftIO $ putStrLn $ "Command " ++ x ++ " took " ++ show t ++ " seconds"
--       pure r
--   
--   run :: IO ()
--   run = timer $ <a>cmd</a> "ghc --version"
--   </pre>
newtype CmdTime
CmdTime :: Double -> CmdTime
[fromCmdTime] :: CmdTime -> Double

-- | Collect the command line used for the process. This command line will
--   be approximate - suitable for user diagnostics, but not for direct
--   execution.
newtype CmdLine
CmdLine :: String -> CmdLine
[fromCmdLine] :: CmdLine -> String

-- | The results produced by <tt>fsatrace</tt>. All files will be absolute
--   paths. You can get the results for a <a>cmd</a> by requesting a value
--   of type <tt>[<a>FSATrace</a>]</tt>.
data FSATrace a

-- | Writing to a file
FSAWrite :: a -> FSATrace a

-- | Reading from a file
FSARead :: a -> FSATrace a

-- | Deleting a file
FSADelete :: a -> FSATrace a

-- | Moving, arguments destination, then source
FSAMove :: a -> a -> FSATrace a

-- | Querying/stat on a file
FSAQuery :: a -> FSATrace a

-- | Touching a file
FSATouch :: a -> FSATrace a

-- | A class for specifying what results you want to collect from a
--   process. Values are formed of <a>Stdout</a>, <a>Stderr</a>,
--   <a>Exit</a> and tuples of those.
class CmdResult a

-- | The allowable <a>String</a>-like values that can be captured.
class CmdString a

-- | Options passed to <tt>command</tt> or <tt>cmd</tt> to control how
--   processes are executed.
data CmdOption

-- | Change the current directory in the spawned process. By default uses
--   this processes current directory. Successive <a>Cwd</a> options are
--   joined together, to change into nested directories.
Cwd :: FilePath -> CmdOption

-- | Change the environment variables in the spawned process. By default
--   uses this processes environment.
Env :: [(String, String)] -> CmdOption

-- | Add an environment variable in the child process.
AddEnv :: String -> String -> CmdOption

-- | Remove an environment variable from the child process.
RemEnv :: String -> CmdOption

-- | Add some items to the prefix and suffix of the <tt>$PATH</tt>
--   variable.
AddPath :: [String] -> [String] -> CmdOption

-- | Given as the <tt>stdin</tt> of the spawned process.
Stdin :: String -> CmdOption

-- | Given as the <tt>stdin</tt> of the spawned process.
StdinBS :: ByteString -> CmdOption

-- | Take the <tt>stdin</tt> from a file.
FileStdin :: FilePath -> CmdOption

-- | Pass the command to the shell without escaping - any arguments will be
--   joined with spaces. By default arguments are escaped properly.
Shell :: CmdOption

-- | Treat the <tt>stdin</tt>/<tt>stdout</tt>/<tt>stderr</tt> messages as
--   binary. By default <a>String</a> results use text encoding and
--   <tt>ByteString</tt> results use binary encoding.
BinaryPipes :: CmdOption

-- | Name to use with <tt>traced</tt>, or <tt>""</tt> for no tracing. By
--   default traces using the name of the executable.
Traced :: String -> CmdOption

-- | Abort the computation after N seconds, will raise a failure exit code.
--   Calls <tt>interruptProcessGroupOf</tt> and <tt>terminateProcess</tt>,
--   but may sometimes fail to abort the process and not timeout.
Timeout :: Double -> CmdOption

-- | Should I include the <tt>stdout</tt> in the exception if the command
--   fails? Defaults to <a>False</a>.
WithStdout :: Bool -> CmdOption

-- | Should I include the <tt>stderr</tt> in the exception if the command
--   fails? Defaults to <a>True</a>.
WithStderr :: Bool -> CmdOption

-- | Should I echo the <tt>stdout</tt>? Defaults to <a>True</a> unless a
--   <tt>Stdout</tt> result is required or you use <a>FileStdout</a>.
EchoStdout :: Bool -> CmdOption

-- | Should I echo the <tt>stderr</tt>? Defaults to <a>True</a> unless a
--   <tt>Stderr</tt> result is required or you use <a>FileStderr</a>.
EchoStderr :: Bool -> CmdOption

-- | Should I put the <tt>stdout</tt> to a file.
FileStdout :: FilePath -> CmdOption

-- | Should I put the <tt>stderr</tt> to a file.
FileStderr :: FilePath -> CmdOption

-- | Compute dependencies automatically. Only works if
--   <tt>shakeLintInside</tt> has been set to the files where autodeps
--   might live.
AutoDeps :: CmdOption

-- | The command the user thinks about, before any munging. Defaults to the
--   actual command.
UserCommand :: String -> CmdOption

-- | Options to <tt>fsatrace</tt>, a list of strings with characters such
--   as <tt>"r"</tt> (reads) <tt>"w"</tt> (writes). Defaults to
--   <tt>"rwmdqt"</tt> if the output of <tt>fsatrace</tt> is required.
FSAOptions :: String -> CmdOption

-- | Before starting the command in the child process, close all file
--   handles except stdin, stdout, stderr in the child process. Uses
--   <tt>close_fds</tt> from package process and comes with the same
--   caveats, i.e. runtime is linear with the maximum number of open file
--   handles (<tt>RLIMIT_NOFILE</tt>, see <tt>man 2 getrlimit</tt> on
--   Linux).
CloseFileHandles :: CmdOption

-- | Don't run the process in its own group. Required when running
--   <tt>docker</tt>. Will mean that process timeouts and asyncronous
--   exceptions may not properly clean up child processes.
NoProcessGroup :: CmdOption

-- | Cause the stdin from the parent to be inherited. Might also require
--   NoProcessGroup on Linux. Ignored if you explicitly pass a stdin.
InheritStdin :: CmdOption

-- | <i>Deprecated:</i> Use <a>AddPath</a>. This function will be removed
--   in a future version.
--   
--   Add a prefix and suffix to the <tt>$PATH</tt> environment variable.
--   For example:
--   
--   <pre>
--   opt &lt;- <a>addPath</a> ["/usr/special"] []
--   <a>cmd</a> opt "userbinary --version"
--   </pre>
--   
--   Would prepend <tt>/usr/special</tt> to the current <tt>$PATH</tt>, and
--   the command would pick <tt>/usr/special/userbinary</tt>, if it exists.
--   To add other variables see <a>addEnv</a>.
addPath :: MonadIO m => [String] -> [String] -> m CmdOption

-- | <i>Deprecated:</i> Use <a>AddEnv</a>. This function will be removed in
--   a future version.
--   
--   Add a single variable to the environment. For example:
--   
--   <pre>
--   opt &lt;- <a>addEnv</a> [("CFLAGS","-O2")]
--   <a>cmd</a> opt "gcc -c main.c"
--   </pre>
--   
--   Would add the environment variable <tt>$CFLAGS</tt> with value
--   <tt>-O2</tt>. If the variable <tt>$CFLAGS</tt> was already defined it
--   would be overwritten. If you wish to modify <tt>$PATH</tt> see
--   <a>addPath</a>.
addEnv :: MonadIO m => [(String, String)] -> m CmdOption
instance GHC.Show.Show Development.Shake.Command.Str
instance GHC.Classes.Eq Development.Shake.Command.Str
instance GHC.Base.Functor Development.Shake.Command.FSATrace
instance Data.Data.Data a => Data.Data.Data (Development.Shake.Command.FSATrace a)
instance GHC.Classes.Ord a => GHC.Classes.Ord (Development.Shake.Command.FSATrace a)
instance GHC.Classes.Eq a => GHC.Classes.Eq (Development.Shake.Command.FSATrace a)
instance GHC.Show.Show a => GHC.Show.Show (Development.Shake.Command.FSATrace a)
instance GHC.Show.Show Development.Shake.Command.Result
instance GHC.Classes.Eq Development.Shake.Command.Result
instance GHC.Show.Show Development.Shake.Command.Params
instance GHC.Show.Show Development.Shake.Command.CmdArgument
instance GHC.Base.Monoid Development.Shake.Command.CmdArgument
instance GHC.Base.Semigroup Development.Shake.Command.CmdArgument
instance GHC.Classes.Eq Development.Shake.Command.CmdArgument
instance (Development.Shake.Command.IsCmdArgument a, Development.Shake.Command.CmdArguments r) => Development.Shake.Command.CmdArguments (a -> r)
instance Development.Shake.Command.IsCmdArgument ()
instance Development.Shake.Command.IsCmdArgument GHC.Base.String
instance Development.Shake.Command.IsCmdArgument [GHC.Base.String]
instance Development.Shake.Command.IsCmdArgument (GHC.Base.NonEmpty GHC.Base.String)
instance Development.Shake.Command.IsCmdArgument Development.Shake.Internal.CmdOption.CmdOption
instance Development.Shake.Command.IsCmdArgument [Development.Shake.Internal.CmdOption.CmdOption]
instance Development.Shake.Command.IsCmdArgument Development.Shake.Command.CmdArgument
instance Development.Shake.Command.IsCmdArgument a => Development.Shake.Command.IsCmdArgument (GHC.Maybe.Maybe a)
instance Development.Shake.Command.CmdResult r => Development.Shake.Command.CmdArguments (Development.Shake.Internal.Core.Types.Action r)
instance Development.Shake.Command.CmdResult r => Development.Shake.Command.CmdArguments (GHC.Types.IO r)
instance Development.Shake.Command.CmdArguments Development.Shake.Command.CmdArgument
instance Development.Shake.Command.CmdResult Development.Shake.Command.Exit
instance Development.Shake.Command.CmdResult GHC.IO.Exception.ExitCode
instance Development.Shake.Command.CmdResult Development.Shake.Command.Process
instance Development.Shake.Command.CmdResult System.Process.Common.ProcessHandle
instance Development.Shake.Command.CmdResult Development.Shake.Command.CmdLine
instance Development.Shake.Command.CmdResult Development.Shake.Command.CmdTime
instance Development.Shake.Command.CmdResult [Development.Shake.Command.FSATrace GHC.IO.FilePath]
instance Development.Shake.Command.CmdResult [Development.Shake.Command.FSATrace Data.ByteString.Internal.Type.ByteString]
instance Development.Shake.Command.CmdString a => Development.Shake.Command.CmdResult (Development.Shake.Command.Stdout a)
instance Development.Shake.Command.CmdString a => Development.Shake.Command.CmdResult (Development.Shake.Command.StdoutTrim a)
instance Development.Shake.Command.CmdString a => Development.Shake.Command.CmdResult (Development.Shake.Command.Stderr a)
instance Development.Shake.Command.CmdString a => Development.Shake.Command.CmdResult (Development.Shake.Command.Stdouterr a)
instance Development.Shake.Command.CmdResult ()
instance (Development.Shake.Command.CmdResult x1, Development.Shake.Command.CmdResult x2) => Development.Shake.Command.CmdResult (x1, x2)
instance (Development.Shake.Command.CmdResult x1, Development.Shake.Command.CmdResult x2, Development.Shake.Command.CmdResult x3) => Development.Shake.Command.CmdResult (x1, x2, x3)
instance (Development.Shake.Command.CmdResult x1, Development.Shake.Command.CmdResult x2, Development.Shake.Command.CmdResult x3, Development.Shake.Command.CmdResult x4) => Development.Shake.Command.CmdResult (x1, x2, x3, x4)
instance (Development.Shake.Command.CmdResult x1, Development.Shake.Command.CmdResult x2, Development.Shake.Command.CmdResult x3, Development.Shake.Command.CmdResult x4, Development.Shake.Command.CmdResult x5) => Development.Shake.Command.CmdResult (x1, x2, x3, x4, x5)
instance Development.Shake.Command.Unit b => Development.Shake.Command.Unit (a -> b)
instance (a GHC.Types.~ ()) => Development.Shake.Command.Unit (m a)
instance Development.Shake.Command.CmdString ()
instance Development.Shake.Command.CmdString GHC.Base.String
instance Development.Shake.Command.CmdString Data.ByteString.Internal.Type.ByteString
instance Development.Shake.Command.CmdString Data.ByteString.Lazy.Internal.ByteString
instance Development.Shake.Command.MonadTempDir GHC.Types.IO
instance Development.Shake.Command.MonadTempDir Development.Shake.Internal.Core.Types.Action
instance GHC.Classes.Eq Development.Shake.Command.PID
instance GHC.Show.Show Development.Shake.Command.PID


-- | Lower-level primitives to drive Shake, which are wrapped into the
--   <a>shake</a> function. Useful if you want to perform multiple Shake
--   runs in a row without reloading from the database. Sometimes used in
--   conjunction with <tt><a>shakeFiles</a>="/dev/null"</tt>. Using these
--   functions you can approximate the <a>shake</a> experience with:
--   
--   <pre>
--   shake opts rules = do
--       (_, after) &lt;- <a>shakeWithDatabase</a> opts rules $ \db -&gt; do
--           <a>shakeOneShotDatabase</a> db
--           <a>shakeRunDatabase</a> db []
--       <a>shakeRunAfter</a> opts after
--   </pre>
module Development.Shake.Database

-- | The type of an open Shake database. Created with
--   <a>shakeOpenDatabase</a> or <a>shakeWithDatabase</a>. Used with
--   <a>shakeRunDatabase</a>. You may not execute simultaneous calls using
--   <a>ShakeDatabase</a> on separate threads (it will raise an error).
data ShakeDatabase

-- | Given some options and rules, return a pair. The first component opens
--   the database, the second cleans it up. The creation <i>does not</i>
--   need to be run masked, because the cleanup is able to run at any
--   point. Most users should prefer <a>shakeWithDatabase</a> which handles
--   exceptions duration creation properly.
shakeOpenDatabase :: ShakeOptions -> Rules () -> IO (IO ShakeDatabase, IO ())

-- | Given some options and rules, create a <a>ShakeDatabase</a> that can
--   be used to run executions.
shakeWithDatabase :: ShakeOptions -> Rules () -> (ShakeDatabase -> IO a) -> IO a

-- | Declare that a just-openned database will be used to call
--   <a>shakeRunDatabase</a> at most once. If so, an optimisation can be
--   applied to retain less memory.
shakeOneShotDatabase :: ShakeDatabase -> IO ()

-- | Given an open <a>ShakeDatabase</a>, run both whatever actions were
--   added to the <a>Rules</a>, plus the list of <a>Action</a> given here.
--   Returns the results from the explicitly passed actions along with a
--   list of actions to run after the database was closed, as added with
--   <a>runAfter</a> and <a>removeFilesAfter</a>.
shakeRunDatabase :: ShakeDatabase -> [Action a] -> IO ([a], [IO ()])

-- | Given a <a>ShakeDatabase</a>, what files did the execution ensure were
--   up-to-date in the previous call to <a>shakeRunDatabase</a>.
--   Corresponds to the list of files written out to <a>shakeLiveFiles</a>.
shakeLiveFilesDatabase :: ShakeDatabase -> IO [FilePath]

-- | Given a <a>ShakeDatabase</a>, generate profile information to the
--   given file about the latest run. See <a>shakeReport</a> for the types
--   of file that can be generated.
shakeProfileDatabase :: ShakeDatabase -> FilePath -> IO ()

-- | Given a <a>ShakeDatabase</a>, what files did the execution reach an
--   error on last time. Some special considerations when using this
--   function:
--   
--   <ul>
--   <li>The presence of an error does not mean the build will fail,
--   specifically if a previously required dependency was run and raised an
--   error, then the thing that previously required it will be run. If the
--   build system has changed in an untracked manner, the build may succeed
--   this time round.</li>
--   <li>If the previous run actually failed then <a>shakeRunDatabase</a>
--   will have thrown an exception. You probably want to catch that
--   exception so you can make the call to <a>shakeErrorsDatabase</a>.</li>
--   <li>You may see a single failure reported multiple times, with
--   increasingly large call stacks, showing the ways in which the error
--   lead to further errors throughout.</li>
--   <li>The <a>SomeException</a> values are highly likely to be of type
--   <a>ShakeException</a>.</li>
--   <li>If you want as many errors as possible in one run set
--   <tt><a>shakeStaunch</a>=True</tt>.</li>
--   </ul>
shakeErrorsDatabase :: ShakeDatabase -> IO [(String, SomeException)]

-- | Run a set of IO actions, treated as "after" actions, typically
--   returned from <a>shakeRunDatabase</a>. The actions will be run with
--   diagnostics etc as specified in the <a>ShakeOptions</a>.
shakeRunAfter :: ShakeOptions -> [IO ()] -> IO ()


-- | This module is used for defining Shake build systems. As a simple
--   example of a Shake build system, let us build the file
--   <tt>result.tar</tt> from the files listed by <tt>result.txt</tt>:
--   
--   <pre>
--   import <a>Development.Shake</a>
--   import <a>Development.Shake.FilePath</a>
--   
--   main = <a>shakeArgs</a> <a>shakeOptions</a> $ do
--       <a>want</a> ["result.tar"]
--       "*.tar" <a>%&gt;</a> \out -&gt; do
--           contents &lt;- <a>readFileLines</a> $ out <a>-&lt;.&gt;</a> "txt"
--           <a>need</a> contents
--           <a>cmd</a> "tar -cf" [out] contents
--   </pre>
--   
--   We start by importing the modules defining both Shake and routines for
--   manipulating <a>FilePath</a> values. We define <tt>main</tt> to call
--   <a>shake</a> with the default <a>shakeOptions</a>. As the second
--   argument to <a>shake</a>, we provide a set of rules. There are two
--   common forms of rules, <a>want</a> to specify target files, and
--   <a>%&gt;</a> to define a rule which builds a <a>FilePattern</a>. We
--   use <a>want</a> to require that after the build completes the file
--   <tt>result.tar</tt> should be ready.
--   
--   The <tt>*.tar</tt> rule describes how to build files with the
--   extension <tt>.tar</tt>, including <tt>result.tar</tt>. We
--   <a>readFileLines</a> on <tt>result.txt</tt>, after changing the
--   <tt>.tar</tt> extension to <tt>.txt</tt>. We read each line into the
--   variable <tt>contents</tt> -- being a list of the files that should go
--   into <tt>result.tar</tt>. Next, we depend (<a>need</a>) all the files
--   in <tt>contents</tt>. If any of these files change, the rule will be
--   repeated. Finally we call the <tt>tar</tt> program. If either
--   <tt>result.txt</tt> changes, or any of the files listed by
--   <tt>result.txt</tt> change, then <tt>result.tar</tt> will be rebuilt.
--   
--   To find out more:
--   
--   <ul>
--   <li>The user manual contains a longer example and background
--   information on how to use Shake
--   <a>https://www.shakebuild.com/manual</a>.</li>
--   <li>The home page has links to additional information
--   <a>https://www.shakebuild.com/</a>, including a mailing list.</li>
--   <li>The theory behind Shake is described in an ICFP 2012 paper,
--   <a>Shake Before Building -- Replacing Make with Haskell</a>. The
--   <a>associated talk</a> forms a short overview of Shake.</li>
--   </ul>
module Development.Shake

-- | Main entry point for running Shake build systems. For an example see
--   the top of the module <a>Development.Shake</a>. Use
--   <a>ShakeOptions</a> to specify how the system runs, and <a>Rules</a>
--   to specify what to build. The function will throw an exception if the
--   build fails.
--   
--   To use command line flags to modify <a>ShakeOptions</a> see
--   <a>shakeArgs</a>.
shake :: ShakeOptions -> Rules () -> IO ()

-- | The default set of <a>ShakeOptions</a>.
shakeOptions :: ShakeOptions

-- | Define a set of rules. Rules can be created with calls to functions
--   such as <a>%&gt;</a> or <a>action</a>. Rules are combined with either
--   the <a>Monoid</a> instance, or (more commonly) the <a>Monad</a>
--   instance and <tt>do</tt> notation. To define your own custom types of
--   rule, see <a>Development.Shake.Rule</a>.
data Rules a

-- | Run an action, usually used for specifying top-level requirements.
--   
--   <pre>
--   main = <a>shake</a> <a>shakeOptions</a> $ do
--      <a>action</a> $ do
--          b &lt;- <a>doesFileExist</a> "file.src"
--          when b $ <a>need</a> ["file.out"]
--   </pre>
--   
--   This <a>action</a> builds <tt>file.out</tt>, but only if
--   <tt>file.src</tt> exists. The <a>action</a> will be run in every build
--   execution (unless <a>withoutActions</a> is used), so only cheap
--   operations should be performed. On the flip side, consulting system
--   information (e.g. environment variables) can be done directly as the
--   information will not be cached. All calls to <a>action</a> may be run
--   in parallel, in any order.
--   
--   For the standard requirement of only <a>need</a>ing a fixed list of
--   files in the <a>action</a>, see <a>want</a>.
action :: Partial => Action a -> Rules ()

-- | Remove all actions specified in a set of rules, usually used for
--   implementing command line specification of what to build.
withoutActions :: Rules a -> Rules a

-- | Change the matching behaviour of rules so rules do not have to be
--   disjoint, but are instead matched in order. Only recommended for small
--   blocks containing a handful of rules.
--   
--   <pre>
--   <a>alternatives</a> $ do
--       "hello.*" %&gt; \out -&gt; <tt>writeFile'</tt> out "hello.*"
--       "*.txt" %&gt; \out -&gt; <tt>writeFile'</tt> out "*.txt"
--   </pre>
--   
--   In this example <tt>hello.txt</tt> will match the first rule, instead
--   of raising an error about ambiguity. Inside <a>alternatives</a> the
--   <a>priority</a> of each rule is not used to determine which rule
--   matches, but the resulting match uses that priority compared to the
--   rules outside the <a>alternatives</a> block.
alternatives :: Rules a -> Rules a

-- | Change the priority of a given set of rules, where higher values take
--   precedence. All matching rules at a given priority must be disjoint,
--   or an error is raised. All builtin Shake rules have priority between 0
--   and 1. Excessive use of <a>priority</a> is discouraged. As an example:
--   
--   <pre>
--   <a>priority</a> 4 $ "hello.*" %&gt; \out -&gt; <tt>writeFile'</tt> out "hello.*"
--   <a>priority</a> 8 $ "*.txt" %&gt; \out -&gt; <tt>writeFile'</tt> out "*.txt"
--   </pre>
--   
--   In this example <tt>hello.txt</tt> will match the second rule, instead
--   of raising an error about ambiguity.
--   
--   The <a>priority</a> function obeys the invariants:
--   
--   <pre>
--   <a>priority</a> p1 (<a>priority</a> p2 r1) === <a>priority</a> p1 r1
--   <a>priority</a> p1 (r1 &gt;&gt; r2) === <a>priority</a> p1 r1 &gt;&gt; <a>priority</a> p1 r2
--   </pre>
priority :: Double -> Rules a -> Rules a

-- | Indicate that the nested rules have a given version. If you change the
--   semantics of the rule then updating (or adding) a version will cause
--   the rule to rebuild in some circumstances.
--   
--   <pre>
--   <a>versioned</a> 1 $ "hello.*" %&gt; \out -&gt;
--       <tt>writeFile'</tt> out "Writes v1 now" -- previously wrote out v0
--   </pre>
--   
--   You should only use <a>versioned</a> to track changes in the build
--   source, for standard runtime dependencies you should use other
--   mechanisms, e.g. <a>addOracle</a>.
versioned :: Int -> Rules a -> Rules a

-- | The <a>Action</a> monad, use <a>liftIO</a> to raise <a>IO</a> actions
--   into it, and <a>need</a> to execute files. Action values are used by
--   <tt>addUserRule</tt> and <tt>action</tt>. The <a>Action</a> monad
--   tracks the dependencies of a rule. To raise an exception call
--   <a>error</a>, <a>fail</a> or <tt><a>liftIO</a> . <a>throwIO</a></tt>.
--   
--   The <a>Action</a> type is both a <a>Monad</a> and <a>Applicative</a>.
--   Anything that is depended upon applicatively will have its
--   dependencies run in parallel. For example <tt><tt>need</tt> ["a"]
--   *&gt; 'need ["b"]</tt> is equivalent to <tt><tt>need</tt> ["a",
--   "b"]</tt>.
data Action a

-- | Write an action to the trace list, along with the start/end time of
--   running the IO action. The <a>cmd</a> and <a>command</a> functions
--   automatically call <a>traced</a> with the name of the executable. The
--   trace list is used for profile reports (see <a>shakeReport</a>).
--   
--   By default <a>traced</a> prints some useful extra context about what
--   Shake is building, e.g.:
--   
--   <pre>
--   # traced message (for myobject.o)
--   </pre>
--   
--   To suppress the output of <a>traced</a> (for example you want more
--   control over the message using <a>putInfo</a>), use the <a>quietly</a>
--   combinator.
--   
--   It is recommended that the string passed to <a>traced</a> is short and
--   that only a small number of unique strings are used (makes profiling
--   work better). The string does not need to make sense on its own, only
--   in conjunction with the target it is building.
traced :: String -> IO a -> Action a
liftIO :: MonadIO m => IO a -> m a

-- | If an exception is raised by the <a>Action</a>, perform some <a>IO</a>
--   then reraise the exception. This function is implemented using
--   <a>actionBracket</a>.
actionOnException :: Action a -> IO b -> Action a

-- | After an <a>Action</a>, perform some <a>IO</a>, even if there is an
--   exception. This function is implemented using <a>actionBracket</a>.
actionFinally :: Action a -> IO b -> Action a

-- | Like <a>bracket</a>, but where the inner operation is of type
--   <a>Action</a>. Usually used as <tt><a>actionBracket</a> alloc free
--   use</tt>.
--   
--   The <tt>free</tt> action will be run masked. The cost of
--   <a>actionBracket</a> is _O(n log n)_ in the number of simultaneous
--   <a>actionBracket</a> calls active in the program.
actionBracket :: IO a -> (a -> IO b) -> (a -> Action c) -> Action c

-- | If a syncronous exception is raised by the <a>Action</a>, perform some
--   handler. Note that there is no guarantee that the handler will run on
--   shutdown (use <a>actionFinally</a> for that), and that
--   <a>actionCatch</a> <i>cannot</i> catch exceptions thrown by
--   dependencies, e.g. raised by <tt>need</tt> (to do so would allow
--   untracked dependencies on failure conditions).
actionCatch :: Exception e => Action a -> (e -> Action a) -> Action a

-- | Retry an <a>Action</a> if it throws an exception, at most <i>n</i>
--   times (where <i>n</i> must be positive). If you need to call this
--   function, you should probably try and fix the underlying cause (but
--   you also probably know that).
actionRetry :: Int -> Action a -> Action a

-- | Specify an action to be run after the database has been closed, if
--   building completes successfully.
runAfter :: IO () -> Action ()

-- | Error representing all expected exceptions thrown by Shake. Problems
--   when executing rules will be raising using this exception type.
data ShakeException
ShakeException :: String -> [String] -> SomeException -> ShakeException

-- | The target that was being built when the exception occurred.
[shakeExceptionTarget] :: ShakeException -> String

-- | A description of the call stack, one entry per line.
[shakeExceptionStack] :: ShakeException -> [String]

-- | The underlying exception that was raised.
[shakeExceptionInner] :: ShakeException -> SomeException

-- | Options to control the execution of Shake, usually specified by
--   overriding fields in <a>shakeOptions</a>:
--   
--   <pre>
--   <a>shakeOptions</a>{<a>shakeThreads</a>=4, <a>shakeReport</a>=["report.html"]}
--   </pre>
--   
--   The <a>Data</a> instance for this type reports the
--   <a>shakeProgress</a> and <a>shakeOutput</a> fields as having the
--   abstract type <a>Hidden</a>, because <a>Data</a> cannot be defined for
--   functions or <a>TypeRep</a>s.
data ShakeOptions
ShakeOptions :: FilePath -> Int -> String -> Verbosity -> Bool -> [FilePath] -> Maybe Lint -> [FilePath] -> [FilePattern] -> [FilePattern] -> [CmdOption] -> Maybe Seconds -> [(Rebuild, FilePattern)] -> [(String, String)] -> Bool -> Bool -> Bool -> Bool -> Change -> Bool -> [FilePath] -> Bool -> Bool -> Maybe FilePath -> [String] -> Bool -> Bool -> Bool -> (IO Progress -> IO ()) -> (Verbosity -> String -> IO ()) -> (String -> String -> Bool -> IO ()) -> HashMap TypeRep Dynamic -> ShakeOptions

-- | Defaults to <tt>.shake</tt>. The directory used for storing Shake
--   metadata files. All metadata files will be named
--   <tt><a>shakeFiles</a>/.shake.<i>file-name</i></tt>, for some
--   <tt><i>file-name</i></tt>. If the <a>shakeFiles</a> directory does not
--   exist it will be created. If set to <tt>"/dev/null"</tt> then no
--   shakeFiles are read or written (even on Windows).
[shakeFiles] :: ShakeOptions -> FilePath

-- | Defaults to <tt>1</tt>. Maximum number of rules to run in parallel,
--   similar to <tt>make --jobs=<i>N</i></tt>. For many build systems, a
--   number equal to or slightly less than the number of physical
--   processors works well. Use <tt>0</tt> to match the detected number of
--   processors (when <tt>0</tt>, <tt>getShakeOptions</tt> will return the
--   number of threads used).
[shakeThreads] :: ShakeOptions -> Int

-- | Defaults to <tt>"1"</tt>. The version number of your build rules.
--   Change the version number to force a complete rebuild, such as when
--   making significant changes to the rules that require a wipe. The
--   version number should be set in the source code, and not passed on the
--   command line.
[shakeVersion] :: ShakeOptions -> String

-- | Defaults to <a>Info</a>. What level of messages should be printed out.
[shakeVerbosity] :: ShakeOptions -> Verbosity

-- | Defaults to <a>False</a>. Operate in staunch mode, where building
--   continues even after errors, similar to <tt>make --keep-going</tt>.
[shakeStaunch] :: ShakeOptions -> Bool

-- | Defaults to <tt>[]</tt>. Write a profiling report to a file, showing
--   which rules rebuilt, why, and how much time they took. Useful for
--   improving the speed of your build systems. If the file extension is
--   <tt>.json</tt> it will write JSON data; if <tt>.js</tt> it will write
--   Javascript; if <tt>.trace</tt> it will write trace events (load into
--   <tt>about://tracing</tt> in Chrome); otherwise it will write HTML.
[shakeReport] :: ShakeOptions -> [FilePath]

-- | Defaults to <a>Nothing</a>. Perform sanity checks during building, see
--   <a>Lint</a> for details.
[shakeLint] :: ShakeOptions -> Maybe Lint

-- | Directories in which the files will be tracked by the linter.
[shakeLintInside] :: ShakeOptions -> [FilePath]

-- | File patterns which are ignored from linter tracking, a bit like
--   calling <a>trackAllow</a> in every rule.
[shakeLintIgnore] :: ShakeOptions -> [FilePattern]

-- | File patterns whose modification causes an error. Raises an error even
--   if <a>shakeLint</a> is <a>Nothing</a>.
[shakeLintWatch] :: ShakeOptions -> [FilePattern]

-- | Defaults to <tt>[]</tt>. Additional options to be passed to all
--   command invocations.
[shakeCommandOptions] :: ShakeOptions -> [CmdOption]

-- | Defaults to <tt><a>Just</a> 10</tt>. How often to flush Shake metadata
--   files in seconds, or <a>Nothing</a> to never flush explicitly. It is
--   possible that on abnormal termination (not Haskell exceptions) any
--   rules that completed in the last <a>shakeFlush</a> seconds will be
--   lost.
[shakeFlush] :: ShakeOptions -> Maybe Seconds

-- | What to rebuild
[shakeRebuild] :: ShakeOptions -> [(Rebuild, FilePattern)]

-- | Defaults to <tt>[]</tt>. A list of substrings that should be
--   abbreviated in status messages, and their corresponding abbreviation.
--   Commonly used to replace the long paths (e.g.
--   <tt>.make/i586-linux-gcc/output</tt>) with an abbreviation (e.g.
--   <tt>$OUT</tt>).
[shakeAbbreviations] :: ShakeOptions -> [(String, String)]

-- | Defaults to <a>False</a>. Write a message to
--   <tt><a>shakeFiles</a>/.shake.storage.log</tt> whenever a storage event
--   happens which may impact on the current stored progress. Examples
--   include database version number changes, database compaction or
--   corrupt files.
[shakeStorageLog] :: ShakeOptions -> Bool

-- | Defaults to <a>True</a>. Change <tt>stdout</tt> and <tt>stderr</tt> to
--   line buffering while running Shake.
[shakeLineBuffering] :: ShakeOptions -> Bool

-- | Defaults to <a>False</a>. Print timing information for each stage at
--   the end.
[shakeTimings] :: ShakeOptions -> Bool

-- | Default to <a>True</a>. Should you run command line actions, set to
--   <a>False</a> to skip actions whose output streams and exit code are
--   not used. Useful for profiling the non-command portion of the build
--   system.
[shakeRunCommands] :: ShakeOptions -> Bool

-- | Default to <a>ChangeModtime</a>. How to check if a file has changed,
--   see <a>Change</a> for details.
[shakeChange] :: ShakeOptions -> Change

-- | Default to <a>True</a>. After running a rule to create a file, is it
--   an error if the file does not exist. Provided for compatibility with
--   <tt>make</tt> and <tt>ninja</tt> (which have ugly file creation
--   semantics).
[shakeCreationCheck] :: ShakeOptions -> Bool

-- | Default to <tt>[]</tt>. After the build system completes, write a list
--   of all files which were <i>live</i> in that run, i.e. those which
--   Shake checked were valid or rebuilt. Produces best answers if nothing
--   rebuilds.
[shakeLiveFiles] :: ShakeOptions -> [FilePath]

-- | Defaults to <a>False</a>. Ignore any differences in
--   <a>shakeVersion</a>.
[shakeVersionIgnore] :: ShakeOptions -> Bool

-- | Defaults to <a>False</a>. Whether to colorize the output.
[shakeColor] :: ShakeOptions -> Bool

-- | Defaults to <a>Nothing</a>. Whether to use and store outputs in a
--   shared directory.
[shakeShare] :: ShakeOptions -> Maybe FilePath

-- | Defaults to <tt>[]</tt>. Cloud servers to talk to forming a shared
--   cache.
[shakeCloud] :: ShakeOptions -> [String]

-- | Defaults to <tt>False</tt>. Use symlinks for <a>shakeShare</a> if they
--   are available. If this setting is <tt>True</tt> (even if symlinks are
--   not available) then files will be made read-only to avoid
--   inadvertantly poisoning the shared cache. Note the links are actually
--   hard links, not symlinks.
[shakeSymlink] :: ShakeOptions -> Bool

-- | Defaults to <tt>False</tt>. Is depending on a directory an error
--   (default), or it is permitted with undefined results. Provided for
--   compatibility with <tt>ninja</tt>.
[shakeNeedDirectory] :: ShakeOptions -> Bool

-- | Whether to allow calling addBuiltinRule for the same key more than
--   once
[shakeAllowRedefineRules] :: ShakeOptions -> Bool

-- | Defaults to no action. A function called when the build starts,
--   allowing progress to be reported. The function is called on a separate
--   thread, and that thread is killed when the build completes. For
--   applications that want to display progress messages,
--   <tt>progressSimple</tt> is often sufficient, but more advanced users
--   should look at the <a>Progress</a> data type.
[shakeProgress] :: ShakeOptions -> IO Progress -> IO ()

-- | Defaults to writing using <a>putStrLn</a>. A function called to output
--   messages from Shake, along with the <a>Verbosity</a> at which that
--   message should be printed. This function will be called atomically
--   from all other <a>shakeOutput</a> functions. The <a>Verbosity</a> will
--   always be greater than or higher than <a>shakeVerbosity</a>.
[shakeOutput] :: ShakeOptions -> Verbosity -> String -> IO ()

-- | Defaults to doing nothing. Called for each call of <a>traced</a>, with
--   the key, the command and <a>True</a> for starting, <a>False</a> for
--   stopping.
[shakeTrace] :: ShakeOptions -> String -> String -> Bool -> IO ()

-- | This a map which can be used to store arbitrary extra information that
--   a user may need when writing rules. The key of each entry must be the
--   <a>dynTypeRep</a> of the value. Insert values using
--   <tt>addShakeExtra</tt> and retrieve them using <tt>getShakeExtra</tt>.
--   The correct way to use this field is to define a hidden newtype for
--   the key, so that conflicts cannot occur.
[shakeExtra] :: ShakeOptions -> HashMap TypeRep Dynamic

-- | The current assumptions made by the build system, used by
--   <a>shakeRebuild</a>. These options allow the end user to specify that
--   any rules run are either to be treated as clean, or as dirty,
--   regardless of what the build system thinks.
--   
--   These assumptions only operate on files reached by the current
--   <a>action</a> commands. Any other files in the database are left
--   unchanged.
data Rebuild

-- | Assume these files are dirty and require rebuilding. for benchmarking
--   rebuild speed and for rebuilding if untracked dependencies have
--   changed. This flag is safe, but may cause more rebuilding than
--   necessary.
RebuildNow :: Rebuild

-- | Useful to reset the rebuild status to how it was before, equivalent to
--   passing no <a>Rebuild</a> flags.
RebuildNormal :: Rebuild

-- | <i>This assumption is unsafe, and may lead to incorrect build results
--   in this run</i>. Assume these files are clean in this run, but test
--   them normally in future runs.
RebuildLater :: Rebuild

-- | Which lint checks to perform, used by <a>shakeLint</a>.
data Lint

-- | The most basic form of linting. Checks that the current directory does
--   not change and that results do not change after they are first
--   written. Any calls to <tt>needed</tt> will assert that they do not
--   cause a rule to be rebuilt.
LintBasic :: Lint

-- | Track which files are accessed by command line programs using
--   <a>fsatrace</a>.
LintFSATrace :: Lint

-- | How should you determine if a file has changed, used by
--   <a>shakeChange</a>. The most common values are <a>ChangeModtime</a>
--   (the default, very fast, <tt>touch</tt> causes files to rebuild) and
--   <a>ChangeModtimeAndDigestInput</a> (slightly slower, <tt>touch</tt>
--   and switching <tt>git</tt> branches does not cause input files to
--   rebuild).
data Change

-- | Compare equality of modification timestamps, a file has changed if its
--   last modified time changes. A <tt>touch</tt> will force a rebuild.
--   This mode is fast and usually sufficiently accurate, so is the
--   default.
ChangeModtime :: Change

-- | Compare equality of file contents digests, a file has changed if its
--   digest changes. A <tt>touch</tt> will not force a rebuild. Use this
--   mode if modification times on your file system are unreliable.
ChangeDigest :: Change

-- | A file is rebuilt if both its modification time and digest have
--   changed. For efficiency reasons, the modification time is checked
--   first, and if that has changed, the digest is checked.
ChangeModtimeAndDigest :: Change

-- | Use <a>ChangeModtimeAndDigest</a> for input/source files and
--   <a>ChangeModtime</a> for output files. An input file is one which is a
--   dependency but is not built by Shake as it has no matching rule and
--   already exists on the file system.
ChangeModtimeAndDigestInput :: Change

-- | A file is rebuilt if either its modification time or its digest has
--   changed. A <tt>touch</tt> will force a rebuild, but even if a files
--   modification time is reset afterwards, changes will also cause a
--   rebuild.
ChangeModtimeOrDigest :: Change

-- | Get the initial <a>ShakeOptions</a>, these will not change during the
--   build process.
getShakeOptions :: Action ShakeOptions

-- | Get the <a>ShakeOptions</a> that were used.
getShakeOptionsRules :: Rules ShakeOptions

-- | Get a checksum of a list of files, suitable for using as
--   <a>shakeVersion</a>. This will trigger a rebuild when the Shake rules
--   defined in any of the files are changed. For example:
--   
--   <pre>
--   main = do
--       ver &lt;- <a>getHashedShakeVersion</a> ["Shakefile.hs"]
--       <tt>shakeArgs</tt> <a>shakeOptions</a>{<a>shakeVersion</a> = ver} ...
--   </pre>
--   
--   To automatically detect the name of the current file, turn on the
--   <tt>TemplateHaskell</tt> extension and write <tt>$(LitE . StringL .
--   loc_filename &lt;$&gt; location)</tt>.
--   
--   This feature can be turned off during development by passing the flag
--   <tt>--no-rule-version</tt> or setting <a>shakeVersionIgnore</a> to
--   <a>True</a>.
getHashedShakeVersion :: [FilePath] -> IO String

-- | Get an item from <a>shakeExtra</a>, using the requested type as the
--   key. Fails if the value found at this key does not match the requested
--   type.
getShakeExtra :: Typeable a => Action (Maybe a)

-- | A version of <a>getShakeExtra</a> in <a>Rules</a>.
getShakeExtraRules :: Typeable a => Rules (Maybe a)

-- | Add a properly structued value to <a>shakeExtra</a> which can be
--   retrieved with <a>getShakeExtra</a>.
addShakeExtra :: Typeable a => a -> HashMap TypeRep Dynamic -> HashMap TypeRep Dynamic

-- | Run a build system using command line arguments for configuration. The
--   available flags are those from <a>shakeOptDescrs</a>, along with a few
--   additional <tt>make</tt> compatible flags that are not represented in
--   <a>ShakeOptions</a>, such as <tt>--print-directory</tt>. If there are
--   no file arguments then the <a>Rules</a> are used directly, otherwise
--   the file arguments are <a>want</a>ed (after calling
--   <a>withoutActions</a>). As an example:
--   
--   <pre>
--   main = <a>shakeArgs</a> <a>shakeOptions</a>{<a>shakeFiles</a> = "_make", <a>shakeProgress</a> = <a>progressSimple</a>} $ do
--       <a>phony</a> "clean" $ <a>removeFilesAfter</a> "_make" ["//*"]
--       <a>want</a> ["_make/neil.txt","_make/emily.txt"]
--       "_make/*.txt" <a>%&gt;</a> \out -&gt;
--           ... build action here ...
--   </pre>
--   
--   This build system will default to building <tt>neil.txt</tt> and
--   <tt>emily.txt</tt>, while showing progress messages, and putting the
--   Shake files in locations such as <tt>_make/.database</tt>. Some
--   example command line flags:
--   
--   <ul>
--   <li><tt>main --no-progress</tt> will turn off progress messages.</li>
--   <li><tt>main -j6</tt> will build on 6 threads.</li>
--   <li><tt>main --help</tt> will display a list of supported flags.</li>
--   <li><tt>main clean</tt> will not build anything, but will remove the
--   <tt>_make</tt> directory, including the any <a>shakeFiles</a>.</li>
--   <li><tt>main _make/henry.txt</tt> will not build <tt>neil.txt</tt> or
--   <tt>emily.txt</tt>, but will instead build <tt>henry.txt</tt>.</li>
--   </ul>
shakeArgs :: ShakeOptions -> Rules () -> IO ()

-- | A version of <a>shakeArgs</a> with more flexible handling of command
--   line arguments. The caller of <a>shakeArgsWith</a> can add additional
--   flags (the second argument) and chose how to convert the
--   flags/arguments into rules (the third argument). Given:
--   
--   <pre>
--   <a>shakeArgsWith</a> opts flags (\flagValues argValues -&gt; result)
--   </pre>
--   
--   <ul>
--   <li><tt>opts</tt> is the initial <a>ShakeOptions</a> value, which may
--   have some fields overridden by command line flags. This argument is
--   usually <a>shakeOptions</a>, perhaps with a few fields
--   overridden.</li>
--   <li><tt>flags</tt> is a list of flag descriptions, which either
--   produce a <a>String</a> containing an error message (typically for
--   flags with invalid arguments, .e.g. <tt><a>Left</a> "could not parse
--   as int"</tt>), or a value that is passed as <tt>flagValues</tt>. If
--   you have no custom flags, pass <tt>[]</tt>.</li>
--   <li><tt>flagValues</tt> is a list of custom flags that the user
--   supplied. If <tt>flags == []</tt> then this list will be
--   <tt>[]</tt>.</li>
--   <li><tt>argValues</tt> is a list of non-flag arguments, which are
--   often treated as files and passed to <a>want</a>. If arguments are
--   specified then typically the <a>want</a> calls from the rules are
--   discarded using <a>withoutActions</a>.</li>
--   <li><tt>result</tt> should produce a <a>Nothing</a> to indicate that
--   no building needs to take place, or a <a>Just</a> providing the rules
--   that should be used.</li>
--   </ul>
--   
--   As an example of a build system that can use either <tt>gcc</tt> or
--   <tt>distcc</tt> for compiling:
--   
--   <pre>
--   import System.Console.GetOpt
--   
--   data Flags = DistCC deriving Eq
--   flags = [Option "" ["distcc"] (NoArg $ Right DistCC) "Run distributed."]
--   
--   main = <a>shakeArgsWith</a> <a>shakeOptions</a> flags $ \flags targets -&gt; pure $ Just $ do
--       let compiler = if DistCC `elem` flags then "distcc" else "gcc"
--       let rules = do
--           "*.o" <a>%&gt;</a> \out -&gt; do
--               <a>need</a> ...
--               <tt>cmd</tt> compiler ...
--           <a>want</a> ["target.exe"]
--           ...
--       if null targets then rules else <a>want</a> targets &gt;&gt; <a>withoutActions</a> rules
--   </pre>
--   
--   Now you can pass <tt>--distcc</tt> to use the <tt>distcc</tt>
--   compiler.
shakeArgsWith :: ShakeOptions -> [OptDescr (Either String a)] -> ([a] -> [String] -> IO (Maybe (Rules ()))) -> IO ()

-- | Like <a>shakeArgsWith</a>, but also lets you manipulate the
--   <a>ShakeOptions</a>.
shakeArgsOptionsWith :: ShakeOptions -> [OptDescr (Either String a)] -> (ShakeOptions -> [a] -> [String] -> IO (Maybe (ShakeOptions, Rules ()))) -> IO ()

-- | A list of command line options that can be used to modify
--   <a>ShakeOptions</a>. Each option returns either an error message
--   (invalid argument to the flag) or a function that changes some fields
--   in <a>ShakeOptions</a>. The command line flags are <tt>make</tt>
--   compatible where possbile, but additional flags have been added for
--   the extra options Shake supports.
shakeOptDescrs :: [OptDescr (Either String (ShakeOptions -> ShakeOptions))]

-- | Adds some extra information at the end of <tt>--help</tt>.
addHelpSuffix :: String -> Rules ()

-- | Get all targets registered in the given rules. The names in
--   <a>phony</a> and <a>~&gt;</a> as well as the file patterns in
--   <a>%&gt;</a>, <a>|%&gt;</a> and <a>&amp;%&gt;</a> are registered as
--   targets, plus any explicit calls to <a>addTarget</a>. Returns the
--   command, paired with the documentation (if any).
getTargets :: ShakeOptions -> Rules () -> IO [(String, Maybe String)]

-- | Register a target, as available when passing <tt>--help</tt> or
--   through <a>getTargets</a>. Called automatically by rules such as
--   <a>phony</a> and <a>%&gt;</a> - to avoid that use
--   <a>withoutTargets</a>. To add documentation to a target use
--   <a>withTargetDocs</a>.
addTarget :: String -> Rules ()

-- | For all <a>addTarget</a> targets within the <a>Rules</a> provide the
--   specified documentation, if they don't already have documentation.
withTargetDocs :: String -> Rules () -> Rules ()

-- | Remove all targets specified in a set of rules, typically because they
--   are internal details. Overrides <a>addTarget</a>.
withoutTargets :: Rules a -> Rules a

-- | Information about the current state of the build, obtained by either
--   passing a callback function to <a>shakeProgress</a> (asynchronous
--   output) or <a>getProgress</a> (synchronous output). Typically a build
--   system will pass <tt>progressDisplay</tt> to <a>shakeProgress</a>,
--   which will poll this value and produce status messages.
data Progress
Progress :: !Maybe String -> {-# UNPACK #-} !Int -> {-# UNPACK #-} !Int -> {-# UNPACK #-} !Int -> {-# UNPACK #-} !Int -> {-# UNPACK #-} !Double -> {-# UNPACK #-} !Double -> {-# UNPACK #-} !Double -> {-# UNPACK #-} !(Double, Int) -> Progress

-- | Starts out <a>Nothing</a>, becomes <a>Just</a> a target name if a rule
--   fails.
[isFailure] :: Progress -> !Maybe String

-- | Number of rules which were required, but were already in a valid
--   state.
[countSkipped] :: Progress -> {-# UNPACK #-} !Int

-- | Number of rules which were have been built in this run.
[countBuilt] :: Progress -> {-# UNPACK #-} !Int

-- | Number of rules which have been built previously, but are not yet
--   known to be required.
[countUnknown] :: Progress -> {-# UNPACK #-} !Int

-- | Number of rules which are currently required (ignoring dependencies
--   that do not change), but not built.
[countTodo] :: Progress -> {-# UNPACK #-} !Int

-- | Time spent building <a>countSkipped</a> rules in previous runs.
[timeSkipped] :: Progress -> {-# UNPACK #-} !Double

-- | Time spent building <a>countBuilt</a> rules.
[timeBuilt] :: Progress -> {-# UNPACK #-} !Double

-- | Time spent building <a>countUnknown</a> rules in previous runs.
[timeUnknown] :: Progress -> {-# UNPACK #-} !Double

-- | Time spent building <a>countTodo</a> rules in previous runs, plus the
--   number which have no known time (have never been built before).
[timeTodo] :: Progress -> {-# UNPACK #-} !(Double, Int)

-- | A simple method for displaying progress messages, suitable for using
--   as <a>shakeProgress</a>. This function writes the current progress to
--   the titlebar every five seconds using <a>progressTitlebar</a>, and
--   calls any <tt>shake-progress</tt> program on the <tt>$PATH</tt> using
--   <a>progressProgram</a>.
progressSimple :: IO Progress -> IO ()

-- | Given a sampling interval (in seconds) and a way to display the status
--   message, produce a function suitable for using as
--   <a>shakeProgress</a>. This function polls the progress information
--   every <i>n</i> seconds, produces a status message and displays it
--   using the display function.
--   
--   Typical status messages will take the form of <tt>1m25s (15%)</tt>,
--   indicating that the build is predicted to complete in 1 minute 25
--   seconds (85 seconds total), and 15% of the necessary build time has
--   elapsed. This function uses past observations to predict future
--   behaviour, and as such, is only guessing. The time is likely to go up
--   as well as down, and will be less accurate from a clean build (as the
--   system has fewer past observations).
--   
--   The current implementation is to predict the time remaining (based on
--   <a>timeTodo</a>) and the work already done (<a>timeBuilt</a>). The
--   percentage is then calculated as <tt>remaining / (done +
--   remaining)</tt>, while time left is calculated by scaling
--   <tt>remaining</tt> by the observed work rate in this build, roughly
--   <tt>done / time_elapsed</tt>.
progressDisplay :: Double -> (String -> IO ()) -> IO Progress -> IO ()

-- | Set the title of the current console window to the given text. If the
--   environment variable <tt>$TERM</tt> is set to <tt>xterm</tt> this uses
--   xterm escape sequences. On Windows, if not detected as an xterm, this
--   function uses the <tt>SetConsoleTitle</tt> API.
progressTitlebar :: String -> IO ()

-- | Call the program <tt>shake-progress</tt> if it is on the
--   <tt>$PATH</tt>. The program is called with the following arguments:
--   
--   <ul>
--   <li><tt>--title=string</tt> - the string passed to
--   <tt>progressProgram</tt>.</li>
--   <li><tt>--state=Normal</tt>, or one of <tt>NoProgress</tt>,
--   <tt>Normal</tt>, or <tt>Error</tt> to indicate what state the progress
--   bar should be in.</li>
--   <li><tt>--value=25</tt> - the percent of the build that has completed,
--   if not in <tt>NoProgress</tt> state.</li>
--   </ul>
--   
--   The program will not be called consecutively with the same
--   <tt>--state</tt> and <tt>--value</tt> options.
--   
--   Windows 7 or higher users can get taskbar progress notifications by
--   placing the following program in their <tt>$PATH</tt>:
--   <a>https://github.com/ndmitchell/shake/releases</a>.
progressProgram :: IO (String -> IO ())

-- | Get the current <a>Progress</a> structure, as would be returned by
--   <a>shakeProgress</a>.
getProgress :: Action Progress

-- | The verbosity data type, used by <a>shakeVerbosity</a>.
data Verbosity

-- | Don't print any messages.
Silent :: Verbosity

-- | Only print error messages.
Error :: Verbosity

-- | Print errors and warnings.
Warn :: Verbosity

-- | Print errors, warnings and <tt># <i>command-name</i> (for
--   <i>file-name</i>)</tt> when running a <a>traced</a> command.
Info :: Verbosity

-- | Print errors, warnings, full command lines when running a
--   <a>command</a> or <a>cmd</a> command and status messages when starting
--   a rule.
Verbose :: Verbosity

-- | Print messages for virtually everything (mostly for debugging).
Diagnostic :: Verbosity

-- | Get the current verbosity level, originally set by
--   <a>shakeVerbosity</a>. If you want to output information to the
--   console, you are recommended to use <a>putVerbose</a> / <a>putInfo</a>
--   / <a>putError</a>, which ensures multiple messages are not
--   interleaved. The verbosity can be modified locally by
--   <a>withVerbosity</a>.
getVerbosity :: Action Verbosity

-- | Write an unimportant message to the output, only shown when
--   <a>shakeVerbosity</a> is higher than normal (<a>Verbose</a> or above).
--   The output will not be interleaved with any other Shake messages
--   (other than those generated by system commands).
putVerbose :: String -> Action ()

-- | Write a normal priority message to the output, only suppressed when
--   <a>shakeVerbosity</a> is <a>Error</a>, <a>Warn</a> or <a>Silent</a>.
--   The output will not be interleaved with any other Shake messages
--   (other than those generated by system commands).
putInfo :: String -> Action ()

-- | Write a semi important message to the output, only suppressed when
--   <a>shakeVerbosity</a> is <a>Error</a> or <a>Silent</a>. The output
--   will not be interleaved with any other Shake messages (other than
--   those generated by system commands).
putWarn :: String -> Action ()

-- | Write an important message to the output, only suppressed when
--   <a>shakeVerbosity</a> is <a>Silent</a>. The output will not be
--   interleaved with any other Shake messages (other than those generated
--   by system commands).
putError :: String -> Action ()

-- | Run an action with a particular verbosity level. Will not update the
--   <a>shakeVerbosity</a> returned by <a>getShakeOptions</a> and will not
--   have any impact on <a>Diagnostic</a> tracing.
withVerbosity :: Verbosity -> Action a -> Action a

-- | Run an action with <a>Error</a> verbosity, in particular messages
--   produced by <a>traced</a> (including from <a>cmd</a> or
--   <a>command</a>) will not be printed to the screen. Will not update the
--   <a>shakeVerbosity</a> returned by <a>getShakeOptions</a> and will not
--   turn off any <a>Diagnostic</a> tracing.
quietly :: Action a -> Action a

-- | Execute a system command. Before running <a>command</a> make sure you
--   <a>need</a> any files that are used by the command.
--   
--   This function takes a list of options (often just <tt>[]</tt>, see
--   <a>CmdOption</a> for the available options), the name of the
--   executable (either a full name, or a program on the <tt>$PATH</tt>)
--   and a list of arguments. The result is often <tt>()</tt>, but can be a
--   tuple containg any of <a>Stdout</a>, <a>Stderr</a> and <a>Exit</a>.
--   Some examples:
--   
--   <pre>
--   <a>command_</a> [] "gcc" ["-c","myfile.c"]                          -- compile a file, throwing an exception on failure
--   <a>Exit</a> c &lt;- <a>command</a> [] "gcc" ["-c",myfile]                     -- run a command, recording the exit code
--   (<a>Exit</a> c, <a>Stderr</a> err) &lt;- <a>command</a> [] "gcc" ["-c","myfile.c"]   -- run a command, recording the exit code and error output
--   <a>Stdout</a> out &lt;- <a>command</a> [] "gcc" ["-MM","myfile.c"]            -- run a command, recording the output
--   <a>command_</a> [<a>Cwd</a> "generated"] "gcc" ["-c",myfile]               -- run a command in a directory
--   </pre>
--   
--   Unless you retrieve the <a>ExitCode</a> using <a>Exit</a>, any
--   <a>ExitFailure</a> will throw an error, including the <a>Stderr</a> in
--   the exception message. If you capture the <a>Stdout</a> or
--   <a>Stderr</a>, that stream will not be echoed to the console, unless
--   you use the option <a>EchoStdout</a> or <a>EchoStderr</a>.
--   
--   If you use <a>command</a> inside a <tt>do</tt> block and do not use
--   the result, you may get a compile-time error about being unable to
--   deduce <a>CmdResult</a>. To avoid this error, use <a>command_</a>.
--   
--   By default the <tt>stderr</tt> stream will be captured for use in
--   error messages, and also echoed. To only echo pass
--   <tt><a>WithStderr</a> <a>False</a></tt>, which causes no streams to be
--   captured by Shake, and certain programs (e.g. <tt>gcc</tt>) to detect
--   they are running in a terminal.
command :: (Partial, CmdResult r) => [CmdOption] -> String -> [String] -> Action r

-- | A version of <a>command</a> where you do not require any results, used
--   to avoid errors about being unable to deduce <a>CmdResult</a>.
command_ :: Partial => [CmdOption] -> String -> [String] -> Action ()

-- | Build or execute a system command. Before using <a>cmd</a> to run a
--   command, make sure you <a>need</a> any files that are used by the
--   command.
--   
--   <ul>
--   <li><tt>String</tt> arguments are treated as a list of whitespace
--   separated arguments.</li>
--   <li><tt>[String]</tt> arguments are treated as a list of literal
--   arguments.</li>
--   <li><a>CmdOption</a> arguments are used as options.</li>
--   <li><a>CmdArgument</a> arguments, which can be built by <a>cmd</a>
--   itself, are spliced into the containing command.</li>
--   </ul>
--   
--   Typically only string literals should be passed as <tt>String</tt>
--   arguments. When using variables prefer <tt>[myvar]</tt> so that if
--   <tt>myvar</tt> contains spaces they are properly escaped.
--   
--   As some examples, here are some calls, and the resulting command
--   string:
--   
--   <pre>
--   <a>cmd_</a> "git log --pretty=" "oneline"           -- git log --pretty= oneline
--   <a>cmd_</a> "git log --pretty=" ["oneline"]         -- git log --pretty= oneline
--   <a>cmd_</a> "git log" ("--pretty=" ++ "oneline")    -- git log --pretty=oneline
--   <a>cmd_</a> "git log" ("--pretty=" ++ "one line")   -- git log --pretty=one line
--   <a>cmd_</a> "git log" ["--pretty=" ++ "one line"]   -- git log "--pretty=one line"
--   </pre>
--   
--   More examples, including return values, see this translation of the
--   examples given for the <a>command</a> function:
--   
--   <pre>
--   <a>cmd_</a> "gcc -c myfile.c"                                       -- compile a file, throwing an exception on failure
--   <a>Exit</a> c &lt;- <a>cmd</a> "gcc -c" [myfile]                              -- run a command, recording the exit code
--   (<a>Exit</a> c, <a>Stderr</a> err) &lt;- <a>cmd</a> "gcc -c myfile.c"                -- run a command, recording the exit code and error output
--   <a>Stdout</a> out &lt;- <a>cmd</a> "gcc -MM myfile.c"                         -- run a command, recording the output
--   <a>cmd</a> (<a>Cwd</a> "generated") "gcc -c" [myfile] :: <a>Action</a> ()         -- run a command in a directory
--   
--   let gccCommand = <a>cmd</a> "gcc -c" :: <a>CmdArgument</a>                 -- build a sub-command. <a>cmd</a> can return <a>CmdArgument</a> values as well as execute commands
--   cmd (<a>Cwd</a> "generated") gccCommand [myfile]                 -- splice that command into a greater command
--   </pre>
--   
--   If you use <a>cmd</a> inside a <tt>do</tt> block and do not use the
--   result, you may get a compile-time error about being unable to deduce
--   <a>CmdResult</a>. To avoid this error, use <a>cmd_</a>. If you enable
--   <tt>OverloadedStrings</tt> or <tt>OverloadedLists</tt> you may have to
--   give type signatures to the arguments, or use the more constrained
--   <a>command</a> instead.
--   
--   The <a>cmd</a> function can also be run in the <a>IO</a> monad, but
--   then <a>Traced</a> is ignored and command lines are not echoed. As an
--   example:
--   
--   <pre>
--   <a>cmd</a> (<a>Cwd</a> "generated") <a>Shell</a> "gcc -c myfile.c" :: IO ()
--   </pre>
cmd :: (Partial, CmdArguments args) => args :-> Action r

-- | See <a>cmd</a>. Same as <a>cmd</a> except with a unit result.
--   <a>cmd</a> is to <a>cmd_</a> as <a>command</a> is to <a>command_</a>.
cmd_ :: (Partial, CmdArguments args, Unit args) => args :-> Action ()
unit :: m () -> m ()

-- | Collect the <tt>stdout</tt> of the process. If used, the
--   <tt>stdout</tt> will not be echoed to the terminal, unless you include
--   <a>EchoStdout</a>. The value type may be either <a>String</a>, or
--   either lazy or strict <tt>ByteString</tt>.
--   
--   Note that most programs end their output with a trailing newline, so
--   calling <tt>ghc --numeric-version</tt> will result in <a>Stdout</a> of
--   <tt>"6.8.3\n"</tt>. If you want to automatically trim the resulting
--   string, see <a>StdoutTrim</a>.
newtype Stdout a
Stdout :: a -> Stdout a
[fromStdout] :: Stdout a -> a

-- | Like <a>Stdout</a> but remove all leading and trailing whitespaces.
newtype StdoutTrim a
StdoutTrim :: a -> StdoutTrim a
[fromStdoutTrim] :: StdoutTrim a -> a

-- | Collect the <tt>stderr</tt> of the process. If used, the
--   <tt>stderr</tt> will not be echoed to the terminal, unless you include
--   <a>EchoStderr</a>. The value type may be either <a>String</a>, or
--   either lazy or strict <tt>ByteString</tt>.
newtype Stderr a
Stderr :: a -> Stderr a
[fromStderr] :: Stderr a -> a

-- | Collect the <tt>stdout</tt> and <tt>stderr</tt> of the process. If
--   used, the <tt>stderr</tt> and <tt>stdout</tt> will not be echoed to
--   the terminal, unless you include <a>EchoStdout</a> and
--   <a>EchoStderr</a>. The value type may be either <a>String</a>, or
--   either lazy or strict <tt>ByteString</tt>.
newtype Stdouterr a
Stdouterr :: a -> Stdouterr a
[fromStdouterr] :: Stdouterr a -> a

-- | Collect the <a>ExitCode</a> of the process. If you do not collect the
--   exit code, any <a>ExitFailure</a> will cause an exception.
newtype Exit
Exit :: ExitCode -> Exit
[fromExit] :: Exit -> ExitCode

-- | Collect the <a>ProcessHandle</a> of the process. If you do collect the
--   process handle, the command will run asyncronously and the call to
--   <a>cmd</a> / <a>command</a> will return as soon as the process is
--   spawned. Any <a>Stdout</a> / <a>Stderr</a> captures will return empty
--   strings.
newtype Process
Process :: ProcessHandle -> Process
[fromProcess] :: Process -> ProcessHandle

-- | Collect the time taken to execute the process. Can be used in
--   conjunction with <a>CmdLine</a> to write helper functions that print
--   out the time of a result.
--   
--   <pre>
--   timer :: (<a>CmdResult</a> r, MonadIO m) =&gt; (forall r . <a>CmdResult</a> r =&gt; m r) -&gt; m r
--   timer act = do
--       (<a>CmdTime</a> t, <a>CmdLine</a> x, r) &lt;- act
--       liftIO $ putStrLn $ "Command " ++ x ++ " took " ++ show t ++ " seconds"
--       pure r
--   
--   run :: IO ()
--   run = timer $ <a>cmd</a> "ghc --version"
--   </pre>
newtype CmdTime
CmdTime :: Double -> CmdTime
[fromCmdTime] :: CmdTime -> Double

-- | Collect the command line used for the process. This command line will
--   be approximate - suitable for user diagnostics, but not for direct
--   execution.
newtype CmdLine
CmdLine :: String -> CmdLine
[fromCmdLine] :: CmdLine -> String

-- | The results produced by <tt>fsatrace</tt>. All files will be absolute
--   paths. You can get the results for a <a>cmd</a> by requesting a value
--   of type <tt>[<a>FSATrace</a>]</tt>.
data FSATrace a

-- | Writing to a file
FSAWrite :: a -> FSATrace a

-- | Reading from a file
FSARead :: a -> FSATrace a

-- | Deleting a file
FSADelete :: a -> FSATrace a

-- | Moving, arguments destination, then source
FSAMove :: a -> a -> FSATrace a

-- | Querying/stat on a file
FSAQuery :: a -> FSATrace a

-- | Touching a file
FSATouch :: a -> FSATrace a

-- | A class for specifying what results you want to collect from a
--   process. Values are formed of <a>Stdout</a>, <a>Stderr</a>,
--   <a>Exit</a> and tuples of those.
class CmdResult a

-- | The allowable <a>String</a>-like values that can be captured.
class CmdString a

-- | Options passed to <tt>command</tt> or <tt>cmd</tt> to control how
--   processes are executed.
data CmdOption

-- | Change the current directory in the spawned process. By default uses
--   this processes current directory. Successive <a>Cwd</a> options are
--   joined together, to change into nested directories.
Cwd :: FilePath -> CmdOption

-- | Change the environment variables in the spawned process. By default
--   uses this processes environment.
Env :: [(String, String)] -> CmdOption

-- | Add an environment variable in the child process.
AddEnv :: String -> String -> CmdOption

-- | Remove an environment variable from the child process.
RemEnv :: String -> CmdOption

-- | Add some items to the prefix and suffix of the <tt>$PATH</tt>
--   variable.
AddPath :: [String] -> [String] -> CmdOption

-- | Given as the <tt>stdin</tt> of the spawned process.
Stdin :: String -> CmdOption

-- | Given as the <tt>stdin</tt> of the spawned process.
StdinBS :: ByteString -> CmdOption

-- | Take the <tt>stdin</tt> from a file.
FileStdin :: FilePath -> CmdOption

-- | Pass the command to the shell without escaping - any arguments will be
--   joined with spaces. By default arguments are escaped properly.
Shell :: CmdOption

-- | Treat the <tt>stdin</tt>/<tt>stdout</tt>/<tt>stderr</tt> messages as
--   binary. By default <a>String</a> results use text encoding and
--   <tt>ByteString</tt> results use binary encoding.
BinaryPipes :: CmdOption

-- | Name to use with <tt>traced</tt>, or <tt>""</tt> for no tracing. By
--   default traces using the name of the executable.
Traced :: String -> CmdOption

-- | Abort the computation after N seconds, will raise a failure exit code.
--   Calls <tt>interruptProcessGroupOf</tt> and <tt>terminateProcess</tt>,
--   but may sometimes fail to abort the process and not timeout.
Timeout :: Double -> CmdOption

-- | Should I include the <tt>stdout</tt> in the exception if the command
--   fails? Defaults to <a>False</a>.
WithStdout :: Bool -> CmdOption

-- | Should I include the <tt>stderr</tt> in the exception if the command
--   fails? Defaults to <a>True</a>.
WithStderr :: Bool -> CmdOption

-- | Should I echo the <tt>stdout</tt>? Defaults to <a>True</a> unless a
--   <tt>Stdout</tt> result is required or you use <a>FileStdout</a>.
EchoStdout :: Bool -> CmdOption

-- | Should I echo the <tt>stderr</tt>? Defaults to <a>True</a> unless a
--   <tt>Stderr</tt> result is required or you use <a>FileStderr</a>.
EchoStderr :: Bool -> CmdOption

-- | Should I put the <tt>stdout</tt> to a file.
FileStdout :: FilePath -> CmdOption

-- | Should I put the <tt>stderr</tt> to a file.
FileStderr :: FilePath -> CmdOption

-- | Compute dependencies automatically. Only works if
--   <tt>shakeLintInside</tt> has been set to the files where autodeps
--   might live.
AutoDeps :: CmdOption

-- | The command the user thinks about, before any munging. Defaults to the
--   actual command.
UserCommand :: String -> CmdOption

-- | Options to <tt>fsatrace</tt>, a list of strings with characters such
--   as <tt>"r"</tt> (reads) <tt>"w"</tt> (writes). Defaults to
--   <tt>"rwmdqt"</tt> if the output of <tt>fsatrace</tt> is required.
FSAOptions :: String -> CmdOption

-- | Before starting the command in the child process, close all file
--   handles except stdin, stdout, stderr in the child process. Uses
--   <tt>close_fds</tt> from package process and comes with the same
--   caveats, i.e. runtime is linear with the maximum number of open file
--   handles (<tt>RLIMIT_NOFILE</tt>, see <tt>man 2 getrlimit</tt> on
--   Linux).
CloseFileHandles :: CmdOption

-- | Don't run the process in its own group. Required when running
--   <tt>docker</tt>. Will mean that process timeouts and asyncronous
--   exceptions may not properly clean up child processes.
NoProcessGroup :: CmdOption

-- | Cause the stdin from the parent to be inherited. Might also require
--   NoProcessGroup on Linux. Ignored if you explicitly pass a stdin.
InheritStdin :: CmdOption

-- | <i>Deprecated:</i> Use <a>AddPath</a>. This function will be removed
--   in a future version.
--   
--   Add a prefix and suffix to the <tt>$PATH</tt> environment variable.
--   For example:
--   
--   <pre>
--   opt &lt;- <a>addPath</a> ["/usr/special"] []
--   <a>cmd</a> opt "userbinary --version"
--   </pre>
--   
--   Would prepend <tt>/usr/special</tt> to the current <tt>$PATH</tt>, and
--   the command would pick <tt>/usr/special/userbinary</tt>, if it exists.
--   To add other variables see <a>addEnv</a>.
addPath :: MonadIO m => [String] -> [String] -> m CmdOption

-- | <i>Deprecated:</i> Use <a>AddEnv</a>. This function will be removed in
--   a future version.
--   
--   Add a single variable to the environment. For example:
--   
--   <pre>
--   opt &lt;- <a>addEnv</a> [("CFLAGS","-O2")]
--   <a>cmd</a> opt "gcc -c main.c"
--   </pre>
--   
--   Would add the environment variable <tt>$CFLAGS</tt> with value
--   <tt>-O2</tt>. If the variable <tt>$CFLAGS</tt> was already defined it
--   would be overwritten. If you wish to modify <tt>$PATH</tt> see
--   <a>addPath</a>.
addEnv :: MonadIO m => [(String, String)] -> m CmdOption

-- | Execute a list of actions in parallel. In most cases <tt>need</tt>
--   will be more appropriate to benefit from parallelism. If the two types
--   of <a>Action</a> are different dependencies which ultimately boil down
--   to <tt>apply</tt>, using <a>Applicative</a> operations will still
--   ensure the dependencies occur in parallel. The main use of this
--   function is to run work that happens in an <a>Action</a> in parallel.
parallel :: [Action a] -> Action [a]

-- | A <a>parallel</a> version of <a>forM</a>.
forP :: [a] -> (a -> Action b) -> Action [b]

-- | Execute two operations in parallel, based on <a>parallel</a>.
par :: Action a -> Action b -> Action (a, b)

-- | <tt>copyFile' old new</tt> copies the existing file from <tt>old</tt>
--   to <tt>new</tt>. The <tt>old</tt> file will be tracked as a
--   dependency. Also creates the new directory if necessary.
copyFile' :: Partial => FilePath -> FilePath -> Action ()

-- | <tt>copyFileChanged old new</tt> copies the existing file from
--   <tt>old</tt> to <tt>new</tt>, if the contents have changed. The
--   <tt>old</tt> file will be tracked as a dependency. Also creates the
--   new directory if necessary.
copyFileChanged :: Partial => FilePath -> FilePath -> Action ()

-- | Read a file, after calling <a>need</a>. The argument file will be
--   tracked as a dependency.
readFile' :: Partial => FilePath -> Action String

-- | A version of <a>readFile'</a> which also splits the result into lines.
--   The argument file will be tracked as a dependency.
readFileLines :: Partial => FilePath -> Action [String]

-- | Write a file, lifted to the <a>Action</a> monad.
writeFile' :: (MonadIO m, Partial) => FilePath -> String -> m ()

-- | A version of <a>writeFile'</a> which writes out a list of lines.
writeFileLines :: (MonadIO m, Partial) => FilePath -> [String] -> m ()

-- | Write a file, but only if the contents would change.
writeFileChanged :: (MonadIO m, Partial) => FilePath -> String -> m ()

-- | Remove all files and directories that match any of the patterns within
--   a directory. Some examples:
--   
--   <pre>
--   <a>removeFiles</a> "output" ["//*"]        -- delete everything inside 'output'
--   <a>removeFiles</a> "output" ["//"]         -- delete 'output' itself
--   <a>removeFiles</a> "." ["//*.hi","//*.o"] -- delete all '.hi' and '.o' files
--   </pre>
--   
--   If the argument directory is missing no error is raised. This function
--   will follow symlinks, so should be used with care.
--   
--   This function is often useful when writing a <tt>clean</tt> action for
--   your build system, often as a <tt>phony</tt> rule.
removeFiles :: FilePath -> [FilePattern] -> IO ()

-- | Remove files, like <a>removeFiles</a>, but executed after the build
--   completes successfully using <a>runAfter</a>. Useful for implementing
--   <tt>clean</tt> actions that delete files Shake may have open for
--   building, e.g. <tt>shakeFiles</tt>. Where possible, delete the files
--   as a normal part of the build, e.g. using <tt><a>liftIO</a> $
--   <a>removeFiles</a> dir pats</tt>.
removeFilesAfter :: FilePath -> [FilePattern] -> Action ()

-- | Create a temporary file in the temporary directory. The file will be
--   deleted after the action completes (provided the file is not still
--   open). The <a>FilePath</a> will not have any file extension, will
--   exist, and will be zero bytes long. If you require a file with a
--   specific name, use <a>withTempDir</a>.
withTempFile :: (FilePath -> Action a) -> Action a

-- | Create a temporary directory inside the system temporary directory.
--   The directory will be deleted after the action completes. As an
--   example:
--   
--   <pre>
--   <a>withTempDir</a> $ \mydir -&gt; do
--      <a>putInfo</a> $ "Temp directory is " ++ mydir
--      <a>writeFile'</a> (mydir &lt;/&gt; "test.txt") "writing out a temp file"
--   </pre>
withTempDir :: (FilePath -> Action a) -> Action a

-- | Like <a>withTempFile</a> but using a custom temporary directory.
withTempFileWithin :: FilePath -> (FilePath -> Action a) -> Action a

-- | Like <a>withTempDir</a> but using a custom temporary directory.
withTempDirWithin :: FilePath -> (FilePath -> Action a) -> Action a

-- | Add a dependency on the file arguments, ensuring they are built before
--   continuing. The file arguments may be built in parallel, in any order.
--   This function is particularly necessary when calling <a>cmd</a> or
--   <a>command</a>. As an example:
--   
--   <pre>
--   "//*.rot13" <a>%&gt;</a> \out -&gt; do
--       let src = <a>dropExtension</a> out
--       <a>need</a> [src]
--       <a>cmd</a> "rot13" [src] "-o" [out]
--   </pre>
--   
--   Usually <tt>need [foo,bar]</tt> is preferable to <tt>need [foo]
--   &gt;&gt; need [bar]</tt> as the former allows greater parallelism,
--   while the latter requires <tt>foo</tt> to finish building before
--   starting to build <tt>bar</tt>.
--   
--   This function should not be called with wildcards (e.g. <tt>*.txt</tt>
--   - use <tt>getDirectoryFiles</tt> to expand them), environment
--   variables (e.g. <tt>$HOME</tt> - use <tt>getEnv</tt> to expand them)
--   or directories (directories cannot be tracked directly - track files
--   within the directory instead).
need :: Partial => [FilePath] -> Action ()

-- | Require that the argument files are built by the rules, used to
--   specify the target.
--   
--   <pre>
--   main = <a>shake</a> <a>shakeOptions</a> $ do
--      <a>want</a> ["Main.exe"]
--      ...
--   </pre>
--   
--   This program will build <tt>Main.exe</tt>, given sufficient rules. All
--   arguments to all <a>want</a> calls may be built in parallel, in any
--   order.
--   
--   This function is defined in terms of <a>action</a> and <a>need</a>,
--   use <a>action</a> if you need more complex targets than <a>want</a>
--   allows.
want :: Partial => [FilePath] -> Rules ()

-- | Define a rule that matches a <a>FilePattern</a>, see <a>?==</a> for
--   the pattern rules. Patterns with no wildcards have higher priority
--   than those with wildcards, and no file required by the system may be
--   matched by more than one pattern at the same priority (see
--   <a>priority</a> and <a>alternatives</a> to modify this behaviour).
--   This function will create the directory for the result file, if
--   necessary.
--   
--   <pre>
--   "*.asm.o" <a>%&gt;</a> \out -&gt; do
--       let src = <a>dropExtension</a> out
--       <a>need</a> [src]
--       <a>cmd</a> "as" [src] "-o" [out]
--   </pre>
--   
--   To define a build system for multiple compiled languages, we recommend
--   using <tt>.asm.o</tt>, <tt>.cpp.o</tt>, <tt>.hs.o</tt>, to indicate
--   which language produces an object file. I.e., the file
--   <tt>foo.cpp</tt> produces object file <tt>foo.cpp.o</tt>.
--   
--   Note that matching is case-sensitive, even on Windows.
--   
--   If the <a>Action</a> completes successfully the file is considered
--   up-to-date, even if the file has not changed.
(%>) :: Located => FilePattern -> (FilePath -> Action ()) -> Rules ()
infix 1 %>

-- | Define a set of patterns, and if any of them match, run the associated
--   rule. Defined in terms of <a>%&gt;</a>. Think of it as the OR
--   (<tt>||</tt>) equivalent of <a>%&gt;</a>.
(|%>) :: Located => [FilePattern] -> (FilePath -> Action ()) -> Rules ()
infix 1 |%>

-- | Define a rule to build files. If the first argument returns
--   <a>True</a> for a given file, the second argument will be used to
--   build it. Usually <a>%&gt;</a> is sufficient, but <a>?&gt;</a> gives
--   additional power. For any file used by the build system, only one rule
--   should return <a>True</a>. This function will create the directory for
--   the result file, if necessary.
--   
--   <pre>
--   (all isUpper . <a>takeBaseName</a>) <a>?&gt;</a> \out -&gt; do
--       let src = <a>replaceBaseName</a> out $ map toLower $ takeBaseName out
--       <a>writeFile'</a> out . map toUpper =&lt;&lt; <a>readFile'</a> src
--   </pre>
--   
--   If the <a>Action</a> completes successfully the file is considered
--   up-to-date, even if the file has not changed.
(?>) :: Located => (FilePath -> Bool) -> (FilePath -> Action ()) -> Rules ()
infix 1 ?>

-- | Declare a Make-style phony action. A phony target does not name a file
--   (despite living in the same namespace as file rules); rather, it names
--   some action to be executed when explicitly requested. You can demand
--   <a>phony</a> rules using <a>want</a>. (And <a>need</a>, although
--   that's not recommended.)
--   
--   Phony actions are intended to define recipes that can be executed by
--   the user. If you <a>need</a> a phony action in a rule then every
--   execution where that rule is required will rerun both the rule and the
--   phony action. However, note that phony actions are never executed more
--   than once in a single build run.
--   
--   In make, the <tt>.PHONY</tt> attribute on non-file-producing rules has
--   a similar effect. However, while in make it is acceptable to omit the
--   <tt>.PHONY</tt> attribute as long as you don't create the file in
--   question, a Shake rule which behaves this way will fail lint. For
--   file-producing rules which should be rerun every execution of Shake,
--   see <a>alwaysRerun</a>.
phony :: Located => String -> Action () -> Rules ()

-- | Infix operator alias for <a>phony</a>, for sake of consistency with
--   normal rules.
(~>) :: Located => String -> Action () -> Rules ()
infix 1 ~>

-- | A predicate version of <a>phony</a>, return <a>Just</a> with the
--   <a>Action</a> for the matching rules.
phonys :: Located => (String -> Maybe (Action ())) -> Rules ()

-- | Define a rule for building multiple files at the same time. Think of
--   it as the AND (<tt>&amp;&amp;</tt>) equivalent of <a>%&gt;</a>. As an
--   example, a single invocation of GHC produces both <tt>.hi</tt> and
--   <tt>.o</tt> files:
--   
--   <pre>
--   ["*.o","*.hi"] <a>&amp;%&gt;</a> \[o,hi] -&gt; do
--       let hs = o <a>-&lt;.&gt;</a> "hs"
--       <a>need</a> ... -- all files the .hs import
--       <a>cmd</a> "ghc -c" [hs]
--   </pre>
--   
--   However, in practice, it's usually easier to define rules with
--   <a>%&gt;</a> and make the <tt>.hi</tt> depend on the <tt>.o</tt>. When
--   defining rules that build multiple files, all the <a>FilePattern</a>
--   values must have the same sequence of <tt>//</tt> and <tt>*</tt>
--   wildcards in the same order. This function will create directories for
--   the result files, if necessary.
(&%>) :: Located => [FilePattern] -> ([FilePath] -> Action ()) -> Rules ()
infix 1 &%>

-- | Define a rule for building multiple files at the same time, a more
--   powerful and more dangerous version of <a>&amp;%&gt;</a>. Think of it
--   as the AND (<tt>&amp;&amp;</tt>) equivalent of <a>?&gt;</a>.
--   
--   Given an application <tt>test &amp;?&gt; ...</tt>, <tt>test</tt>
--   should return <tt>Just</tt> if the rule applies, and should return the
--   list of files that will be produced. This list <i>must</i> include the
--   file passed as an argument and should obey the invariant:
--   
--   <pre>
--   forAll $ \x ys -&gt; test x == Just ys ==&gt; x `elem` ys &amp;&amp; all ((== Just ys) . test) ys
--   </pre>
--   
--   Intuitively, the function defines a set partitioning, mapping each
--   element to the partition that contains it. As an example of a function
--   satisfying the invariant:
--   
--   <pre>
--   test x | <a>takeExtension</a> x `elem` [".hi",".o"]
--          = Just [<a>dropExtension</a> x <a>&lt;.&gt;</a> "hi", <a>dropExtension</a> x <a>&lt;.&gt;</a> "o"]
--   test _ = Nothing
--   </pre>
--   
--   Regardless of whether <tt>Foo.hi</tt> or <tt>Foo.o</tt> is passed, the
--   function always returns <tt>[Foo.hi, Foo.o]</tt>.
(&?>) :: Located => (FilePath -> Maybe [FilePath]) -> ([FilePath] -> Action ()) -> Rules ()
infix 1 &?>

-- | Define order-only dependencies, these are dependencies that will
--   always be built before continuing, but which aren't dependencies of
--   this action. Mostly useful for defining generated dependencies you
--   think might be real dependencies. If they turn out to be real
--   dependencies, you should add an explicit dependency afterwards.
--   
--   <pre>
--   "source.o" %&gt; \out -&gt; do
--       <a>orderOnly</a> ["header.h"]
--       <tt>cmd_</tt> "gcc -c source.c -o source.o -MMD -MF source.m"
--       <tt>neededMakefileDependencies</tt> "source.m"
--   </pre>
--   
--   If <tt>header.h</tt> is included by <tt>source.c</tt> then the call to
--   <tt>needMakefileDependencies</tt> will cause it to be added as a real
--   dependency. If it isn't, then the rule won't rebuild if it changes.
orderOnly :: [FilePath] -> Action ()

-- | Run an action but do not depend on anything the action uses. A more
--   general version of <tt>orderOnly</tt>.
orderOnlyAction :: Action a -> Action a

-- | A type synonym for file patterns, containing <tt>//</tt> and
--   <tt>*</tt>. For the syntax and semantics of <a>FilePattern</a> see
--   <a>?==</a>.
--   
--   Most <tt>normaliseEx</tt>d <a>FilePath</a> values are suitable as
--   <a>FilePattern</a> values which match only that specific file. On
--   Windows <tt>\</tt> is treated as equivalent to <tt>/</tt>.
--   
--   You can write <a>FilePattern</a> values as a literal string, or build
--   them up using the operators <a>&lt;.&gt;</a>, <a>&lt;/&gt;</a> and
--   <a>&lt;//&gt;</a>. However, beware that:
--   
--   <ul>
--   <li>On Windows, use <a>&lt;.&gt;</a> from
--   <a>Development.Shake.FilePath</a> instead of from
--   <a>System.FilePath</a> - otherwise <tt>"//*" &lt;.&gt; exe</tt>
--   results in <tt>"//*\\.exe"</tt>.</li>
--   <li>If the second argument of <a>&lt;/&gt;</a> has a leading path
--   separator (namely <tt>/</tt>) then the second argument will be
--   returned.</li>
--   </ul>
type FilePattern = String

-- | Match a <a>FilePattern</a> against a <a>FilePath</a>, There are three
--   special forms:
--   
--   <ul>
--   <li><tt>*</tt> matches an entire path component, excluding any
--   separators.</li>
--   <li><tt>//</tt> matches an arbitrary number of path components,
--   including absolute path prefixes.</li>
--   <li><tt>**</tt> as a path component matches an arbitrary number of
--   path components, but not absolute path prefixes. Currently considered
--   experimental.</li>
--   </ul>
--   
--   Some examples:
--   
--   <ul>
--   <li><tt>test.c</tt> matches <tt>test.c</tt> and nothing else.</li>
--   <li><tt>*.c</tt> matches all <tt>.c</tt> files in the current
--   directory, so <tt>file.c</tt> matches, but <tt>file.h</tt> and
--   <tt>dir/file.c</tt> don't.</li>
--   <li><tt>//*.c</tt> matches all <tt>.c</tt> files anywhere on the
--   filesystem, so <tt>file.c</tt>, <tt>dir/file.c</tt>,
--   <tt>dir1/dir2/file.c</tt> and <tt>/path/to/file.c</tt> all match, but
--   <tt>file.h</tt> and <tt>dir/file.h</tt> don't.</li>
--   <li><tt>dir/*/*</tt> matches all files one level below <tt>dir</tt>,
--   so <tt>dir/one/file.c</tt> and <tt>dir/two/file.h</tt> match, but
--   <tt>file.c</tt>, <tt>one/dir/file.c</tt>, <tt>dir/file.h</tt> and
--   <tt>dir/one/two/file.c</tt> don't.</li>
--   </ul>
--   
--   Patterns with constructs such as <tt>foo/../bar</tt> will never match
--   normalised <a>FilePath</a> values, so are unlikely to be correct.
(?==) :: FilePattern -> FilePath -> Bool

-- | Join two <a>FilePattern</a> values by inserting two <tt>/</tt>
--   characters between them. Will first remove any trailing path
--   separators on the first argument, and any leading separators on the
--   second.
--   
--   <pre>
--   "dir" &lt;//&gt; "*" == "dir//*"
--   </pre>
(<//>) :: FilePattern -> FilePattern -> FilePattern
infixr 5 <//>

-- | Like <a>?==</a>, but returns <a>Nothing</a> on if there is no match,
--   otherwise <a>Just</a> with the list of fragments matching each
--   wildcard. For example:
--   
--   <pre>
--   <a>filePattern</a> "**/*.c" "test.txt" == Nothing
--   <a>filePattern</a> "**/*.c" "foo.c" == Just ["","foo"]
--   <a>filePattern</a> "**/*.c" "bar/baz/foo.c" == Just ["bar/baz/","foo"]
--   </pre>
--   
--   Note that the <tt>**</tt> will often contain a trailing <tt>/</tt>,
--   and even on Windows any <tt>\</tt> separators will be replaced by
--   <tt>/</tt>.
filePattern :: FilePattern -> FilePath -> Maybe [String]

-- | Like <a>need</a>, but if <a>shakeLint</a> is set, check that the file
--   does not rebuild. Used for adding dependencies on files that have
--   already been used in this rule.
needed :: Partial => [FilePath] -> Action ()

-- | Track that a file was read by the action preceding it. If
--   <a>shakeLint</a> is activated then these files must be dependencies of
--   this rule. Calls to <a>trackRead</a> are automatically inserted in
--   <a>LintFSATrace</a> mode.
trackRead :: [FilePath] -> Action ()

-- | Track that a file was written by the action preceding it. If
--   <a>shakeLint</a> is activated then these files must either be the
--   target of this rule, or never referred to by the build system. Calls
--   to <a>trackWrite</a> are automatically inserted in <a>LintFSATrace</a>
--   mode.
trackWrite :: [FilePath] -> Action ()

-- | Allow accessing a file in this rule, ignoring any subsequent
--   <a>trackRead</a> / <a>trackWrite</a> calls matching the pattern.
trackAllow :: [FilePattern] -> Action ()

-- | Returns <a>True</a> if the file exists. The existence of the file is
--   tracked as a dependency, and if the file is created or deleted the
--   rule will rerun in subsequent builds. Usually used to implement
--   include paths. For example, given a include path of <tt>foo</tt> and
--   <tt>bar</tt>, and a file <tt>hello.txt</tt>, you might write:
--   
--   <pre>
--   b &lt;- <a>doesFileExist</a> "foo/hello.txt"
--   let file = if b then "foo/hello.txt" else "bar/hello.txt"
--   </pre>
--   
--   Now if the user had a file <tt>bar/hello.txt</tt>, and then creates a
--   file <tt>foo/hello.txt</tt>, the rule would correctly rerun, as while
--   the <tt>hello.txt</tt> that was used didn't change, which file should
--   be used has changed.
--   
--   You should not call <a>doesFileExist</a> on files which can be created
--   by the build system. The reason is that Shake operations such as this
--   one are both cached for the duration of the build, and may be run
--   preemptively during a recheck. That means you can't control the time
--   at which <a>doesFileExist</a> is called. For that to be consistent,
--   <a>doesFileExist</a> must return the same result at the start and end
--   of the build, a property that is partially checked by the
--   <tt>--lint</tt> flag. Given a file created by the build system, a
--   build from clean will return <a>False</a> at the beginning and
--   <a>True</a> at the end, leading to a change, and thus rebuilds in
--   subsequent runs.
--   
--   If you do want to know whether a file exists separate to the build
--   system, e.g. you can perfectly predict the files contents and can save
--   some meaningful work if the file already exists, you should use the
--   untracked <a>System.Directory</a> version. Such calls are not tracked
--   by the file system, and you should take care not to result in
--   unpredictable results.
doesFileExist :: FilePath -> Action Bool

-- | Returns <a>True</a> if the directory exists. The existence of the
--   directory is tracked as a dependency, and if the directory is created
--   or delete the rule will rerun in subsequent builds.
--   
--   You should not call <a>doesDirectoryExist</a> on directories which can
--   be created by the build system, for reasons explained in
--   <a>doesFileExist</a>.
doesDirectoryExist :: FilePath -> Action Bool

-- | Get the contents of a directory. The result will be sorted, and will
--   not contain the entries <tt>.</tt> or <tt>..</tt> (unlike the standard
--   Haskell version). The resulting paths will be relative to the first
--   argument. The result itself is tracked as a dependency, but the files
--   in the result are not. If the list of files changes in subsequent
--   builds any rule calling it will rerun.
--   
--   It is usually simpler to call either <a>getDirectoryFiles</a> or
--   <a>getDirectoryDirs</a>.
getDirectoryContents :: FilePath -> Action [FilePath]

-- | Get the files anywhere under a directory that match any of a set of
--   patterns. For the interpretation of the patterns see <a>?==</a>. All
--   results will be relative to the directory argument. The result itself
--   is tracked as a dependency, but the files in the result are not. If
--   the list of files changes in subsequent builds any rule calling it
--   will rerun. Some examples:
--   
--   <pre>
--   getDirectoryFiles "Config" ["//*.xml"]
--       -- All .xml files anywhere under the Config directory
--       -- If Config/foo/bar.xml exists it will return ["foo/bar.xml"]
--   getDirectoryFiles "Modules" ["*.hs","*.lhs"]
--       -- All .hs or .lhs in the Modules directory
--       -- If Modules/foo.hs and Modules/foo.lhs exist, it will return ["foo.hs","foo.lhs"]
--   </pre>
--   
--   If you require a qualified file name it is often easier to use
--   <tt>""</tt> as the <a>FilePath</a> argument, for example the following
--   two expressions are equivalent:
--   
--   <pre>
--   fmap (map ("Config" &lt;/&gt;)) (getDirectoryFiles "Config" ["//*.xml"])
--   getDirectoryFiles "" ["Config//*.xml"]
--   </pre>
--   
--   If the first argument directory does not exist it will raise an error.
--   If <tt>foo</tt> does not exist, then the first of these error, but the
--   second will not.
--   
--   <pre>
--   getDirectoryFiles "foo" ["//*"] -- error
--   getDirectoryFiles "" ["foo//*"] -- returns []
--   </pre>
--   
--   This function is tracked and serves as a dependency. If a rule calls
--   <tt>getDirectoryFiles "" ["*.c"]</tt> and someone adds <tt>foo.c</tt>
--   to the directory, that rule will rebuild. If someone changes one of
--   the <tt>.c</tt> files, but the <i>list</i> of <tt>.c</tt> files
--   doesn't change, then it will not rebuild. As a consequence of being
--   tracked, if the contents change during the build (e.g. you are
--   generating <tt>.c</tt> files in this directory) then the build not
--   reach a stable point, which is an error - detected by running with
--   <tt>--lint</tt>. You should normally only call this function returning
--   source files.
--   
--   For an untracked variant see <a>getDirectoryFilesIO</a>.
getDirectoryFiles :: FilePath -> [FilePattern] -> Action [FilePath]

-- | Get the directories in a directory, not including <tt>.</tt> or
--   <tt>..</tt>. All directories are relative to the argument directory.
--   The result itself is tracked as a dependency, but the directories in
--   the result are not. If the list of directories changes in subsequent
--   builds any rule calling it will rerun.
getDirectoryDirs :: FilePath -> Action [FilePath]

-- | A version of <a>getDirectoryFiles</a> that is in IO, and thus
--   untracked.
getDirectoryFilesIO :: FilePath -> [FilePattern] -> IO [FilePath]

-- | Return <a>Just</a> the value of the environment variable, or
--   <a>Nothing</a> if the variable is not set. The environment variable is
--   tracked as a dependency, and if it changes the rule will rerun in
--   subsequent builds. This function is a tracked version of <a>getEnv</a>
--   / <tt>lookupEnv</tt> from the base library.
--   
--   <pre>
--   flags &lt;- getEnv "CFLAGS"
--   <tt>cmd</tt> "gcc -c" [out] (maybe [] words flags)
--   </pre>
getEnv :: String -> Action (Maybe String)

-- | <tt><a>getEnvWithDefault</a> def var</tt> returns the value of the
--   environment variable <tt>var</tt>, or the default value <tt>def</tt>
--   if it is not set. Similar to <a>getEnv</a>.
--   
--   <pre>
--   flags &lt;- getEnvWithDefault "-Wall" "CFLAGS"
--   <tt>cmd</tt> "gcc -c" [out] flags
--   </pre>
getEnvWithDefault :: String -> String -> Action String

-- | A partial variant of <a>getEnv</a> that returns the environment
--   variable variable or fails.
getEnvError :: Partial => String -> Action String

-- | Define an alias for the six type classes required for things involved
--   in Shake rules. Using this alias requires the <tt>ConstraintKinds</tt>
--   extension.
--   
--   To define your own values meeting the necessary constraints it is
--   convenient to use the extensions <tt>GeneralizedNewtypeDeriving</tt>
--   and <tt>DeriveDataTypeable</tt> to write:
--   
--   <pre>
--   newtype MyType = MyType (String, Bool) deriving (Show, Typeable, Eq, Hashable, Binary, NFData)
--   </pre>
--   
--   Shake needs these instances on keys and values. They are used for:
--   
--   <ul>
--   <li><a>Show</a> is used to print out keys in errors, profiling,
--   progress messages and diagnostics.</li>
--   <li><a>Typeable</a> is used because Shake indexes its database by the
--   type of the key and value involved in the rule (overlap is not allowed
--   for type classes and not allowed in Shake either).</li>
--   <li><a>Eq</a> and <a>Hashable</a> are used on keys in order to build
--   hash maps from keys to values. <a>Eq</a> is used on values to test if
--   the value has changed or not (this is used to support unchanging
--   rebuilds, where Shake can avoid rerunning rules if it runs a
--   dependency, but it turns out that no changes occurred.) The
--   <a>Hashable</a> instances are only use at runtime (never serialised to
--   disk), so they do not have to be stable across runs. Hashable on
--   values is not used, and only required for a consistent interface.</li>
--   <li><a>Binary</a> is used to serialize keys and values into Shake's
--   build database; this lets Shake cache values across runs and implement
--   unchanging rebuilds.</li>
--   <li><a>NFData</a> is used to avoid space and thunk leaks, especially
--   when Shake is parallelized.</li>
--   </ul>
type ShakeValue a = (Show a, Typeable a, Eq a, Hashable a, Binary a, NFData a)

-- | The type mapping between the <tt>key</tt> or a rule and the resulting
--   <tt>value</tt>. See <a>addBuiltinRule</a> and <a>apply</a>.
type family RuleResult key

-- | Add extra information which rules can depend on. An oracle is a
--   function from a question type <tt>q</tt>, to an answer type
--   <tt>a</tt>. As an example, we can define an oracle allowing you to
--   depend on the current version of GHC:
--   
--   <pre>
--   newtype GhcVersion = GhcVersion () deriving (Show,Typeable,Eq,Hashable,Binary,NFData)
--   type instance RuleResult GhcVersion = String
--   rules = do
--       <a>addOracle</a> $ \(GhcVersion _) -&gt; <a>fromStdout</a> &lt;$&gt; <a>cmd</a> "ghc --numeric-version" :: Action String
--       ... rules ...
--   </pre>
--   
--   If a rule calls <tt><a>askOracle</a> (GhcVersion ())</tt>, that rule
--   will be rerun whenever the GHC version changes. Some notes:
--   
--   <ul>
--   <li>We define <tt>GhcVersion</tt> with a <tt>newtype</tt> around
--   <tt>()</tt>, allowing the use of <tt>GeneralizedNewtypeDeriving</tt>.
--   All the necessary type classes are exported from
--   <a>Development.Shake.Classes</a>.</li>
--   <li>The <tt>type instance</tt> requires the extension
--   <tt>TypeFamilies</tt>.</li>
--   <li>Each call to <a>addOracle</a> must use a different type of
--   question.</li>
--   <li>Actions passed to <a>addOracle</a> will be run in every build they
--   are required, even if nothing else changes, so be careful of slow
--   actions. If the result of an oracle does not change it will not
--   invalidate any rules depending on it. To always rerun files rules see
--   <a>alwaysRerun</a>.</li>
--   </ul>
--   
--   As a more complex example, consider tracking Haskell package versions:
--   
--   <pre>
--   newtype GhcPkgList = GhcPkgList () deriving (Show,Typeable,Eq,Hashable,Binary,NFData)
--   type instance RuleResult GhcPkgList = [(String, String)]
--   newtype GhcPkgVersion = GhcPkgVersion String deriving (Show,Typeable,Eq,Hashable,Binary,NFData)
--   type instance RuleResult GhcPkgVersion = Maybe String
--   
--   rules = do
--       getPkgList &lt;- <a>addOracle</a> $ \GhcPkgList{} -&gt; do
--           Stdout out &lt;- <a>cmd</a> "ghc-pkg list --simple-output"
--           pure [(reverse b, reverse a) | x &lt;- words out, let (a,_:b) = break (== '-') $ reverse x]
--   
--       getPkgVersion &lt;- <a>addOracle</a> $ \(GhcPkgVersion pkg) -&gt; do
--           pkgs &lt;- getPkgList $ GhcPkgList ()
--           pure $ lookup pkg pkgs
--   
--       "myrule" %&gt; \_ -&gt; do
--           getPkgVersion $ GhcPkgVersion "shake"
--           ... rule using the shake version ...
--   </pre>
--   
--   Using these definitions, any rule depending on the version of
--   <tt>shake</tt> should call <tt>getPkgVersion $ GhcPkgVersion
--   "shake"</tt> to rebuild when <tt>shake</tt> is upgraded.
--   
--   If you apply <a>versioned</a> to an oracle it will cause that oracle
--   result to be discarded, and not do early-termination.
addOracle :: (RuleResult q ~ a, ShakeValue q, ShakeValue a, Partial) => (q -> Action a) -> Rules (q -> Action a)

-- | A combination of <a>addOracle</a> and <tt>newCache</tt> - an action
--   that only runs when its dependencies change, whose result is stored in
--   the database.
--   
--   <ul>
--   <li>Does the information need recomputing every time? e.g. looking up
--   stuff in the environment? If so, use <a>addOracle</a> instead.</li>
--   <li>Is the action mostly deserisalising some file? If so, use
--   <tt>newCache</tt>.</li>
--   <li>Is the operation expensive computation from other results? If so,
--   use <a>addOracleCache</a>.</li>
--   </ul>
--   
--   An alternative to using <a>addOracleCache</a> is introducing an
--   intermediate file containing the result, which requires less storage
--   in the Shake database and can be inspected by existing file-system
--   viewing tools.
addOracleCache :: (RuleResult q ~ a, ShakeValue q, ShakeValue a, Partial) => (q -> Action a) -> Rules (q -> Action a)

-- | An alternative to to <a>addOracle</a> that relies on the <a>hash</a>
--   function providing a perfect equality, doesn't support
--   <tt>--skip</tt>, but requires less storage.
addOracleHash :: (RuleResult q ~ a, ShakeValue q, ShakeValue a, Partial) => (q -> Action a) -> Rules (q -> Action a)

-- | Get information previously added with <a>addOracle</a> or
--   <a>addOracleCache</a>. The question/answer types must match those
--   provided previously.
askOracle :: (RuleResult q ~ a, ShakeValue q, ShakeValue a) => q -> Action a

-- | A parallel version of <a>askOracle</a>.
askOracles :: (RuleResult q ~ a, ShakeValue q, ShakeValue a) => [q] -> Action [a]

-- | Always rerun the associated action. Useful for defining rules that
--   query the environment. For example:
--   
--   <pre>
--   "ghcVersion.txt" <a>%&gt;</a> \out -&gt; do
--       <a>alwaysRerun</a>
--       <a>Stdout</a> stdout &lt;- <a>cmd</a> "ghc --numeric-version"
--       <a>writeFileChanged</a> out stdout
--   </pre>
--   
--   In <tt>make</tt>, the <tt>.PHONY</tt> attribute on file-producing
--   rules has a similar effect.
--   
--   Note that <a>alwaysRerun</a> is applied when a rule is executed.
--   Modifying an existing rule to insert <a>alwaysRerun</a> will
--   <i>not</i> cause that rule to rerun next time.
alwaysRerun :: Action ()

-- | A type representing an external resource which the build system should
--   respect. There are two ways to create <a>Resource</a>s in Shake:
--   
--   <ul>
--   <li><a>newResource</a> creates a finite resource, stopping too many
--   actions running simultaneously.</li>
--   <li><a>newThrottle</a> creates a throttled resource, stopping too many
--   actions running over a short time period.</li>
--   </ul>
--   
--   These resources are used with <a>withResource</a> when defining rules.
--   Typically only system commands (such as <a>cmd</a>) should be run
--   inside <a>withResource</a>, not commands such as <a>need</a>.
--   
--   Be careful that the actions run within <a>withResource</a> do not
--   themselves require further resources, or you may get a "thread blocked
--   indefinitely in an MVar operation" exception. If an action requires
--   multiple resources, use <a>withResources</a> to avoid deadlock.
data Resource

-- | Create a finite resource, given a name (for error messages) and a
--   quantity of the resource that exists. Shake will ensure that actions
--   using the same finite resource do not execute in parallel. As an
--   example, only one set of calls to the Excel API can occur at one time,
--   therefore Excel is a finite resource of quantity 1. You can write:
--   
--   <pre>
--   <a>shake</a> <a>shakeOptions</a>{<a>shakeThreads</a>=2} $ do
--      <a>want</a> ["a.xls","b.xls"]
--      excel &lt;- <a>newResource</a> "Excel" 1
--      "*.xls" <a>%&gt;</a> \out -&gt;
--          <a>withResource</a> excel 1 $
--              <a>cmd</a> "excel" out ...
--   </pre>
--   
--   Now the two calls to <tt>excel</tt> will not happen in parallel.
--   
--   As another example, calls to compilers are usually CPU bound but calls
--   to linkers are usually disk bound. Running 8 linkers will often cause
--   an 8 CPU system to grid to a halt. We can limit ourselves to 4 linkers
--   with:
--   
--   <pre>
--   disk &lt;- <a>newResource</a> "Disk" 4
--   <a>want</a> [show i <a>&lt;.&gt;</a> "exe" | i &lt;- [1..100]]
--   "*.exe" <a>%&gt;</a> \out -&gt;
--       <a>withResource</a> disk 1 $
--           <a>cmd</a> "ld -o" [out] ...
--   "*.o" <a>%&gt;</a> \out -&gt;
--       <a>cmd</a> "cl -o" [out] ...
--   </pre>
newResource :: String -> Int -> Rules Resource

-- | A version of <a>newResource</a> that runs in IO, and can be called
--   before calling <a>shake</a>. Most people should use <a>newResource</a>
--   instead.
newResourceIO :: String -> Int -> IO Resource

-- | Run an action which uses part of a finite resource. For more details
--   see <a>Resource</a>. You cannot depend on a rule (e.g. <tt>need</tt>)
--   while a resource is held.
withResource :: Resource -> Int -> Action a -> Action a

-- | Run an action which uses part of several finite resources. Acquires
--   the resources in a stable order, to prevent deadlock. If all rules
--   requiring more than one resource acquire those resources with a single
--   call to <a>withResources</a>, resources will not deadlock.
withResources :: [(Resource, Int)] -> Action a -> Action a

-- | Create a throttled resource, given a name (for error messages) and a
--   number of resources (the <a>Int</a>) that can be used per time period
--   (the <a>Double</a> in seconds). Shake will ensure that actions using
--   the same throttled resource do not exceed the limits. As an example,
--   let us assume that making more than 1 request every 5 seconds to
--   Google results in our client being blacklisted, we can write:
--   
--   <pre>
--   google &lt;- <a>newThrottle</a> "Google" 1 5
--   "*.url" <a>%&gt;</a> \out -&gt; do
--       <a>withResource</a> google 1 $
--           <a>cmd</a> "wget" ["https://google.com?q=" ++ <a>takeBaseName</a> out] "-O" [out]
--   </pre>
--   
--   Now we will wait at least 5 seconds after querying Google before
--   performing another query. If Google change the rules to allow 12
--   requests per minute we can instead use <tt><a>newThrottle</a> "Google"
--   12 60</tt>, which would allow greater parallelisation, and avoid
--   throttling entirely if only a small number of requests are necessary.
--   
--   In the original example we never make a fresh request until 5 seconds
--   after the previous request has <i>completed</i>. If we instead want to
--   throttle requests since the previous request <i>started</i> we can
--   write:
--   
--   <pre>
--   google &lt;- <a>newThrottle</a> "Google" 1 5
--   "*.url" <a>%&gt;</a> \out -&gt; do
--       <a>withResource</a> google 1 $ pure ()
--       <a>cmd</a> "wget" ["https://google.com?q=" ++ <a>takeBaseName</a> out] "-O" [out]
--   </pre>
--   
--   However, the rule may not continue running immediately after
--   <a>withResource</a> completes, so while we will never exceed an
--   average of 1 request every 5 seconds, we may end up running an
--   unbounded number of requests simultaneously. If this limitation causes
--   a problem in practice it can be fixed.
newThrottle :: String -> Int -> Double -> Rules Resource

-- | A version of <a>newThrottle</a> that runs in IO, and can be called
--   before calling <a>shake</a>. Most people should use <a>newThrottle</a>
--   instead.
newThrottleIO :: String -> Int -> Double -> IO Resource

-- | Run an action without counting to the thread limit, typically used for
--   actions that execute on remote machines using barely any local CPU
--   resources. Unsafe as it allows the <a>shakeThreads</a> limit to be
--   exceeded. You cannot depend on a rule (e.g. <tt>need</tt>) while the
--   extra thread is executing. If the rule blocks (e.g. calls
--   <tt>withResource</tt>) then the extra thread may be used by some other
--   action. Only really suitable for calling <tt>cmd</tt> /
--   <tt>command</tt>.
unsafeExtraThread :: Action a -> Action a

-- | Given an action on a key, produce a cached version that will execute
--   the action at most once per key per run. Using the cached result will
--   still result include any dependencies that the action requires - e.g.
--   if the action does <a>need</a> then those dependencies will be added
--   to every rule that uses that cache. Each call to <a>newCache</a>
--   creates a separate cache that is independent of all other calls to
--   <a>newCache</a>.
--   
--   The operations will not be cached between runs and nothing will be
--   persisted to the Shake database. For an alternative that does persist
--   the cache, see <a>addOracleCache</a>.
--   
--   This function is useful when creating files that store intermediate
--   values, to avoid the overhead of repeatedly reading from disk,
--   particularly if the file requires expensive parsing. As an example:
--   
--   <pre>
--   digits &lt;- <a>newCache</a> $ \file -&gt; do
--       src &lt;- readFile' file
--       pure $ length $ filter isDigit src
--   "*.digits" <a>%&gt;</a> \x -&gt; do
--       v1 &lt;- digits (<tt>dropExtension</tt> x)
--       v2 &lt;- digits (<tt>dropExtension</tt> x)
--       <a>writeFile'</a> x $ show (v1,v2)
--   </pre>
--   
--   To create the result <tt>MyFile.txt.digits</tt> the file
--   <tt>MyFile.txt</tt> will be read and counted, but only at most once
--   per execution.
newCache :: (Eq k, Hashable k) => (k -> Action v) -> Rules (k -> Action v)

-- | A version of <a>newCache</a> that runs in IO, and can be called before
--   calling <a>shake</a>. Most people should use <a>newCache</a> instead.
newCacheIO :: (Eq k, Hashable k) => (k -> Action v) -> IO (k -> Action v)

-- | This rule should not be saved to shared/cloud storage via
--   <a>shakeShare</a>. There are usually two reasons to call this
--   function:
--   
--   <ol>
--   <li>It makes use of untracked dependencies that are specific to this
--   machine, e.g. files in a system directory or items on the
--   <tt>$PATH</tt>.</li>
--   <li>The rule is trivial to compute locally, so there is no point
--   sharing it.</li>
--   </ol>
--   
--   If you want the rule to not be cached at all, use
--   <tt>alwaysRerun</tt>.
historyDisable :: Action ()

-- | This rule builds the following files, in addition to any defined by
--   its target. At the end of the rule these files must have been written.
--   These files must <i>not</i> be tracked as part of the build system -
--   two rules cannot produce the same file and you cannot <a>need</a> the
--   files it produces.
produces :: [FilePath] -> Action ()

-- | Like <a>need</a> but returns a list of rebuilt dependencies since the
--   calling rule last built successfully.
--   
--   The following example writes a list of changed dependencies to a file
--   as its action.
--   
--   <pre>
--   "target" <a>%&gt;</a> \out -&gt; do
--         let sourceList = ["source1", "source2"]
--         rebuildList &lt;- <a>needHasChanged</a> sourceList
--         <a>writeFileLines</a> out rebuildList
--   </pre>
--   
--   This function can be used to alter the action depending on which
--   dependency needed to be rebuild.
--   
--   Note that a rule can be run even if no dependency has changed, for
--   example because of <a>shakeRebuild</a> or because the target has
--   changed or been deleted. To detect the latter case you may wish to use
--   <a>resultHasChanged</a>.
needHasChanged :: Partial => [FilePath] -> Action [FilePath]

-- | Has a file changed. This function will only give the correct answer if
--   called in the rule producing the file, <i>before</i> the rule has
--   modified the file in question. Best avoided, but sometimes necessary
--   in conjunction with <a>needHasChanged</a> to cause rebuilds to happen
--   if the result is deleted or modified.
resultHasChanged :: FilePath -> Action Bool

-- | Batch different outputs into a single <a>Action</a>, typically useful
--   when a command has a high startup cost - e.g. <tt>apt-get install foo
--   bar baz</tt> is a lot cheaper than three separate calls to <tt>apt-get
--   install</tt>. As an example, if we have a standard build rule:
--   
--   <pre>
--   "*.out" <a>%&gt;</a> \out -&gt; do
--       <a>need</a> [out <tt>-&lt;.&gt;</tt> "in"]
--       <a>cmd</a> "build-multiple" [out <tt>-&lt;.&gt;</tt> "in"]
--   </pre>
--   
--   Assuming that <tt>build-multiple</tt> can compile multiple files in a
--   single run, and that the cost of doing so is a lot less than running
--   each individually, we can write:
--   
--   <pre>
--   <a>batch</a> 3 ("*.out" <a>%&gt;</a>)
--       (\out -&gt; do <a>need</a> [out <tt>-&lt;.&gt;</tt> "in"]; pure out)
--       (\outs -&gt; <a>cmd</a> "build-multiple" [out <tt>-&lt;.&gt;</tt> "in" | out &lt;- outs])
--   </pre>
--   
--   In constrast to the normal call, we have specified a maximum batch
--   size of 3, an action to run on each output individually (typically all
--   the <tt>need</tt> dependencies), and an action that runs on multiple
--   files at once. If we were to require lots of <tt>*.out</tt> files,
--   they would typically be built in batches of 3.
--   
--   If Shake ever has nothing else to do it will run batches before they
--   are at the maximum, so you may see much smaller batches, especially at
--   high parallelism settings.
batch :: Int -> ((a -> Action ()) -> Rules ()) -> (a -> Action b) -> ([b] -> Action ()) -> Rules ()

-- | Given a running task, reschedule so it only continues after all other
--   pending tasks, and all rescheduled tasks with a higher pool priority.
--   Note that due to parallelism there is no guarantee that all actions of
--   a higher pool priority will have <i>completed</i> before the action
--   resumes. Only useful if the results are being interactively reported
--   or consumed.
reschedule :: Double -> Action ()

-- | <i>Deprecated:</i> Replace <tt><a>askOracleWith</a> q a</tt> by
--   <tt><a>askOracle</a> q</tt> since the <a>RuleResult</a> type family
--   now fixes the result type.

-- | <i>Deprecated: Use 'askOracle q' instead of 'askOracleWith q a', the
--   result value is now unnecessary</i>
askOracleWith :: (RuleResult q ~ a, ShakeValue q, ShakeValue a) => q -> a -> Action a

-- | <i>Deprecated:</i> Alias for <a>reschedule</a>.

-- | <i>Deprecated: Use <a>reschedule</a> instead</i>
deprioritize :: Double -> Action ()

-- | <i>Deprecated:</i> A bidirectional pattern synonym for <a>Error</a>.
pattern Quiet :: Verbosity

-- | <i>Deprecated:</i> A bidirectional pattern synonym for <a>Info</a>.
pattern Normal :: Verbosity

-- | <i>Deprecated:</i> A bidirectional pattern synonym for <a>Verbose</a>.
pattern Loud :: Verbosity

-- | <i>Deprecated:</i> A bidirectional pattern synonym for <a>Verbose</a>.
pattern Chatty :: Verbosity

-- | <i>Deprecated:</i> Alias for <a>putVerbose</a>.
putLoud :: String -> Action ()

-- | <i>Deprecated:</i> Alias for <a>putInfo</a>.
putNormal :: String -> Action ()

-- | <i>Deprecated:</i> Alias for <a>putError</a>.
putQuiet :: String -> Action ()


-- | A module for useful utility functions for Shake build systems.
module Development.Shake.Util

-- | Given the text of a Makefile, extract the list of targets and
--   dependencies. Assumes a small subset of Makefile syntax, mostly that
--   generated by <tt>gcc -MM</tt>.
--   
--   <pre>
--   parseMakefile "a: b c\nd : e" == [("a",["b","c"]),("d",["e"])]
--   </pre>
parseMakefile :: String -> [(FilePath, [FilePath])]

-- | Depend on the dependencies listed in a Makefile. Does not depend on
--   the Makefile itself.
--   
--   <pre>
--   needMakefileDependencies file = need . concatMap snd . parseMakefile =&lt;&lt; liftIO (readFile file)
--   </pre>
needMakefileDependencies :: FilePath -> Action ()

-- | Depend on the dependencies listed in a Makefile. Does not depend on
--   the Makefile itself. Use this function to indicate that you have
--   <i>already</i> used the files in question.
--   
--   <pre>
--   neededMakefileDependencies file = needed . concatMap snd . parseMakefile =&lt;&lt; liftIO (readFile file)
--   </pre>
neededMakefileDependencies :: FilePath -> Action ()

-- | Like <a>shakeArgsWith</a>, but instead of accumulating a list of
--   flags, apply functions to a default value. Usually used to populate a
--   record structure. As an example of a build system that can use either
--   <tt>gcc</tt> or <tt>distcc</tt> for compiling:
--   
--   <pre>
--   import System.Console.GetOpt
--   
--   data Flags = Flags {distCC :: Bool} deriving Eq
--   flags = [Option "" ["distcc"] (NoArg $ Right $ \x -&gt; x{distCC=True}) "Run distributed."]
--   
--   main = <a>shakeArgsAccumulate</a> <a>shakeOptions</a> flags (Flags False) $ \flags targets -&gt; pure $ Just $ do
--       if null targets then <a>want</a> ["result.exe"] else <a>want</a> targets
--       let compiler = if distCC flags then "distcc" else "gcc"
--       "*.o" <a>%&gt;</a> \out -&gt; do
--           <a>need</a> ...
--           <a>cmd</a> compiler ...
--       ...
--   </pre>
--   
--   Now you can pass <tt>--distcc</tt> to use the <tt>distcc</tt>
--   compiler.
shakeArgsAccumulate :: ShakeOptions -> [OptDescr (Either String (a -> a))] -> a -> (a -> [String] -> IO (Maybe (Rules ()))) -> IO ()

-- | Like <a>shakeArgs</a> but also takes a pruning function. If
--   <tt>--prune</tt> is passed, then after the build has completed, the
--   second argument is called with a list of the files that the build
--   checked were up-to-date.
shakeArgsPrune :: ShakeOptions -> ([FilePath] -> IO ()) -> Rules () -> IO ()

-- | A version of <a>shakeArgsPrune</a> that also takes a list of extra
--   options to use.
shakeArgsPruneWith :: ShakeOptions -> ([FilePath] -> IO ()) -> [OptDescr (Either String a)] -> ([a] -> [String] -> IO (Maybe (Rules ()))) -> IO ()


-- | A module for producing forward-defined build systems, in contrast to
--   standard backwards-defined build systems such as shake. Based around
--   ideas from <a>fabricate</a>. As an example:
--   
--   <pre>
--   import <a>Development.Shake</a>
--   import <a>Development.Shake.Forward</a>
--   import <a>Development.Shake.FilePath</a>
--   
--   main = <a>shakeArgsForward</a> <a>shakeOptions</a> $ do
--       contents &lt;- <a>readFileLines</a> "result.txt"
--       <a>cache</a> $ <a>cmd</a> "tar -cf result.tar" contents
--   </pre>
--   
--   Compared to backward-defined build systems (such as normal Shake),
--   forward-defined build systems tend to be simpler for simple systems
--   (less boilerplate, more direct style), but more complex for larger
--   build systems (requires explicit parallelism, explicit sharing of
--   build products, no automatic command line targets). As a general
--   approach for writing forward-defined systems:
--   
--   <ul>
--   <li>Figure out the sequence of system commands that will build your
--   project.</li>
--   <li>Write a simple <a>Action</a> that builds your project.</li>
--   <li>Insert <a>cache</a> in front of most system commands.</li>
--   <li>Replace most loops with <a>forP</a>, where they can be executed in
--   parallel.</li>
--   <li>Where Haskell performs real computation, if zero-build performance
--   is insufficient, use <a>cacheAction</a>.</li>
--   </ul>
--   
--   All forward-defined systems use <a>AutoDeps</a>, which requires
--   <tt>fsatrace</tt> to be on the <tt>$PATH</tt>. You can obtain
--   <tt>fsatrace</tt> from <a>https://github.com/jacereda/fsatrace</a>.
--   You must set <a>shakeLintInside</a> to specify where <a>AutoDeps</a>
--   will look for dependencies - if you want all dependencies everywhere
--   use <tt>[""]</tt>.
--   
--   This module is considered experimental - it has not been battle
--   tested. There are now a few possible alternatives in this space:
--   
--   <ul>
--   <li>Pier
--   <a>http://hackage.haskell.org/package/pier/docs/Pier-Core-Artifact.html</a>
--   (built on Shake).</li>
--   <li>Rattle <a>https://github.com/ndmitchell/rattle</a> (by the same
--   author as Shake).</li>
--   <li>Stroll <a>https://github.com/snowleopard/stroll</a>.</li>
--   </ul>
module Development.Shake.Forward

-- | Run a forward-defined build system.
shakeForward :: ShakeOptions -> Action () -> IO ()

-- | Run a forward-defined build system, interpreting command-line
--   arguments.
shakeArgsForward :: ShakeOptions -> Action () -> IO ()

-- | Given a <a>ShakeOptions</a>, set the options necessary to execute in
--   forward mode.
forwardOptions :: ShakeOptions -> ShakeOptions

-- | Given an <a>Action</a>, turn it into a <a>Rules</a> structure which
--   runs in forward mode.
forwardRule :: Action () -> Rules ()

-- | Apply caching to an external command using the same arguments as
--   <a>cmd</a>.
--   
--   <pre>
--   cache $ cmd "gcc -c" ["foo.c"] "-o" ["foo.o"]
--   </pre>
--   
--   This command will be cached, with the inputs/outputs traced. If any of
--   the files used by this command (e.g. <tt>foo.c</tt> or header files it
--   imports) then the command will rerun.
cache :: (forall r. CmdArguments r => r) -> Action ()

-- | Cache an action, given a key and an <a>Action</a>. Each call in your
--   program should specify a different key, but the key should remain
--   consistent between runs. Ideally, the <a>Action</a> will gather all
--   its dependencies with tracked operations, e.g. 'readFile''. However,
--   if information is accessed from the environment (e.g. the action is a
--   closure), you should call <a>cacheActionWith</a> being explicit about
--   what is captured.
cacheAction :: (Typeable a, Binary a, Show a, Typeable b, Binary b, Show b) => a -> Action b -> Action b

-- | Like <a>cacheAction</a>, but also specify which information is
--   captured by the closure of the <a>Action</a>. If that information
--   changes, the <a>Action</a> will be rerun.
cacheActionWith :: (Typeable a, Binary a, Show a, Typeable b, Binary b, Show b, Typeable c, Binary c, Show c) => a -> b -> Action c -> Action c
instance Data.Binary.Class.Binary Development.Shake.Forward.Forward
instance Control.DeepSeq.NFData Development.Shake.Forward.Forward
instance GHC.Classes.Eq Development.Shake.Forward.Forward
instance Data.Hashable.Class.Hashable Development.Shake.Forward.Forward
instance GHC.Show.Show a => GHC.Show.Show (Development.Shake.Forward.With a)
instance Data.Binary.Class.Binary a => Data.Binary.Class.Binary (Development.Shake.Forward.With a)
instance Data.Binary.Class.Binary Development.Shake.Forward.Command
instance GHC.Show.Show Development.Shake.Forward.Command
instance GHC.Show.Show Development.Shake.Forward.Forward


-- | A module for parsing and using config files in a Shake build system.
--   Config files consist of variable bindings, for example:
--   
--   <pre>
--   # This is my Config file
--   HEADERS_DIR = /path/to/dir
--   CFLAGS = -g -I${HEADERS_DIR}
--   CFLAGS = $CFLAGS -O2
--   include extra/file.cfg
--   </pre>
--   
--   This defines the variable <tt>HEADERS_DIR</tt> (equal to
--   <tt>/path/to/dir</tt>), and <tt>CFLAGS</tt> (equal to <tt>-g
--   -I/path/to/dir -O2</tt>), and also includes the configuration
--   statements in the file <tt>extra/file.cfg</tt>. The full lexical
--   syntax for configuration files is defined here:
--   <a>https://ninja-build.org/manual.html#_lexical_syntax</a>. The use of
--   Ninja file syntax is due to convenience and the desire to reuse an
--   externally-defined specification (but the choice of configuration
--   language is mostly arbitrary).
--   
--   To use the configuration file either use <a>readConfigFile</a> to
--   parse the configuration file and use the values directly, or
--   <a>usingConfigFile</a> and <a>getConfig</a> to track the configuration
--   values, so they become build dependencies.
module Development.Shake.Config

-- | Read a config file, returning a list of the variables and their
--   bindings. Config files use the Ninja lexical syntax:
--   <a>https://ninja-build.org/manual.html#_lexical_syntax</a>
readConfigFile :: FilePath -> IO (HashMap String String)

-- | Read a config file with an initial environment, returning a list of
--   the variables and their bindings. Config files use the Ninja lexical
--   syntax: <a>https://ninja-build.org/manual.html#_lexical_syntax</a>
readConfigFileWithEnv :: [(String, String)] -> FilePath -> IO (HashMap String String)

-- | Specify the file to use with <a>getConfig</a>.
usingConfigFile :: FilePath -> Rules ()

-- | Specify the values to use with <a>getConfig</a>, generally prefer
--   <a>usingConfigFile</a> unless you also need access to the values of
--   variables outside <a>Action</a>.
usingConfig :: HashMap String String -> Rules ()

-- | Obtain the value of a configuration variable, returns <a>Nothing</a>
--   to indicate the variable has no binding. Any build system using
--   <a>getConfig</a> <i>must</i> call either <a>usingConfigFile</a> or
--   <a>usingConfig</a>. The <a>getConfig</a> function will introduce a
--   dependency on the configuration variable (but not the whole
--   configuration file), and if the configuration variable changes, the
--   rule will be rerun. As an example:
--   
--   <pre>
--   <a>usingConfigFile</a> "myconfiguration.cfg"
--   "*.o" <a>%&gt;</a> \out -&gt; do
--       cflags &lt;- <a>getConfig</a> "CFLAGS"
--       <a>cmd</a> "gcc" [out <tt>-&lt;.&gt;</tt> "c"] (fromMaybe "" cflags)
--   </pre>
getConfig :: String -> Action (Maybe String)

-- | Obtain the configuration keys. Any build system using
--   <a>getConfigKeys</a> <i>must</i> call either <a>usingConfigFile</a> or
--   <a>usingConfig</a>. The <a>getConfigKeys</a> function will introduce a
--   dependency on the configuration keys (but not the whole configuration
--   file), and if the configuration keys change, the rule will be rerun.
--   Usually use as part of an action. As an example:
--   
--   <pre>
--   <a>usingConfigFile</a> "myconfiguration.cfg"
--   <a>action</a> $ need =&lt;&lt; getConfigKeys
--   </pre>
getConfigKeys :: Action [String]
instance Control.DeepSeq.NFData Development.Shake.Config.Config
instance Data.Binary.Class.Binary Development.Shake.Config.Config
instance Data.Hashable.Class.Hashable Development.Shake.Config.Config
instance GHC.Classes.Eq Development.Shake.Config.Config
instance GHC.Show.Show Development.Shake.Config.Config
instance Control.DeepSeq.NFData Development.Shake.Config.ConfigKeys
instance Data.Binary.Class.Binary Development.Shake.Config.ConfigKeys
instance Data.Hashable.Class.Hashable Development.Shake.Config.ConfigKeys
instance GHC.Classes.Eq Development.Shake.Config.ConfigKeys
instance GHC.Show.Show Development.Shake.Config.ConfigKeys
