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.

To use command line flags to modify ShakeOptions see shakeArgs.

The default set of ShakeOptions.

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

Run an action, usually used for specifying top-level requirements.

main = shake shakeOptions $ do
   action $ do
       b <- doesFileExist "file.src"
       when b $ need ["file.out"]

This action builds file.out, but only if file.src exists. The action will be run in every build execution (unless withoutActions is used), so only cheap operations should be performed. On the flip side, consulting system information (e.g. environment variables) can be done directly as the information will not be cached. All calls to action may be run in parallel, in any order.

For the standard requirement of only needing a fixed list of files in the action, see want.

Remove all actions specified in a set of rules, usually used for implementing command line specification of what to build.

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.

alternatives $ do
    "hello.*" %> \out -> writeFile' out "hello.*"
    "*.txt" %> \out -> writeFile' out "*.txt"

In this example hello.txt will match the first rule, instead of raising an error about ambiguity. Inside alternatives the priority of each rule is not used to determine which rule matches, but the resulting match uses that priority compared to the rules outside the alternatives block.

Change the priority of a given set of rules, where higher values take precedence. All matching rules at a given priority must be disjoint, or an error is raised. All builtin Shake rules have priority between 0 and 1. Excessive use of priority is discouraged. As an example:

priority 4 $ "hello.*" %> \out -> writeFile' out "hello.*"
priority 8 $ "*.txt" %> \out -> writeFile' out "*.txt"

In this example hello.txt will match the second rule, instead of raising an error about ambiguity.

The priority function obeys the invariants:

priority p1 (priority p2 r1) === priority p1 r1
priority p1 (r1 >> r2) === priority p1 r1 >> priority p1 r2

Indicate that the nested rules have a given version. If you change the semantics of the rule then updating (or adding) a version will cause the rule to rebuild in some circumstances.

versioned 1 $ "hello.*" %> \out ->
    writeFile' out "Writes v1 now" -- previously wrote out v0

You should only use versioned to track changes in the build source, for standard runtime dependencies you should use other mechanisms, e.g. addOracle.

The Action monad, use liftIO to raise IO actions into it, and need to execute files. Action values are used by addUserRule and action. The Action monad tracks the dependencies of a rule. To raise an exception call error, fail or liftIO . throwIO.

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 with the name of the executable. The trace list is used for profile reports (see shakeReport).

By default traced prints some useful extra context about what Shake is building, e.g.:

# traced message (for myobject.o)

To suppress the output of traced (for example you want more control over the message using putInfo), use the quietly combinator.

It is recommended that the string passed to traced is short and that only a small number of unique strings are used (makes profiling work better). The string does not need to make sense on its own, only in conjunction with the target it is building.

Lift a computation from the IO monad.

If an exception is raised by the Action, perform some IO then reraise the exception.

After an Action, perform some IO, even if there is an exception.

Like bracket, but where the inner operation is of type Action. Usually used as actionBracket alloc free use.

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

Retry an Action if it throws an exception, at most n times (where n must be positive). If you need to call this function, you should probably try and fix the underlying cause (but you also probably know that).

Specify an action to be run after the database has been closed, if building completes successfully.

Error representing all expected exceptions thrown by Shake. Problems when executing rules will be raising using this exception type.

Options to control the execution of Shake, usually specified by overriding fields in shakeOptions:

 shakeOptions{shakeThreads=4, shakeReport=["report.html"]}

The Data instance for this type reports the shakeProgress and shakeOutput fields as having the abstract type Hidden, because Data cannot be defined for functions or TypeReps.

The current assumptions made by the build system, used by shakeRebuild. 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.

Which lint checks to perform, used by shakeLint.

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

Get the initial ShakeOptions, these will not change during the build process.

Get the ShakeOptions that were used.

Get a checksum of a list of files, suitable for using as shakeVersion. This will trigger a rebuild when the Shake rules defined in any of the files are changed. For example:

main = do
    ver <- getHashedShakeVersion ["Shakefile.hs"]
    shakeArgs shakeOptions{shakeVersion = ver} ...

To automatically detect the name of the current file, turn on the TemplateHaskell extension and write $(LitE . StringL . loc_filename <$> location).

This feature can be turned off during development by passing the flag --no-rule-version or setting shakeVersionIgnore to True.

Get an item from shakeExtra, using the requested type as the key. Fails if the value found at this key does not match the requested type.

A version of getShakeExtra in Rules.

Add a properly structued value to shakeExtra which can be retrieved with getShakeExtra.

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:

main = shakeArgs shakeOptions{shakeFiles = "_make", shakeProgress = progressSimple} $ do
    phony "clean" $ removeFilesAfter "_make" ["//*"]
    want ["_make/neil.txt","_make/emily.txt"]
    "_make/*.txt" %> \out ->
        ... build action here ...

This build system will default to building neil.txt and emily.txt, while showing progress messages, and putting the Shake files in locations such as _make/.database. Some example command line flags:

• main --no-progress will turn off progress messages.
• main -j6 will build on 6 threads.
• main --help will display a list of supported flags.
• main clean will not build anything, but will remove the _make directory, including the any shakeFiles.
• main _make/henry.txt will not build neil.txt or emily.txt, but will instead build henry.txt.

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:

shakeArgsWith opts flags (\flagValues argValues -> result)

• 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. If arguments are specified then typically the want calls from the rules are discarded using withoutActions.
• 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:

import System.Console.GetOpt

data Flags = DistCC deriving Eq
flags = [Option "" ["distcc"] (NoArg $ Right DistCC) "Run distributed."]

main = shakeArgsWith shakeOptions flags $ \flags targets -> pure $ Just $ do
    let compiler = if DistCC `elem` flags then "distcc" else "gcc"
    let rules = do
        "*.o" %> \out -> do
            need ...
            cmd compiler ...
        want ["target.exe"]
        ...
    if null targets then rules else want targets >> withoutActions rules

Now you can pass --distcc to use the distcc compiler.

Like shakeArgsWith, but also lets you manipulate the ShakeOptions.

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.

Adds some extra information at the end of --help.

Get all targets registered in the given rules. The names in phony and ~> as well as the file patterns in %>, |%> and &%> are registered as targets, plus any explicit calls to addTarget. Returns the command, paired with the documentation (if any).

Register a target, as available when passing --help or through getTargets. Called automatically by rules such as phony and %> - to avoid that use withoutTargets. To add documentation to a target use withTargetDocs.

For all addTarget targets within the Rules provide the specified documentation, if they don't already have documentation.

Remove all targets specified in a set of rules, typically because they are internal details. Overrides addTarget.

Information about the current state of the build, obtained by either passing a callback function to shakeProgress (asynchronous output) or getProgress (synchronous output). Typically a build system will pass progressDisplay to shakeProgress, which will poll this value and produce status messages.

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.

Call the program shake-progress if it is on the $PATH. The program is called with the following arguments:

• --title=string - the string passed to progressProgram.
• --state=Normal, or one of NoProgress, Normal, or Error to indicate what state the progress bar should be in.
• --value=25 - the percent of the build that has completed, if not in NoProgress state.

The program will not be called consecutively with the same --state and --value options.

Windows 7 or higher users can get taskbar progress notifications by placing the following program in their $PATH: https://github.com/ndmitchell/shake/releases.

Get the current Progress structure, as would be returned by shakeProgress.

The verbosity data type, used by shakeVerbosity.

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

Write an unimportant message to the output, only shown when shakeVerbosity is higher than normal (Verbose or above). The output will not be interleaved with any other Shake messages (other than those generated by system commands).

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

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

Write an important message to the output, only suppressed when shakeVerbosity is Silent. The output will not be interleaved with any other Shake messages (other than those generated by system commands).

Run an action with a particular verbosity level. Will not update the shakeVerbosity returned by getShakeOptions and will not have any impact on Diagnostic tracing.

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

Execute a system command. Before running command make sure you need any files that are used 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:

command_ [] "gcc" ["-c","myfile.c"]                          -- compile a file, throwing an exception on failure
Exit c <- command [] "gcc" ["-c",myfile]                     -- run a command, recording the exit code
(Exit c, Stderr err) <- command [] "gcc" ["-c","myfile.c"]   -- run a command, recording the exit code and error output
Stdout out <- command [] "gcc" ["-MM","myfile.c"]            -- run a command, recording the output
command_ [Cwd "generated"] "gcc" ["-c",myfile]               -- run a command in a directory

Unless you retrieve the ExitCode using Exit, any ExitFailure will throw an error, including the Stderr in the exception message. If you capture the Stdout or Stderr, that stream will not be echoed to the console, unless you use the option EchoStdout or EchoStderr.

If you use command 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, use command_.

By default the stderr stream will be captured for use in error messages, and also echoed. To only echo pass WithStderr False, which causes no streams to be captured by Shake, and certain programs (e.g. gcc) to detect they are running in a terminal.

A version of command where you do not require any results, used to avoid errors about being unable to deduce CmdResult.

Build or execute a system command. Before using cmd to run a command, make sure you need any files that are used by the command.

