-- 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. Further examples are included in
--   the Cabal tarball, under the <tt>Examples</tt> directory. The homepage
--   contains links to a user manual, an academic paper and further
--   information: <a>http://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.15.5


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

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

-- | Normalise a <a>FilePath</a>, trying to do:
--   
--   <ul>
--   <li>All <a>pathSeparators</a> become <tt>/</tt></li>
--   <li><tt>foo/bar/../baz</tt> becomes <tt>foo/baz</tt></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 normalise function from the filepath
--   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 reexports the six necessary type classes that every
--   <tt>Rule</tt> type must support. 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

-- | Conversion of values to readable <a>String</a>s.
--   
--   Derived instances of <a>Show</a> have the following properties, which
--   are compatible with derived instances of <a>Read</a>:
--   
--   <ul>
--   <li>The result of <a>show</a> is a syntactically correct Haskell
--   expression containing only constants, given the fixity declarations in
--   force at the point where the type is declared. It contains only the
--   constructor names defined in the data type, parentheses, and spaces.
--   When labelled constructor fields are used, braces, commas, field
--   names, and equal signs are also used.</li>
--   <li>If the constructor is defined to be an infix operator, then
--   <a>showsPrec</a> will produce infix applications of the
--   constructor.</li>
--   <li>the representation will be enclosed in parentheses if the
--   precedence of the top-level constructor in <tt>x</tt> is less than
--   <tt>d</tt> (associativity is ignored). Thus, if <tt>d</tt> is
--   <tt>0</tt> then the result is never surrounded in parentheses; if
--   <tt>d</tt> is <tt>11</tt> it is always surrounded in parentheses,
--   unless it is an atomic expression.</li>
--   <li>If the constructor is defined using record syntax, then
--   <a>show</a> will produce the record-syntax form, with the fields given
--   in the same order as the original declaration.</li>
--   </ul>
--   
--   For example, given the declarations
--   
--   <pre>
--   infixr 5 :^:
--   data Tree a =  Leaf a  |  Tree a :^: Tree a
--   </pre>
--   
--   the derived instance of <a>Show</a> is equivalent to
--   
--   <pre>
--   instance (Show a) =&gt; Show (Tree a) where
--   
--          showsPrec d (Leaf m) = showParen (d &gt; app_prec) $
--               showString "Leaf " . showsPrec (app_prec+1) m
--            where app_prec = 10
--   
--          showsPrec d (u :^: v) = showParen (d &gt; up_prec) $
--               showsPrec (up_prec+1) u .
--               showString " :^: "      .
--               showsPrec (up_prec+1) v
--            where up_prec = 5
--   </pre>
--   
--   Note that right-associativity of <tt>:^:</tt> is ignored. For example,
--   
--   <ul>
--   <li><tt><a>show</a> (Leaf 1 :^: Leaf 2 :^: Leaf 3)</tt> produces the
--   string <tt>"Leaf 1 :^: (Leaf 2 :^: Leaf 3)"</tt>.</li>
--   </ul>
class Show a

-- | Convert a value to a readable <a>String</a>.
--   
--   <a>showsPrec</a> should satisfy the law
--   
--   <pre>
--   showsPrec d x r ++ s  ==  showsPrec d x (r ++ s)
--   </pre>
--   
--   Derived instances of <a>Read</a> and <a>Show</a> satisfy the
--   following:
--   
--   <ul>
--   <li><tt>(x,"")</tt> is an element of <tt>(<a>readsPrec</a> d
--   (<a>showsPrec</a> d x ""))</tt>.</li>
--   </ul>
--   
--   That is, <a>readsPrec</a> parses the string produced by
--   <a>showsPrec</a>, and delivers the value that <a>showsPrec</a> started
--   with.
showsPrec :: Show a => Int -> a -> ShowS

-- | A specialised variant of <a>showsPrec</a>, using precedence context
--   zero, and returning an ordinary <a>String</a>.
show :: Show a => a -> String

-- | The method <a>showList</a> is provided to allow the programmer to give
--   a specialised way of showing lists of values. For example, this is
--   used by the predefined <a>Show</a> instance of the <a>Char</a> type,
--   where values of type <a>String</a> should be shown in double quotes,
--   rather than between square brackets.
showList :: Show a => [a] -> ShowS

-- | The class <a>Typeable</a> allows a concrete representation of a type
--   to be calculated.
class Typeable (a :: k)

-- | The <a>Eq</a> class defines equality (<a>==</a>) and inequality
--   (<a>/=</a>). All the basic datatypes exported by the <a>Prelude</a>
--   are instances of <a>Eq</a>, and <a>Eq</a> may be derived for any
--   datatype whose constituents are also instances of <a>Eq</a>.
--   
--   Minimal complete definition: either <a>==</a> or <a>/=</a>.
class Eq a
(==) :: Eq a => a -> a -> Bool
(/=) :: Eq a => a -> a -> Bool

-- | The class of types that can be converted to a hash value.
--   
--   Minimal implementation: <a>hashWithSalt</a>.
class Hashable a

