We start by importing the modules defining both Shake and routines for manipulating FilePath values.
We define main to call shake with the default shakeOptions. As the second argument to
shake, we provide a set of rules. There are two common forms of rules, want to specify target files,
and *> to define a rule which builds a FilePattern. We use want to require that after the build
completes the file result.tar should be ready.

The *.tar rule describes how to build files with the extension .tar, including result.tar.
We readFileLines on result.txt, after changing the .tar extension to .txt. We read each line
into the variable contents -- being a list of the files that should go into result.tar. Next, we
depend (need) all the files in contents. If any of these files change, the rule will be repeated.
Finally we call the tar program. If either result.txt changes, or any of the files listed by result.txt
change, then result.tar will be rebuilt.

When writing a Shake build system, start by defining what you want, then write rules
with *> to produce the results. Before calling cmd you should ensure that any files the command
requires are demanded with calls to need. We offer the following advice to Shake users:

If ghc --make or cabal is capable of building your project, use that instead. Custom build systems are
necessary for many complex projects, but many projects are not complex.

Do not be afraid to mix Shake rules, system commands and other Haskell libraries -- use each for what
it does best.

The more accurate the dependencies are, the better. Use additional rules like doesFileExist and
getDirectoryFiles to track information other than just the contents of files. For information in the environment
that you suspect will change regularly (perhaps ghc version number), either write the information to
a file with alwaysRerun and writeFileChanged, or use addOracle.

== GHC BUILD FLAGS ==============================

For large build systems the choice of GHC flags can have a significant impact. We recommend:

ghc --make MyBuildSystem -rtsopts "-with-rtsopts=-I0 -qg -qb"

Compile without -threaded: In GHC 7.6 and earlier bug 7646 http://ghc.haskell.org/trac/ghc/ticket/7646
can cause a race condition in build systems that write files then read them. Omitting -threaded will
still allow your cmd actions to run in parallel, so most build systems will still run in parallel.

Compile with -rtsopts: Allow the setting of further GHC options at runtime.

Run with -I0: 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.

Run with -qg -qb: 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.

Core

Main entry point for running Shake build systems. For an example see the top of the module Development.Shake.
Use ShakeOptions to specify how the system runs, and Rules to specify what to build. The function will throw
an exception if the build fails.

As an example for filenames/timestamps, if the file exists you should return Just
the timestamp, but otherwise return Nothing. For rules whose values are not
stored externally, storedValue should return Nothing.

Write an action to the trace list, along with the start/end time of running the IO action.
The cmd and command functions automatically call traced.
The trace list is used for profile reports (see shakeReport).

Defaults to 1. 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.

Defaults to False. Perform basic sanity checks during building, checking the current directory
is not modified and that output files are not modified by multiple rules.
These sanity checks do not check for missing or redundant dependencies.

Defaults to Just 10. How often to flush Shake metadata files in seconds, or Nothing to never flush explicitly.
It is possible that on abnormal termination (not Haskell exceptions) any rules that completed in the last
shakeFlush seconds will be lost.

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

Defaults to False. Write a message to shakeFiles.storage whenever a storage event happens which may impact
on the current stored progress. Examples include database version number changes, database compaction or corrupt files.

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, progressSimple is often sufficient, but more advanced
users should look at the Progress data type.

Defaults to writing using putStrLn. A function called to output messages from Shake, along with the Verbosity at
which that message should be printed. This function will be called atomically from all other shakeOutput functions.
The Verbosity will always be greater than or higher than shakeVerbosity.

The current assumptions made by the build system, used by shakeAssume. 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 action commands. Any
other files in the database are left unchanged.

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

This assumption is unsafe, and may lead to incorrect build results in this run, and in future runs.
Assume and record that all rules reached are clean and do not require rebuilding, provided the rule
has a storedValue 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.

This assumption is unsafe, and may lead to incorrect build results in this run.
Assume that all rules reached are clean in this run. Only useful for benchmarking, to remove any overhead
from running storedValue operations.

Command line

Run a build system using command line arguments for configuration.
The available flags are those from shakeOptDescrs, along with a few additional
make compatible flags that are not represented in ShakeOptions, such as --print-directory.
If there are no file arguments then the Rules are used directly, otherwise the file arguments
are wanted (after calling withoutActions). As an example:

A version of shakeArgs with more flexible handling of command line arguments.
The caller of shakeArgsWith can add additional flags (the second argument) and chose how to convert
the flags/arguments into rules (the third argument). Given:

opts is the initial ShakeOptions value, which may have some fields overriden by command line flags.
This argument is usually shakeOptions, perhaps with a few fields overriden.

flags is a list of flag descriptions, which either produce a String containing an error
message (typically for flags with invalid arguments, .e.g. Left "could not parse as int"), or a value
that is passed as flagValues. If you have no custom flags, pass [].

flagValues is a list of custom flags that the user supplied. If flags == [] then this list will
be [].

