-- 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>https://github.com/ndmitchell/shake</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.11.4


-- | 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.
--   
--   Minimal complete definition: <a>showsPrec</a> or <a>show</a>.
--   
--   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
showsPrec :: Show a => Int -> a -> ShowS
show :: Show a => a -> String
showList :: Show a => [a] -> ShowS

-- | The class <a>Typeable</a> allows a concrete representation of a type
--   to be calculated.
class Typeable a
typeOf :: Typeable a => a -> TypeRep

-- | 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>hash</a> or <a>hashWithSalt</a>.
class Hashable a
hash :: Hashable a => a -> Int
hashWithSalt :: Hashable a => Int -> a -> Int

-- | The <tt>Binary</tt> class provides <a>put</a> and <a>get</a>, methods
--   to encode and decode a Haskell value to a lazy ByteString. It mirrors
--   the Read and Show classes for textual representation of Haskell types,
--   and is suitable for serialising Haskell values to disk, over the
--   network.
--   
--   For parsing 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 Put and Get 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
put :: Binary t => t -> Put
get :: Binary t => Get t

-- | A class of types that can be fully evaluated.
class NFData a
rnf :: NFData a => a -> ()


-- | A module for <a>FilePath</a> operations, to be used instead of
--   <a>System.FilePath</a> when writing build systems. In build systems,
--   when using the file name as a key for indexing rules, it is important
--   that two different strings do not refer to the same on-disk file. We
--   therefore follow the conventions:
--   
--   <ul>
--   <li>Always use <tt>/</tt> as the directory separator, even on
--   Windows.</li>
--   <li>When combining <a>FilePath</a> values with <a>&lt;/&gt;</a> we
--   squash any <tt>/./</tt> components.</li>
--   </ul>
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> *
--   <tt>foo/bar/../baz</tt> becomes <tt>foo/baz</tt> * <tt>foo/./bar</tt>
--   becomes <tt>foo/bar</tt> * <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.
normalise :: FilePath -> FilePath

-- | Remove the current extension and add another, an alias for
--   <a>replaceExtension</a>.
(-<.>) :: FilePath -> String -> FilePath

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

-- | Combine two file paths, an alias for <a>combine</a>.
(</>) :: FilePath -> FilePath -> FilePath

-- | Combine two file paths. Any leading <tt>./</tt> or <tt>../</tt>
--   components in the right file are eliminated.
--   
--   <pre>
--   combine "aaa/bbb" "ccc" == "aaa/bbb/ccc"
--   combine "aaa/bbb" "./ccc" == "aaa/bbb/ccc"
--   combine "aaa/bbb" "../ccc" == "aaa/ccc"
--   </pre>
combine :: FilePath -> FilePath -> FilePath

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


-- | <i>Deprecated:</i> This module should no longer be imported as all the
--   functions are available directly from <a>Development.Shake</a>. In
--   future versions this module will be removed.
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>.
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>
--   
--   To take the examples from <a>command</a>:
--   
--   <pre>
--   () &lt;- <a>cmd</a> "gcc -c myfile.c"                                  -- compile a file, throwing an exception on failure
--   <a>Exit</a> c &lt;- <a>cmd</a> "gcc -c" [myfile]                              -- run a command, recording the exit code
--   (<a>Exit</a> c, <a>Stderr</a> err) &lt;- <a>cmd</a> "gcc -c myfile.c"                -- run a command, recording the exit code and error output
--   <a>Stdout</a> out &lt;- <a>cmd</a> "gcc -MM myfile.c"                         -- run a command, recording the output
--   <a>cmd</a> (<a>Cwd</a> "generated") "gcc -c" [myfile] :: <a>Action</a> ()         -- run a command in a directory
--   </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.
--   
--   The <a>cmd</a> command can also be run in the <a>IO</a> monad, but
--   then <a>Traced</a> is ignored and command lines are not echoed.
cmd :: CmdArguments args => args :-> Action r

-- | Collect the <tt>stdout</tt> of the process. If you are collecting the
--   <tt>stdout</tt>, it will not be echoed to the terminal, unless you
--   include <a>EchoStdout</a>.
newtype Stdout
Stdout :: String -> Stdout
fromStdout :: Stdout -> String

-- | Collect the <tt>stderr</tt> of the process. If you are collecting the
--   <tt>stderr</tt>, it will not be echoed to the terminal, unless you
--   include <a>EchoStderr</a>.
newtype Stderr
Stderr :: String -> Stderr
fromStderr :: Stderr -> String

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

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

-- | 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. Use <a>addPath</a> to modify the
--   <tt>$PATH</tt> variable, or <a>addEnv</a> to modify other variables.
Env :: [(String, String)] -> CmdOption

-- | Given as the <tt>stdin</tt> of the spawned process. By default no
--   <tt>stdin</tt> is given.
Stdin :: String -> 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 streams use text 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

-- | 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.
EchoStdout :: Bool -> CmdOption

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

-- | Produce a <a>CmdOption</a> of value <a>Env</a> that is the current
--   environment, plus 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

-- | Produce a <a>CmdOption</a> of value <a>Env</a> that is the current
--   environment, plus the argument environment variables. 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 Eq CmdOption
instance Ord CmdOption
instance Show CmdOption
instance Eq Result
instance Arg [CmdOption]
instance Arg CmdOption
instance Arg [String]
instance Arg String
instance CmdResult r => CmdArguments (IO r)
instance CmdResult r => CmdArguments (Action r)
instance (Arg a, CmdArguments r) => CmdArguments (a -> r)
instance (CmdResult x1, CmdResult x2, CmdResult x3) => CmdResult (x1, x2, x3)
instance (CmdResult x1, CmdResult x2) => CmdResult (x1, x2)
instance CmdResult ()
instance CmdResult Stderr
instance CmdResult Stdout
instance CmdResult ExitCode
instance CmdResult Exit


-- | 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>.
class (ShakeValue key, ShakeValue value) => Rule key value
storedValue :: Rule key value => ShakeOptions -> key -> IO (Maybe value)

-- | Like <a>rule</a>, but lower priority, if no <a>rule</a> exists then
--   <a>defaultRule</a> is checked. All default rules must be disjoint.
defaultRule :: Rule key value => (key -> Maybe (Action value)) -> Rules ()

-- | Add a rule to build a key, returning an appropriate <a>Action</a>. All
--   rules must be disjoint. To define lower priority rules use
--   <a>defaultRule</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> or <a>defaultRule</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 ()


-- | <i>Deprecated: Please use command or cmd instead. This module will be
--   removed in a future version.</i>
--   
--   This module provides versions of the <a>system'</a> family of
--   functions which take a variable number of arguments.
--   
--   All these functions take a variable number of arguments.
--   
--   <ul>
--   <li><tt>String</tt> arguments are treated as whitespace separated
--   arguments.</li>
--   <li><tt>[String]</tt> arguments are treated as literal arguments.</li>
--   </ul>
--   
--   As an example, to run <tt>ghc --make -O2 inputs -o output</tt>:
--   
--   <pre>
--   <a>sys</a> "ghc --make -O2" inputs "-o" [output]
--   </pre>
--   
--   Note that we enclose <tt>output</tt> as a list so that if the output
--   name contains spaces they are appropriately escaped.

-- | <i>Deprecated: Use <tt>command</tt> or <tt>cmd</tt> instead </i>
module Development.Shake.Sys

-- | A variable arity version of <a>system'</a>.
sys :: SysArguments v => String -> v :-> Action ()

-- | A variable arity version of <a>systemCwd</a>.
sysCwd :: SysCwdArguments v => FilePath -> String -> v :-> Action ()

-- | A variable arity version of <a>systemOutput</a>.
sysOutput :: SysOutputArguments v => String -> v :-> Action (String, String)

-- | A variable arity function to accumulate a list of arguments.
args :: ArgsArguments v => v :-> [String]
instance Arg [String]
instance Arg String
instance ArgsArguments [String]
instance (Arg a, ArgsArguments r) => ArgsArguments (a -> r)
instance SysOutputArguments (Action (String, String))
instance (Arg a, SysOutputArguments r) => SysOutputArguments (a -> r)
instance SysCwdArguments (Action ())
instance (Arg a, SysCwdArguments r) => SysCwdArguments (a -> r)
instance SysArguments (Action ())
instance (Arg a, SysArguments r) => SysArguments (a -> r)


-- | This module is used for defining Shake build systems. As a simple
--   example of a Shake build system, let us build the file
--   <tt>result.tar</tt> from the files listed by <tt>result.txt</tt>:
--   
--   <pre>
--   import <a>Development.Shake</a>
--   import <a>Development.Shake.FilePath</a>
--   
--   main = <a>shakeArgs</a> <a>shakeOptions</a> $ do
--       <a>want</a> ["result.tar"]
--       "*.tar" <a>*&gt;</a> \out -&gt; do
--           contents &lt;- <a>readFileLines</a> $ out <a>-&lt;.&gt;</a> "txt"
--           <a>need</a> contents
--           <a>cmd</a> "tar -cf" [out] contents
--   </pre>
--   
--   We start by importing the modules defining both Shake and routines for
--   manipulating <a>FilePath</a> values. We define <tt>main</tt> to call
--   <a>shake</a> with the default <a>shakeOptions</a>. As the second
--   argument to <a>shake</a>, we provide a set of rules. There are two
--   common forms of rules, <a>want</a> to specify target files, and
--   <a>*&gt;</a> to define a rule which builds a <a>FilePattern</a>. We
--   use <a>want</a> to require that after the build completes the file
--   <tt>result.tar</tt> should be ready.
--   
--   The <tt>*.tar</tt> rule describes how to build files with the
--   extension <tt>.tar</tt>, including <tt>result.tar</tt>. We
--   <a>readFileLines</a> on <tt>result.txt</tt>, after changing the
--   <tt>.tar</tt> extension to <tt>.txt</tt>. We read each line into the
--   variable <tt>contents</tt> -- being a list of the files that should go
--   into <tt>result.tar</tt>. Next, we depend (<a>need</a>) all the files
--   in <tt>contents</tt>. If any of these files change, the rule will be
--   repeated. Finally we call the <tt>tar</tt> program. If either
--   <tt>result.txt</tt> changes, or any of the files listed by
--   <tt>result.txt</tt> change, then <tt>result.tar</tt> will be rebuilt.
--   
--   To find out more:
--   
--   <ul>
--   <li>The user manual contains a longer example and background
--   information on how to use Shake
--   <a>https://github.com/ndmitchell/shake/blob/master/docs/Manual.md#readme</a>.</li>
--   <li>The home page has links to additional information
--   <a>https://github.com/ndmitchell/shake#readme</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 -qg -qb"
--   </pre>
--   
--   <ul>
--   <li>Compile without <tt>-threaded</tt>: In GHC 7.6 and earlier 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>Compile with <tt>-rtsopts</tt>: Allow the setting of further GHC
--   options at runtime.</li>
--   <li>Run with <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>Run with <tt>-qg -qb</tt>: Disable parallel garbage collection.
--   Parallel garbage collection in Shake programs typically goes slower
--   than sequential garbage collection, while occupying many cores that
--   can 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>
--   alternatives $ do
--       "hello.txt" *&gt; \out -&gt; writeFile' out "special"
--       "*.txt" *&gt; \out -&gt; writeFile' out "normal"
--   </pre>
alternatives :: 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>=Just "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 -> Maybe FilePath -> Maybe Lint -> Maybe Double -> Maybe Assume -> [(String, String)] -> Bool -> Bool -> Bool -> Bool -> (IO Progress -> IO ()) -> (Verbosity -> String -> IO ()) -> ShakeOptions

-- | Defaults to <tt>.shake</tt>. The prefix of the filename used for
--   storing Shake metadata files. All metadata files will be named
--   <tt><a>shakeFiles</a>.<i>extension</i></tt>, for some
--   <tt><i>extension</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.
shakeThreads :: ShakeOptions -> Int

-- | Defaults to <tt><a>1</a></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 <a>Nothing</a>. Write an HTML 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.
shakeReport :: ShakeOptions -> Maybe 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>.storage</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

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

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