-- | Return a hash value for the argument, using the given salt.
--   
--   The general contract of <a>hashWithSalt</a> is:
--   
--   <ul>
--   <li>If two values are equal according to the <a>==</a> method, then
--   applying the <a>hashWithSalt</a> method on each of the two values
--   <i>must</i> produce the same integer result if the same salt is used
--   in each case.</li>
--   <li>It is <i>not</i> required that if two values are unequal according
--   to the <a>==</a> method, then applying the <a>hashWithSalt</a> method
--   on each of the two values must produce distinct integer results.
--   However, the programmer should be aware that producing distinct
--   integer results for unequal values may improve the performance of
--   hashing-based data structures.</li>
--   <li>This method can be used to compute different hash values for the
--   same input by providing a different salt in each application of the
--   method. This implies that any instance that defines
--   <a>hashWithSalt</a> <i>must</i> make use of the salt in its
--   implementation.</li>
--   </ul>
hashWithSalt :: Hashable a => Int -> a -> Int

-- | Like <a>hashWithSalt</a>, but no salt is used. The default
--   implementation uses <a>hashWithSalt</a> with some default salt.
--   Instances might want to implement this method to provide a more
--   efficient implementation than the default implementation.
hash :: Hashable a => a -> Int

-- | The <a>Binary</a> class provides <a>put</a> and <a>get</a>, methods to
--   encode and decode a Haskell value to a lazy <a>ByteString</a>. It
--   mirrors the <a>Read</a> and <a>Show</a> classes for textual
--   representation of Haskell types, and is suitable for serialising
--   Haskell values to disk, over the network.
--   
--   For decoding and generating simple external binary formats (e.g. C
--   structures), Binary may be used, but in general is not suitable for
--   complex protocols. Instead use the <a>Put</a> and <a>Get</a>
--   primitives directly.
--   
--   Instances of Binary should satisfy the following property:
--   
--   <pre>
--   decode . encode == id
--   </pre>
--   
--   That is, the <a>get</a> and <a>put</a> methods should be the inverse
--   of each other. A range of instances are provided for basic Haskell
--   types.
class Binary t

-- | Encode a value in the Put monad.
put :: Binary t => t -> Put

-- | Decode a value in the Get monad
get :: Binary t => Get t

-- | A class of types that can be fully evaluated.
--   
--   <i>Since: 1.1.0.0</i>
class NFData a

-- | <a>rnf</a> should reduce its argument to normal form (that is, fully
--   evaluate all sub-components), and then return '()'.
--   
--   <h3><a>Generic</a> <a>NFData</a> deriving</h3>
--   
--   Starting with GHC 7.2, you can automatically derive instances for
--   types possessing a <a>Generic</a> instance.
--   
--   <pre>
--   {-# LANGUAGE DeriveGeneric #-}
--   
--   import GHC.Generics (Generic)
--   import Control.DeepSeq
--   
--   data Foo a = Foo a String
--                deriving (Eq, Generic)
--   
--   instance NFData a =&gt; NFData (Foo a)
--   
--   data Colour = Red | Green | Blue
--                 deriving Generic
--   
--   instance NFData Colour
--   </pre>
--   
--   Starting with GHC 7.10, the example above can be written more
--   concisely by enabling the new <tt>DeriveAnyClass</tt> extension:
--   
--   <pre>
--   {-# LANGUAGE DeriveGeneric, DeriveAnyClass #-}
--   
--   import GHC.Generics (Generic)
--   import Control.DeepSeq
--   
--   data Foo a = Foo a String
--                deriving (Eq, Generic, NFData)
--   
--   data Colour = Red | Green | Blue
--                 deriving (Generic, NFData)
--   </pre>
--   
--   <h3>Compatibility with previous <tt>deepseq</tt> versions</h3>
--   
--   Prior to version 1.4.0.0, the default implementation of the <a>rnf</a>
--   method was defined as
--   
--   <pre>
--   <a>rnf</a> a = <a>seq</a> a ()
--   </pre>
--   
--   However, starting with <tt>deepseq-1.4.0.0</tt>, the default
--   implementation is based on <tt>DefaultSignatures</tt> allowing for
--   more accurate auto-derived <a>NFData</a> instances. If you need the
--   previously used exact default <a>rnf</a> method implementation
--   semantics, use
--   
--   <pre>
--   instance NFData Colour where rnf x = seq x ()
--   </pre>
--   
--   or alternatively
--   
--   <pre>
--   {-# LANGUAGE BangPatterns #-}
--   instance NFData Colour where rnf !_ = ()
--   </pre>
rnf :: NFData a => a -> ()


-- | 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 :: 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_ :: [CmdOption] -> String -> [String] -> Action ()

-- | Execute a system command. Before running <a>cmd</a> make sure you
--   <a>need</a> any files that are used by the command.
--   
--   <ul>
--   <li><tt>String</tt> arguments are treated as whitespace separated
--   arguments.</li>
--   <li><tt>[String]</tt> arguments are treated as literal arguments.</li>
--   <li><a>CmdOption</a> arguments are used as options.</li>
--   </ul>
--   
--   As some examples, here are some calls, and the resulting command
--   string:
--   
--   <pre>
--   <a>unit</a> $ <a>cmd</a> "git log --pretty=" "oneline"           -- git log --pretty= oneline
--   <a>unit</a> $ <a>cmd</a> "git log --pretty=" ["oneline"]         -- git log --pretty= oneline
--   <a>unit</a> $ <a>cmd</a> "git log" ("--pretty=" ++ "oneline")    -- git log --pretty=oneline
--   <a>unit</a> $ <a>cmd</a> "git log" ("--pretty=" ++ "one line")   -- git log --pretty=one line
--   <a>unit</a> $ <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>
--   () &lt;- <a>cmd</a> "gcc -c myfile.c"                                  -- compile a file, throwing an exception on failure
--   <a>unit</a> $ <a>cmd</a> "gcc -c myfile.c"                                 -- alternative to () &lt;- binding.
--   <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
--   </pre>
--   
--   When passing file arguments we use <tt>[myfile]</tt> so that if the
--   <tt>myfile</tt> variable contains spaces they are properly escaped.
--   
--   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, bind the result to <tt>()</tt>,
--   or include a type signature, or use the <a>unit</a> function.
--   
--   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 :: CmdArguments args => args :-> Action r

-- | The identity function which requires the inner argument to be
--   <tt>()</tt>. Useful for functions with overloaded return types.
--   
--   <pre>
--   \(x :: Maybe ()) -&gt; unit x == x
--   </pre>
unit :: m () -> m ()
class CmdArguments t

-- | 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>.
newtype Stdout a
Stdout :: a -> Stdout a
[fromStdout] :: Stdout 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
--   'cmd'/'command' will return as soon as the process is spawned. Any
--   'Stdout'\/'Stderr' 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"
--       return 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

-- | 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
class CmdString a

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

-- | Change the current directory in the spawned process. By default uses
--   this processes current directory.
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

-- | 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. By default the
--   <tt>stdin</tt> is inherited.
Stdin :: String -> CmdOption

-- | Given as the <tt>stdin</tt> of the spawned process.
StdinBS :: ByteString -> 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 <a>traced</a>, 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 <a>interruptProcessGroupOf</a> and <a>terminateProcess</a>, 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
--   <a>Stdout</a> 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
--   <a>Stderr</a> 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

-- | <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.Classes.Eq Development.Shake.Command.Result
instance GHC.Classes.Eq Development.Shake.Command.Str
instance GHC.Show.Show Development.Shake.Command.CmdOption
instance GHC.Classes.Ord Development.Shake.Command.CmdOption
instance GHC.Classes.Eq Development.Shake.Command.CmdOption
instance GHC.Classes.Eq Development.Shake.Command.Pid
instance Development.Shake.Command.CmdString ()
instance Development.Shake.Command.CmdString GHC.Base.String
instance Development.Shake.Command.CmdString Data.ByteString.Internal.ByteString
instance Development.Shake.Command.CmdString Data.ByteString.Lazy.Internal.ByteString
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.Internals.ProcessHandle
instance Development.Shake.Command.CmdResult Development.Shake.Command.CmdLine
instance Development.Shake.Command.CmdResult Development.Shake.Command.CmdTime
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.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.Arg a, Development.Shake.Command.CmdArguments r) => Development.Shake.Command.CmdArguments (a -> r)
instance Development.Shake.Command.CmdResult r => Development.Shake.Command.CmdArguments (Development.Shake.Core.Action r)
instance Development.Shake.Command.CmdResult r => Development.Shake.Command.CmdArguments (GHC.Types.IO r)
instance Development.Shake.Command.Arg GHC.Base.String
instance Development.Shake.Command.Arg [GHC.Base.String]
instance Development.Shake.Command.Arg Development.Shake.Command.CmdOption
instance Development.Shake.Command.Arg [Development.Shake.Command.CmdOption]
instance Development.Shake.Command.Arg a => Development.Shake.Command.Arg (GHC.Base.Maybe a)


-- | This module is used for defining new types of rules for Shake build
--   systems. Most users will find the built-in set of rules sufficient.
module Development.Shake.Rule

-- | Define an alias for the six type classes required for things involved
--   in Shake <a>Rule</a>s. This alias is only available in GHC 7.4 and
--   above, and 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>
type ShakeValue a = (Show a, Typeable a, Eq a, Hashable a, Binary a, NFData a)

-- | Define a pair of types that can be used by Shake rules. To import all
--   the type classes required see <a>Development.Shake.Classes</a>.
--   
--   A <a>Rule</a> instance for a class of artifacts (e.g. <i>files</i>)
--   provides:
--   
--   <ul>
--   <li>How to identify individual artifacts, given by the <tt>key</tt>
--   type, e.g. with file names.</li>
--   <li>How to describe the state of an artifact, given by the
--   <tt>value</tt> type, e.g. the file modification time.</li>
--   <li>A way to compare two states of the same individual artifact, with
--   <a>equalValue</a> returning either <a>EqualCheap</a> or
--   <a>NotEqual</a>.</li>
--   <li>A way to query the current state of an artifact, with
--   <a>storedValue</a> returning the current state, or <a>Nothing</a> if
--   there is no current state (e.g. the file does not exist).</li>
--   </ul>
--   
--   Checking if an artifact needs to be built consists of comparing two
--   <tt>value</tt>s of the same <tt>key</tt> with <a>equalValue</a>. The
--   first value is obtained by applying <a>storedValue</a> to the
--   <tt>key</tt> and the second is the value stored in the build database
--   after the last successful build.
--   
--   As an example, below is a simplified rule for building files, where
--   files are identified by a <a>FilePath</a> and their state is
--   identified by a hash of their contents (the builtin functions
--   <a>need</a> and <a>%&gt;</a> provide a similar rule).
--   
--   <pre>
--   newtype File = File FilePath deriving (Show, Typeable, Eq, Hashable, Binary, NFData)
--   newtype Modtime = Modtime Double deriving (Show, Typeable, Eq, Hashable, Binary, NFData)
--   getFileModtime file = ...
--   
--   instance Rule File Modtime where
--       storedValue _ (File x) = do
--           exists &lt;- System.Directory.doesFileExist x
--           if exists then Just &lt;$&gt; getFileModtime x else return Nothing
--       equalValue _ _ t1 t2 =
--           if t1 == t2 then EqualCheap else NotEqual
--    
--   </pre>
--   
--   This example instance means:
--   
--   <ul>
--   <li>A value of type <tt>File</tt> uniquely identifies a generated
--   file.</li>
--   <li>A value of type <tt>Modtime</tt> will be used to check if a file
--   is up-to-date.</li>
--   </ul>
--   
--   It is important to distinguish <a>Rule</a> instances from actual
--   <i>rules</i>. <a>Rule</a> instances are one component required for the
--   creation of rules. Actual <i>rules</i> are functions from a
--   <tt>key</tt> to an <a>Action</a>; they are added to <a>Rules</a> using
--   the <a>rule</a> function.
--   
--   A rule can be created for the instance above with:
--   
--   <pre>
--   -- Compile foo files; for every foo output file there must be a
--   -- single input file named "filename.foo".
--   compileFoo :: <a>Rules</a> ()
--   compileFoo = <a>rule</a> (Just . compile)
--       where
--           compile :: File -&gt; <a>Action</a> Modtime
--           compile (File outputFile) = do
--               -- figure out the name of the input file
--               let inputFile = outputFile <tt>&lt;.&gt;</tt> "foo"
--               <a>unit</a> $ <a>cmd</a> "fooCC" inputFile outputFile
--               -- return the (new) file modtime of the output file:
--               getFileModtime outputFile
--   </pre>
--   
--   <i>Note:</i> In this example, the timestamps of the input files are
--   never used, let alone compared to the timestamps of the ouput files.
--   Dependencies between output and input files are <i>not</i> expressed
--   by <a>Rule</a> instances. Dependencies are created automatically by
--   <a>apply</a>.
--   
--   For rules whose values are not stored externally, <a>storedValue</a>
--   should return <a>Just</a> with a sentinel value and <a>equalValue</a>
--   should always return <a>EqualCheap</a> for that sentinel.
class (ShakeValue key, ShakeValue value) => Rule key value where equalValue _ _ v1 v2 = if v1 == v2 then EqualCheap else NotEqual

-- | <i>[Required]</i> Retrieve the <tt>value</tt> associated with a
--   <tt>key</tt>, if available.
--   
--   As an example for filenames/timestamps, if the file exists you should
--   return <a>Just</a> the timestamp, but otherwise return <a>Nothing</a>.
storedValue :: Rule key value => ShakeOptions -> key -> IO (Maybe value)

-- | <i>[Optional]</i> Equality check, with a notion of how expensive the
--   check was.
equalValue :: Rule key value => ShakeOptions -> key -> value -> value -> EqualCost

-- | An equality check and a cost.
data EqualCost

-- | The equality check was cheap.
EqualCheap :: EqualCost

-- | The equality check was expensive, as the results are not trivially
--   equal.
EqualExpensive :: EqualCost

-- | The values are not equal.
NotEqual :: EqualCost

-- | Add a rule to build a key, returning an appropriate <a>Action</a>. All
--   rules at a given priority must be disjoint. Rules have priority 1 by
--   default, but can be modified with <a>priority</a>.
rule :: Rule key value => (key -> Maybe (Action value)) -> Rules ()

-- | 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>rule</a>. All <tt>key</tt> values passed
--   to <a>apply</a> become dependencies of the <a>Action</a>.
apply :: Rule key 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 :: Rule key value => key -> Action value

-- | Track that a key has been used by the action preceeding it.
trackUse :: ShakeValue key => key -> Action ()

-- | Track that a key has been changed by the action preceeding it.
trackChange :: ShakeValue key => key -> Action ()

-- | Allow any matching key to violate the tracking rules.
trackAllow :: ShakeValue key => (key -> Bool) -> Action ()

-- | A deprecated way of defining a low priority rule. Defined as:
--   
--   <pre>
--   defaultRule = <a>priority</a> 0 . <a>rule</a>
--   </pre>

-- | <i>Deprecated: Use <a>rule</a> with <a>priority</a> 0</i>
defaultRule :: Rule key value => (key -> Maybe (Action value)) -> Rules ()


-- | 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>http://www.shakebuild.com/manual</a>.</li>
--   <li>The home page has links to additional information
--   <a>http://www.shakebuild.com/</a>, including a mailing list.</li>
--   <li>The theory behind Shake is described in an ICFP 2012 paper,
--   <i>Shake Before Building -- Replacing Make with Haskell</i>
--   <a>http://community.haskell.org/~ndm/downloads/paper-shake_before_building-10_sep_2012.pdf</a>.
--   The associated talk forms a short overview of Shake
--   <a>http://www.youtube.com/watch?v=xYCPpXVlqFM</a>.</li>
--   </ul>
--   
--   <i>== WRITING A BUILD SYSTEM ==============================</i>
--   
--   When writing a Shake build system, start by defining what you
--   <a>want</a>, then write rules with <a>%&gt;</a> to produce the
--   results. Before calling <a>cmd</a> you should ensure that any files
--   the command requires are demanded with calls to <a>need</a>. We offer
--   the following advice to Shake users:
--   
--   <ul>
--   <li>If <tt>ghc --make</tt> or <tt>cabal</tt> is capable of building
--   your project, use that instead. Custom build systems are necessary for
--   many complex projects, but many projects are not complex.</li>
--   <li>The <a>shakeArgs</a> function automatically handles command line
--   arguments. To define non-file targets use <a>phony</a>.</li>
--   <li>Put all result files in a distinguished directory, for example
--   <tt>_make</tt>. You can implement a <tt>clean</tt> command by removing
--   that directory, using <tt><a>removeFilesAfter</a> "_make"
--   ["//*"]</tt>.</li>
--   <li>To obtain parallel builds set <a>shakeThreads</a> to a number
--   greater than 1.</li>
--   <li>Lots of compilers produce <tt>.o</tt> files. To avoid overlapping
--   rules, use <tt>.c.o</tt> for C compilers, <tt>.hs.o</tt> for Haskell
--   compilers etc.</li>
--   <li>Do not be afraid to mix Shake rules, system commands and other
--   Haskell libraries -- use each for what it does best.</li>
--   <li>The more accurate the dependencies are, the better. Use additional
--   rules like <a>doesFileExist</a> and <a>getDirectoryFiles</a> to track
--   information other than just the contents of files. For information in
--   the environment that you suspect will change regularly (perhaps
--   <tt>ghc</tt> version number), either write the information to a file
--   with <a>alwaysRerun</a> and <a>writeFileChanged</a>, or use
--   <a>addOracle</a>.</li>
--   </ul>
--   
--   <i>== GHC BUILD FLAGS ==============================</i>
--   
--   For large build systems the choice of GHC flags can have a significant
--   impact. We recommend:
--   
--   <pre>
--   ghc --make MyBuildSystem -rtsopts -with-rtsopts=-I0
--   </pre>
--   
--   <ul>
--   <li><tt>-rtsopts</tt>: Allow the setting of further GHC options at
--   runtime.</li>
--   <li><tt>-I0</tt>: Disable idle garbage collection. In a build system
--   regularly running many system commands the program appears "idle" very
--   often, triggering regular unnecessary garbage collection, stealing
--   resources from the program doing actual work.</li>
--   <li>With GHC 7.6 and before, omit <tt>-threaded</tt>: A GHC bug 7646
--   <a>http://ghc.haskell.org/trac/ghc/ticket/7646</a> can cause a race
--   condition in build systems that write files then read them. Omitting
--   <tt>-threaded</tt> will still allow your <a>cmd</a> actions to run in
--   parallel, so most build systems will still run in parallel.</li>
--   <li>With GHC 7.8 and later you may add <tt>-threaded</tt>, and pass
--   the options <tt>-qg -qb</tt> to <tt>-with-rtsopts</tt> to disable
--   parallel garbage collection. Parallel garbage collection in Shake
--   programs typically goes slower than sequential garbage collection,
--   while occupying many cores that could be used for running system
--   commands.</li>
--   </ul>
--   
--   <i>Acknowledgements</i>: Thanks to Austin Seipp for properly
--   integrating the profiling code.
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. All arguments 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 :: 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 () -> Rules ()

-- | 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.
alternatives :: Rules () -> Rules ()

-- | Change the priority of a given set of rules, where higher priorities
--   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.
priority :: Double -> Rules () -> Rules ()

-- | 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
--   <a>rule</a> and <a>action</a>. The <a>Action</a> monad tracks the
--   dependencies of a <a>Rule</a>.
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>. The trace list is used for profile
--   reports (see <a>shakeReport</a>).
traced :: String -> IO a -> Action a

-- | Lift a computation from the <a>IO</a> monad.
liftIO :: MonadIO m => forall a. IO a -> m a

-- | If an exception is raised by the <a>Action</a>, perform some
--   <a>IO</a>.
actionOnException :: Action a -> IO b -> Action a

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

-- | 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 occured.
[shakeExceptionTarget] :: ShakeException -> String

-- | The stack of targets, where the <a>shakeExceptionTarget</a> is last.
[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>Function</a>, because <a>Data</a> cannot be defined
--   for functions.
data ShakeOptions
ShakeOptions :: FilePath -> Int -> String -> Verbosity -> Bool -> [FilePath] -> Maybe Lint -> Maybe Double -> Maybe Assume -> [(String, String)] -> Bool -> Bool -> Bool -> Bool -> Change -> Bool -> [FilePath] -> Bool -> (IO Progress -> IO ()) -> (Verbosity -> String -> IO ()) -> 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.
[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>Normal</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

-- | 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 Double

-- | Defaults to <a>Nothing</a>. Assume all build objects are clean/dirty,
--   see <a>Assume</a> for details. Can be used to implement <tt>make
--   --touch</tt>.
[shakeAssume] :: ShakeOptions -> Maybe Assume

-- | 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 '[]'. 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 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,
--   <a>progressSimple</a> 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 ()

-- | The current assumptions made by the build system, used by
--   <a>shakeAssume</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 Assume

-- | Assume that all rules reached are dirty and require rebuilding,
--   equivalent to <a>storedValue</a> always returning <a>Nothing</a>.
--   Useful to undo the results of <a>AssumeClean</a>, for benchmarking
--   rebuild speed and for rebuilding if untracked dependencies have
--   changed. This assumption is safe, but may cause more rebuilding than
--   necessary.
AssumeDirty :: Assume

-- | <i>This assumption is unsafe, and may lead to incorrect build results
--   in this run, and in future runs</i>. Assume and record that all rules
--   reached are clean and do not require rebuilding, provided the rule has
--   a <a>storedValue</a> and has been built before. Useful if you have
--   modified a file in some inconsequential way, such as only the comments
--   or whitespace, and wish to avoid a rebuild.
AssumeClean :: Assume

-- | <i>This assumption is unsafe, and may lead to incorrect build results
--   in this run</i>. Assume that all rules reached are clean in this run.
--   Only useful for benchmarking, to remove any overhead from running
--   <a>storedValue</a> operations.
AssumeSkip :: Assume

-- | 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 run by
--   <tt>command</tt> or <tt>cmd</tt>, using <tt>tracker.exe</tt> as
--   supplied with the Microsoft .NET 4.5 SDK (Windows only). Also performs
--   all checks from <a>LintBasic</a>. Note that some programs are not
--   tracked properly, particularly cygwin programs (it seems).
LintTracker :: Lint

-- | How should you determine if a file has changed, used by
--   <a>shakeChange</a>. The most common values are <a>ChangeModtime</a>
--   (very fast, <tt>touch</tt> causes files to rebuild) and
--   <a>ChangeModtimeAndDigestInput</a> (a bit slower, <tt>touch</tt> 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.
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 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

-- | 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 overriden by command line flags. This argument is
--   usually <a>shakeOptions</a>, perhaps with a few fields overriden.</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>.</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; return $ Just $ do
--        if null targets then <a>want</a> ["result.exe"] else <a>want</a> targets
--        let compiler = if DistCC `elem` flags then "distcc" else "gcc"
--        "*.o" <a>%&gt;</a> \out -&gt; do
--            <a>need</a> ...
--            <tt>cmd</tt> compiler ...
--        ...
--    
--   </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 ()

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

-- | Information about the current state of the build, obtained by passing
--   a callback function to <a>shakeProgress</a>. Typically a program will
--   use <a>progressDisplay</a> to poll this value and produce status
--   messages, which is implemented using this data type.
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 ())

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

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

-- | Only print essential messages, typically errors.
Quiet :: Verbosity

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

-- | Print errors and full command lines when running a <a>command</a> or
--   <a>cmd</a> command.
Loud :: Verbosity

-- | Print errors, full command line and status messages when starting a
--   rule.
Chatty :: 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>putLoud</a> / <a>putNormal</a>
--   / <a>putQuiet</a>, which ensures multiple messages are not
--   interleaved. The verbosity can be modified locally by
--   <a>withVerbosity</a>.
getVerbosity :: Action Verbosity

-- | Write a message to the output when the verbosity
--   (<a>shakeVerbosity</a>) is appropriate. The output will not be
--   interleaved with any other Shake messages (other than those generated
--   by system commands).
putLoud :: String -> Action ()

-- | Write a message to the output when the verbosity
--   (<a>shakeVerbosity</a>) is appropriate. The output will not be
--   interleaved with any other Shake messages (other than those generated
--   by system commands).
putNormal :: String -> Action ()

-- | Write a message to the output when the verbosity
--   (<a>shakeVerbosity</a>) is appropriate. The output will not be
--   interleaved with any other Shake messages (other than those generated
--   by system commands).
putQuiet :: 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>Quiet</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 :: 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_ :: [CmdOption] -> String -> [String] -> Action ()

-- | Execute a system command. Before running <a>cmd</a> make sure you
--   <a>need</a> any files that are used by the command.
--   
--   <ul>
--   <li><tt>String</tt> arguments are treated as whitespace separated
--   arguments.</li>
--   <li><tt>[String]</tt> arguments are treated as literal arguments.</li>
--   <li><a>CmdOption</a> arguments are used as options.</li>
--   </ul>
--   
--   As some examples, here are some calls, and the resulting command
--   string:
--   
--   <pre>
--   <a>unit</a> $ <a>cmd</a> "git log --pretty=" "oneline"           -- git log --pretty= oneline
--   <a>unit</a> $ <a>cmd</a> "git log --pretty=" ["oneline"]         -- git log --pretty= oneline
--   <a>unit</a> $ <a>cmd</a> "git log" ("--pretty=" ++ "oneline")    -- git log --pretty=oneline
--   <a>unit</a> $ <a>cmd</a> "git log" ("--pretty=" ++ "one line")   -- git log --pretty=one line
--   <a>unit</a> $ <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>
--   () &lt;- <a>cmd</a> "gcc -c myfile.c"                                  -- compile a file, throwing an exception on failure
--   <a>unit</a> $ <a>cmd</a> "gcc -c myfile.c"                                 -- alternative to () &lt;- binding.
--   <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
--   </pre>
--   
--   When passing file arguments we use <tt>[myfile]</tt> so that if the
--   <tt>myfile</tt> variable contains spaces they are properly escaped.
--   
--   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, bind the result to <tt>()</tt>,
--   or include a type signature, or use the <a>unit</a> function.
--   
--   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 :: CmdArguments args => args :-> Action r

-- | The identity function which requires the inner argument to be
--   <tt>()</tt>. Useful for functions with overloaded return types.
--   
--   <pre>
--   \(x :: Maybe ()) -&gt; unit x == x
--   </pre>
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>.
newtype Stdout a
Stdout :: a -> Stdout a
[fromStdout] :: Stdout 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 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"
--       return 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

-- | 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
class CmdString a

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

-- | Change the current directory in the spawned process. By default uses
--   this processes current directory.
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

-- | 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. By default the
--   <tt>stdin</tt> is inherited.
Stdin :: String -> CmdOption

-- | Given as the <tt>stdin</tt> of the spawned process.
StdinBS :: ByteString -> 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 <a>traced</a>, 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 <a>interruptProcessGroupOf</a> and <a>terminateProcess</a>, 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
--   <a>Stdout</a> 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
--   <a>Stderr</a> 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

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

-- | <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.
copyFile' :: FilePath -> FilePath -> Action ()

-- | <tt>copyFile' 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.
copyFileChanged :: FilePath -> FilePath -> Action ()

-- | Read a file, after calling <a>need</a>. The argument file will be
--   tracked as a dependency.
readFile' :: 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 :: FilePath -> Action [String]

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

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

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

-- | Remove all files and directories that match any of the patterns within
--   a directory. Some examples:
--   
--   <pre>
--   <a>removeFiles</a> "output" ["//*"]
--   <a>removeFiles</a> "." ["//*.hi","//*.o"]
--   </pre>
--   
--   Any directories that become empty after deleting items from within
--   them will themselves be deleted, up to (and including) the containing
--   directory. 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. Useful for implementing <tt>clean</tt> actions
--   that delete files Shake may have open for building.
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.
withTempDir :: (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>.
need :: [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 :: [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.
(%>) :: FilePattern -> (FilePath -> Action ()) -> Rules ()

-- | 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>.
(|%>) :: [FilePattern] -> (FilePath -> Action ()) -> Rules ()

-- | 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.
(?>) :: (FilePath -> Bool) -> (FilePath -> Action ()) -> Rules ()

-- | Declare a phony action -- an action that does not produce a file, and
--   will be rerun in every execution that requires it. You can demand
--   <a>phony</a> rules using <a>want</a> / <a>need</a>. Phony actions are
--   never executed more than once in a single build run.
--   
--   Phony actions are intended to define command-line abbreviations. 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.
phony :: String -> Action () -> Rules ()

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

-- | A predicate version of <a>phony</a>, return <a>Just</a> with the
--   <a>Action</a> for the matching rules.
phonys :: (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. Think of it as the OR (<tt>||</tt>)
--   equivalent of <a>%&gt;</a>.
(&%>) :: [FilePattern] -> ([FilePath] -> Action ()) -> Rules ()

-- | 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>
--   
--   As an example of a function satisfying the invariaint:
--   
--   <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>.
(&?>) :: (FilePath -> Maybe [FilePath]) -> ([FilePath] -> Action ()) -> Rules ()

-- | 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"]
--       () &lt;- <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,
--   and you will have lost some opportunity for parallelism.
orderOnly :: [FilePath] -> Action ()

-- | 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 only
--   two 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.</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 in the current
--   directory or its subdirectories, so <tt>file.c</tt>,
--   <tt>dir/file.c</tt> and <tt>dir1/dir2/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

-- | 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 :: [FilePath] -> Action ()

-- | Track that a file was read by the action preceeding 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>LintTracker</a> mode.
trackRead :: [FilePath] -> Action ()

-- | Track that a file was written by the action preceeding 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>LintTracker</a>
--   mode.
trackWrite :: [FilePath] -> Action ()

-- | Allow accessing a file in this rule, ignoring any
--   'trackRead'\/'trackWrite' 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.
--   
--   You should not call <a>doesFileExist</a> on files which can be created
--   by the build system.
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.
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 is tracked as a dependency, and if it changes the
--   rule will rerun in subsequent builds.
--   
--   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 <a>FilePath</a> argument. The result
--   is tracked as a dependency, and if it changes the rule will rerun in
--   subsequent builds. 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 <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>
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 is tracked as a dependency, and if it changes the rule will
--   rerun in subsequent builds.
--   
--   <pre>
--   getDirectoryDirs "/Users"
--      -- Return all directories in the /Users directory
--      -- e.g. ["Emily","Henry","Neil"]
--   </pre>
getDirectoryDirs :: FilePath -> Action [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.
getEnv :: String -> Action (Maybe String)

-- | Return the value of the environment variable, or the default value if
--   it not set. Similar to <a>getEnv</a>.
getEnvWithDefault :: String -> String -> Action String

-- | 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)
--   rules = do
--       <a>addOracle</a> $ \(GhcVersion _) -&gt; fmap <a>fromStdout</a> $ <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>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, but if their value does not change they will not
--   invalidate any rules depending on them. To get a similar behaviour
--   using data stored in files, see <a>alwaysRerun</a>.</li>
--   <li>If the value returned by <a>askOracle</a> is ignored then
--   <a>askOracleWith</a> may help avoid ambiguous type messages.
--   Alternatively, use the result of <a>addOracle</a>, which is
--   <a>askOracle</a> restricted to the correct type.</li>
--   </ul>
--   
--   As a more complex example, consider tracking Haskell package versions:
--   
--   <pre>
--   newtype GhcPkgList = GhcPkgList () deriving (Show,Typeable,Eq,Hashable,Binary,NFData)
--   newtype GhcPkgVersion = GhcPkgVersion String deriving (Show,Typeable,Eq,Hashable,Binary,NFData)
--   
--   rules = do
--       getPkgList &lt;- <a>addOracle</a> $ \GhcPkgList{} -&gt; do
--           Stdout out &lt;- <a>cmd</a> "ghc-pkg list --simple-output"
--           return [(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 ()
--           return $ 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.
addOracle :: (ShakeValue q, ShakeValue a) => (q -> Action a) -> Rules (q -> Action a)

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

-- | Get information previously added with <a>addOracle</a>. The second
--   argument is not used, but can be useful to fix the answer type,
--   avoiding ambiguous type error messages.
askOracleWith :: (ShakeValue q, ShakeValue a) => q -> a -> 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>
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" ["http://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 $ return ()
--       <a>cmd</a> "wget" ["http://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
--   <a>withResource</a>) then the extra thread may be used by some other
--   action. Only really suitable for calling 'cmd'/'command'.
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. Using the cached result will still
--   result include any dependencies that the action requires. Each call to
--   <a>newCache</a> creates a separate cache that is independent of all
--   other calls to <a>newCache</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
--       return $ 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)

-- | <i>Deprecated:</i> Alias for <a>%&gt;</a>. Note that <tt>*&gt;</tt>
--   clashes with a Prelude operator in GHC 7.10.
(*>) :: FilePattern -> (FilePath -> Action ()) -> Rules ()

-- | <i>Deprecated:</i> Alias for <a>|%&gt;</a>.
(|*>) :: [FilePattern] -> (FilePath -> Action ()) -> Rules ()

-- | <i>Deprecated:</i> Alias for <a>&amp;%&gt;</a>.
(&*>) :: [FilePattern] -> ([FilePath] -> Action ()) -> Rules ()

-- | <i>Deprecated:</i> Alias for <a>|%&gt;</a>.
(**>) :: [FilePattern] -> (FilePath -> Action ()) -> Rules ()

-- | <i>Deprecated:</i> Alias for <a>&amp;%&gt;</a>.
(*>>) :: [FilePattern] -> ([FilePath] -> Action ()) -> Rules ()

-- | <i>Deprecated:</i> Alias for <a>&amp;?&gt;</a>.
(?>>) :: (FilePath -> Maybe [FilePath]) -> ([FilePath] -> Action ()) -> Rules ()

-- | <i>Deprecated:</i> Please use <tt>command</tt> or <tt>cmd</tt>
--   instead. This function will be removed in a future version.
--   
--   Execute a system command. This function will raise an error if the
--   exit code is non-zero. Before running <a>system'</a> make sure you
--   <a>need</a> any required files.

-- | <i>Deprecated: Use <tt>command</tt> or <tt>cmd</tt></i>
system' :: FilePath -> [String] -> Action ()

-- | <i>Deprecated:</i> Please use <tt>command</tt> or <tt>cmd</tt>
--   instead, with <tt>Cwd</tt>. This function will be removed in a future
--   version.
--   
--   Execute a system command with a specified current working directory
--   (first argument). This function will raise an error if the exit code
--   is non-zero. Before running <a>systemCwd</a> make sure you <a>need</a>
--   any required files.
--   
--   <pre>
--   <a>systemCwd</a> "/usr/MyDirectory" "pwd" []
--   </pre>

-- | <i>Deprecated: Use <tt>command</tt> or <tt>cmd</tt> with
--   <tt>Cwd</tt></i>
systemCwd :: FilePath -> FilePath -> [String] -> Action ()

-- | <i>Deprecated:</i> Please use <tt>command</tt> or <tt>cmd</tt>
--   instead, with <tt>Stdout</tt> or <tt>Stderr</tt>. This function will
--   be removed in a future version.
--   
--   Execute a system command, returning <tt>(stdout,stderr)</tt>. This
--   function will raise an error if the exit code is non-zero. Before
--   running <a>systemOutput</a> make sure you <a>need</a> any required
--   files.

-- | <i>Deprecated: Use <tt>command</tt> or <tt>cmd</tt> with
--   <tt>Stdout</tt> or <tt>Stderr</tt></i>
systemOutput :: FilePath -> [String] -> Action (String, String)


-- | 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>http://martine.github.io/ninja/manual.html#_lexical_syntax</a>.
--   
--   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>http://martine.github.io/ninja/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>http://martine.github.io/ninja/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.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
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


-- | 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; return $ 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 ()