• String arguments are treated as a list of whitespace separated arguments.
• [String] arguments are treated as a list of literal arguments.
• CmdOption arguments are used as options.
• CmdArgument arguments, which can be built by cmd itself, are spliced into the containing command.

Typically only string literals should be passed as String arguments. When using variables prefer [myvar] so that if myvar contains spaces they are properly escaped.

As some examples, here are some calls, and the resulting command string:

cmd_ "git log --pretty=" "oneline"           -- git log --pretty= oneline
cmd_ "git log --pretty=" ["oneline"]         -- git log --pretty= oneline
cmd_ "git log" ("--pretty=" ++ "oneline")    -- git log --pretty=oneline
cmd_ "git log" ("--pretty=" ++ "one line")   -- git log --pretty=one line
cmd_ "git log" ["--pretty=" ++ "one line"]   -- git log "--pretty=one line"

More examples, including return values, see this translation of the examples given for the command function:

cmd_ "gcc -c myfile.c"                                       -- compile a file, throwing an exception on failure
Exit c <- cmd "gcc -c" [myfile]                              -- run a command, recording the exit code
(Exit c, Stderr err) <- cmd "gcc -c myfile.c"                -- run a command, recording the exit code and error output
Stdout out <- cmd "gcc -MM myfile.c"                         -- run a command, recording the output
cmd (Cwd "generated") "gcc -c" [myfile] :: Action ()         -- run a command in a directory

let gccCommand = cmd "gcc -c" :: CmdArgument                 -- build a sub-command. cmd can return CmdArgument values as well as execute commands
cmd (Cwd "generated") gccCommand [myfile]                 -- splice that command into a greater command

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, use cmd_. If you enable OverloadedStrings or OverloadedLists you may have to give type signatures to the arguments, or use the more constrained command instead.

The cmd function can also be run in the IO monad, but then Traced is ignored and command lines are not echoed. As an example:

cmd (Cwd "generated") Shell "gcc -c myfile.c" :: IO ()

See cmd. Same as cmd except with a unit result. cmd is to cmd_ as command is to command_.

The identity function which requires the inner argument to be (). Useful for functions with overloaded return types.

\(x :: Maybe ()) -> unit x == x

Collect the stdout of the process. If used, the stdout will not be echoed to the terminal, unless you include EchoStdout. The value type may be either String, or either lazy or strict ByteString.

Note that most programs end their output with a trailing newline, so calling ghc --numeric-version will result in Stdout of "6.8.3\n". If you want to automatically trim the resulting string, see StdoutTrim.

Like Stdout but remove all leading and trailing whitespaces.

Collect the stderr of the process. If used, the stderr will not be echoed to the terminal, unless you include EchoStderr. The value type may be either String, or either lazy or strict ByteString.

Collect the stdout and stderr of the process. If used, the stderr and stdout will not be echoed to the terminal, unless you include EchoStdout and EchoStderr. The value type may be either String, or either lazy or strict ByteString.

Collect the ExitCode of the process. If you do not collect the exit code, any ExitFailure will cause an exception.

Collect the ProcessHandle of the process. If you do collect the process handle, the command will run asyncronously and the call to cmd / command will return as soon as the process is spawned. Any Stdout / Stderr captures will return empty strings.

Collect the time taken to execute the process. Can be used in conjunction with CmdLine to write helper functions that print out the time of a result.

timer :: (CmdResult r, MonadIO m) => (forall r . CmdResult r => m r) -> m r
timer act = do
    (CmdTime t, CmdLine x, r) <- act
    liftIO $ putStrLn $ "Command " ++ x ++ " took " ++ show t ++ " seconds"
    pure r

run :: IO ()
run = timer $ cmd "ghc --version"

Collect the command line used for the process. This command line will be approximate - suitable for user diagnostics, but not for direct execution.

The results produced by fsatrace. All files will be absolute paths. You can get the results for a cmd by requesting a value of type [FSATrace].

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

The allowable String-like values that can be captured.

Options passed to command or cmd to control how processes are executed.

Deprecated: Use AddPath. This function will be removed in a future version.

Add a prefix and suffix to the $PATH environment variable. For example:

opt <- addPath ["/usr/special"] []
cmd opt "userbinary --version"

Would prepend /usr/special to the current $PATH, and the command would pick /usr/special/userbinary, if it exists. To add other variables see addEnv.

Deprecated: Use AddEnv. This function will be removed in a future version.

Add a single variable to the environment. For example:

opt <- addEnv [("CFLAGS","-O2")]
cmd opt "gcc -c main.c"

Would add the environment variable $CFLAGS with value -O2. If the variable $CFLAGS was already defined it would be overwritten. If you wish to modify $PATH see addPath.

Execute a list of actions in parallel. In most cases need will be more appropriate to benefit from parallelism.

A parallel version of forM.

Execute two operations in parallel, based on parallel.

copyFile' old new copies the existing file from old to new. The old file will be tracked as a dependency. Also creates the new directory if necessary.

copyFileChanged old new copies the existing file from old to new, if the contents have changed. The old file will be tracked as a dependency. Also creates the new directory if necessary.

Read a file, after calling need. The argument file will be tracked as a dependency.

A version of readFile' which also splits the result into lines. The argument file will be tracked as a dependency.

Write a file, lifted to the Action monad.

A version of writeFile' which writes out a list of lines.

Write a file, but only if the contents would change.

Remove all files and directories that match any of the patterns within a directory. Some examples:

removeFiles "output" ["//*"]        -- delete everything inside 'output'
removeFiles "output" ["//"]         -- delete 'output' itself
removeFiles "." ["//*.hi","//*.o"] -- delete all '.hi' and '.o' files

If the argument directory is missing no error is raised. This function will follow symlinks, so should be used with care.

This function is often useful when writing a clean action for your build system, often as a phony rule.

Remove files, like removeFiles, but executed after the build completes successfully using runAfter. Useful for implementing clean actions that delete files Shake may have open for building, e.g. shakeFiles. Where possible, delete the files as a normal part of the build, e.g. using liftIO $ removeFiles dir pats.

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

Create a temporary directory inside the system temporary directory. The directory will be deleted after the action completes. As an example:

withTempDir $ \mydir -> do
   putInfo $ "Temp directory is " ++ mydir
   writeFile' (mydir </> "test.txt") "writing out a temp file"

Like withTempFile but using a custom temporary directory.

Like withTempDir but using a custom temporary directory.

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 cmd or command. As an example:

"//*.rot13" %> \out -> do
    let src = dropExtension out
    need [src]
    cmd "rot13" [src] "-o" [out]

Usually need [foo,bar] is preferable to need [foo] >> need [bar] as the former allows greater parallelism, while the latter requires foo to finish building before starting to build bar.

This function should not be called with wildcards (e.g. *.txt - use getDirectoryFiles to expand them), environment variables (e.g. $HOME - use getEnv to expand them) or directories (directories cannot be tracked directly - track files within the directory instead).

Require that the argument files are built by the rules, used to specify the target.

main = shake shakeOptions $ do
   want ["Main.exe"]
   ...

This program will build Main.exe, given sufficient rules. All arguments to all want calls may be built in parallel, in any order.

This function is defined in terms of action and need, use action if you need more complex targets than want allows.

Define a rule that matches a FilePattern, see ?== for the pattern rules. Patterns with no wildcards have higher priority than those with wildcards, and no file required by the system may be matched by more than one pattern at the same priority (see priority and alternatives to modify this behaviour). This function will create the directory for the result file, if necessary.

"*.asm.o" %> \out -> do
    let src = dropExtension out
    need [src]
    cmd "as" [src] "-o" [out]

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.

Note that matching is case-sensitive, even on Windows.

If the Action completes successfully the file is considered up-to-date, even if the file has not changed.

Define a set of patterns, and if any of them match, run the associated rule. Defined in terms of %>. Think of it as the OR (||) equivalent of %>.

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. This function will create the directory for the result file, if necessary.

(all isUpper . takeBaseName) ?> \out -> do
    let src = replaceBaseName out $ map toLower $ takeBaseName out
    writeFile' out . map toUpper =<< readFile' src

If the Action completes successfully the file is considered up-to-date, even if the file has not changed.

Declare a Make-style phony action. A phony target does not name a file (despite living in the same namespace as file rules); rather, it names some action to be executed when explicitly requested. You can demand phony rules using want. (And need, although that's not recommended.)

Phony actions are intended to define recipes that can be executed by the user. 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. However, note that phony actions are never executed more than once in a single build run.

In make, the .PHONY attribute on non-file-producing rules has a similar effect. However, while in make it is acceptable to omit the .PHONY attribute as long as you don't create the file in question, a Shake rule which behaves this way will fail lint. For file-producing rules which should be rerun every execution of Shake, see alwaysRerun.

Infix operator alias for phony, for sake of consistency with normal rules.

A predicate version of phony, return Just with the Action for the matching rules.

Define a rule for building multiple files at the same time. Think of it as the AND (&&) equivalent of %>. As an example, a single invocation of GHC produces both .hi and .o files:

["*.o","*.hi"] &%> \[o,hi] -> do
    let hs = o -<.> "hs"
    need ... -- all files the .hs import
    cmd "ghc -c" [hs]

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. This function will create directories for the result files, if necessary.