-- | 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> <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>.
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>
--   
--   To take the examples from <a>command</a>:
--   
--   <pre>
--   () &lt;- <a>cmd</a> "gcc -c myfile.c"                                  -- compile a file, throwing an exception on failure
--   <a>Exit</a> c &lt;- <a>cmd</a> "gcc -c" [myfile]                              -- run a command, recording the exit code
--   (<a>Exit</a> c, <a>Stderr</a> err) &lt;- <a>cmd</a> "gcc -c myfile.c"                -- run a command, recording the exit code and error output
--   <a>Stdout</a> out &lt;- <a>cmd</a> "gcc -MM myfile.c"                         -- run a command, recording the output
--   <a>cmd</a> (<a>Cwd</a> "generated") "gcc -c" [myfile] :: <a>Action</a> ()         -- run a command in a directory
--   </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.
--   
--   The <a>cmd</a> command can also be run in the <a>IO</a> monad, but
--   then <a>Traced</a> is ignored and command lines are not echoed.
cmd :: CmdArguments args => args :-> Action r

-- | Collect the <tt>stdout</tt> of the process. If you are collecting the
--   <tt>stdout</tt>, it will not be echoed to the terminal, unless you
--   include <a>EchoStdout</a>.
newtype Stdout
Stdout :: String -> Stdout
fromStdout :: Stdout -> String

-- | Collect the <tt>stderr</tt> of the process. If you are collecting the
--   <tt>stderr</tt>, it will not be echoed to the terminal, unless you
--   include <a>EchoStderr</a>.
newtype Stderr
Stderr :: String -> Stderr
fromStderr :: Stderr -> String

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

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

-- | 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. Use <a>addPath</a> to modify the
--   <tt>$PATH</tt> variable, or <a>addEnv</a> to modify other variables.
Env :: [(String, String)] -> CmdOption

-- | Given as the <tt>stdin</tt> of the spawned process. By default no
--   <tt>stdin</tt> is given.
Stdin :: String -> 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 streams use text 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

-- | 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.
EchoStdout :: Bool -> CmdOption

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

-- | Produce a <a>CmdOption</a> of value <a>Env</a> that is the current
--   environment, plus 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

-- | Produce a <a>CmdOption</a> of value <a>Env</a> that is the current
--   environment, plus the argument environment variables. 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 ()

-- | 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 empty directories and files that match any of the patterns
--   beneath a directory. Some examples:
--   
--   <pre>
--   <a>removeFiles</a> "output" ["//*"]
--   <a>removeFiles</a> "." ["//*.hi","//*.o"]
--   </pre>
--   
--   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 ()

-- | 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>. No file required by
--   the system must be matched by more than one pattern. For the pattern
--   rules, see <a>?==</a>. 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.
(*>) :: FilePattern -> (FilePath -> Action ()) -> Rules ()

-- | Define a set of patterns, and if any of them match, run the associated
--   rule. See <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>
(?>) :: (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 ()

-- | Define a rule for building multiple files at the same time, a more
--   powerful and more dangerous version of <a>*&gt;&gt;</a>.
--   
--   Given an application <tt>test ?&gt;&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 a rule for building multiple files at the same time. As an
--   example, a single invokation of GHC produces both <tt>.hi</tt> and
--   <tt>.o</tt> files:
--   
--   <pre>
--   ["*.o","*.hi"] <a>*&gt;&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.
(*>>) :: [FilePattern] -> ([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>.
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 that match:
--   
--   <pre>
--   "//*.c" <a>?==</a> "foo/bar/baz.c"
--   "*.c" <a>?==</a> "baz.c"
--   "//*.c" <a>?==</a> "baz.c"
--   "test.c" <a>?==</a> "test.c"
--   </pre>
--   
--   Examples that <i>don't</i> match:
--   
--   <pre>
--   "*.c" <a>?==</a> "foo/bar.c"
--   "*/*.c" <a>?==</a> "foo/bar/baz.c"
--   </pre>
--   
--   An example that only matches on Windows:
--   
--   <pre>
--   "foo/bar" <a>?==</a> "foo\\bar"
--   </pre>
(?==) :: FilePattern -> FilePath -> Bool

-- | 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"
--       ... 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>newResource</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.
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> 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.
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>
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.
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)

-- | 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)
instance Typeable Config
instance Show Config
instance Eq Config
instance Hashable Config
instance Binary Config
instance NFData 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 ()