argValues is a list of non-flag arguments, which are often treated as files and passed to want.

result should produce a Nothing to indicate that no building needs to take place, or a Just
providing the rules that should be used.

As an example of a build system that can use either gcc or distcc for compiling:

A list of command line options that can be used to modify ShakeOptions. Each option returns
either an error message (invalid argument to the flag) or a function that changes some fields
in ShakeOptions. The command line flags are make compatible where possbile, but additional
flags have been added for the extra options Shake supports.

Progress reporting

Information about the current state of the build, obtained by passing a callback function
to shakeProgress. Typically a program will use progressDisplay to poll this value and produce
status messages, which is implemented using this data type.

A simple method for displaying progress messages, suitable for using as shakeProgress.
This function writes the current progress to the titlebar every five seconds using progressTitlebar,
and calls any shake-progress program on the $PATH using progressProgram.

Given a sampling interval (in seconds) and a way to display the status message,
produce a function suitable for using as shakeProgress.
This function polls the progress information every n seconds, produces a status
message and displays it using the display function.

Typical status messages will take the form of 1m25s (15%), 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 timeTodo) and the
work already done (timeBuilt). The percentage is then calculated as remaining / (done + remaining),
while time left is calculated by scaling remaining by the observed work rate in this build,
roughly done / time_elapsed.

Set the title of the current console window to the given text. If the
environment variable $TERM is set to xterm this uses xterm escape sequences.
On Windows, if not detected as an xterm, this function uses the SetConsoleTitle API.

Get the current verbosity level, as set by shakeVerbosity. If you
want to output information to the console, you are recommended to use
putLoud / putNormal / putQuiet, which ensures multiple messages are
not interleaved.

Running commands

Execute a system command. Before running command make sure you need any files
that are required by the command.

This function takes a list of options (often just [], see CmdOption for the available
options), the name of the executable (either a full name, or a program on the $PATH) and
a list of arguments. The result is often (), but can be a tuple containg any of Stdout,
Stderr and Exit. Some examples:

When passing file arguments we use [myfile] so that if the myfile variable contains spaces they are properly escaped.

If you use cmd inside a do block and do not use the result, you may get a compile-time error about being
unable to deduce CmdResult. To avoid this error, bind the result to (), or include a type signature.

Deprecated: Please use command or cmd instead, with Cwd.
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 systemCwd make sure you need any required files.

To define a build system for multiple compiled languages, we recommend using .asm.o,
.cpp.o, .hs.o, to indicate which language produces an object file.
I.e., the file foo.cpp produces object file foo.cpp.o.

Define a rule to build files. If the first argument returns True for a given file,
the second argument will be used to build it. Usually *> is sufficient, but ?> gives
additional power. For any file used by the build system, only one rule should return True.

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 phony rules using want / need.
Phony actions are never executed more than once in a single build run.

Phony actions are intended to define command-line abbreviations. If you need a phony action
in a rule then every execution where that rule is required will rerun both the rule and the phony
action.

Define a rule for building multiple files at the same time, a more powerful
and more dangerous version of *>>.

Given an application test ?>> ..., test should return Just if the rule applies, and should
return the list of files that will be produced. This list must include the file passed as an argument and should
obey the invariant:

However, in practice, it's usually easier to define rules with *> and make the .hi depend
on the .o. When defining rules that build multiple files, all the FilePattern values must
have the same sequence of // and * wildcards in the same order.

Get the files anywhere under a directory that match any of a set of patterns.
For the interpretation of the patterns see ?==. All results will be
relative to the FilePath argument. Some examples:

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

If you require a qualified file name it is often easier to use "" as FilePath argument,
for example the following two expressions are equivalent:

Oracle rules

Add extra information which rules can depend on.
An oracle is a function from a question type q, to an answer type a.
As an example, we can define an oracle allowing you to depend on the current version of GHC:

Actions passed to addOracle 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 alwaysRerun.

newThrottle creates a throttled resource, stopping too many actions running
over a short time period.

These resources are used with withResource when defining rules. Typically only
system commands (such as cmd) should be run inside withResource,
not commands such as need.

Be careful that the actions run within withResource 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 withResources to avoid deadlock.

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:

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:

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 withResources, resources will not deadlock.

Create a throttled resource, given a name (for error messages) and a number of resources (the Int) that can be
used per time period (the Double 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:

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 newThrottle "Google" 12 60, 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 completed. If we instead
want to throttle requests since the previous request started we can write:

However, the rule may not continue running immediately after withResource 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.

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 shakeThreads limit to be exceeded.
You cannot call apply / need while the extra thread is executing.

Cached file contents

Given a way of loading information from a file, produce a cached version that will load each file at most once.
Using the cached function will still result in a dependency on the original file.
The argument function should not access any files other than the one passed as its argument.
Each call to newCache creates a separate cache that is independent of all other calls to newCache.

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: