Development.Shake.Database

Lower-level primitives to drive Shake, which are wrapped into the shake function. Useful if you want to perform multiple Shake runs in a row without reloading from the database. Sometimes used in conjunction with shakeFiles="/dev/null". Using these functions you can approximate the shake experience with:

shake opts rules = do
    (_, after) <- shakeWithDatabase opts rules $ \db -> do
        shakeOneShotDatabase db
        shakeRunDatabase db []
    shakeRunAfter opts after

Documentation

data ShakeDatabase

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

shakeOpenDatabase :: ShakeOptions -> Rules () -> IO (IO ShakeDatabase, IO ())

Given some options and rules, return a pair. The first component opens the database, the second cleans it up. The creation does not need to be run masked, because the cleanup is able to run at any point. Most users should prefer shakeWithDatabase which handles exceptions duration creation properly.

shakeWithDatabase :: ShakeOptions -> Rules () -> (ShakeDatabase -> IO a) -> IO a

Given some options and rules, create a ShakeDatabase that can be used to run executions.

shakeOneShotDatabase :: ShakeDatabase -> IO ()

Declare that a just-openned database will be used to call shakeRunDatabase at most once. If so, an optimisation can be applied to retain less memory.

shakeRunDatabase :: ShakeDatabase -> [Action a] -> IO ([a], [IO ()])

Given an open ShakeDatabase, run both whatever actions were added to the Rules, plus the list of Action given here. Returns the results from the explicitly passed actions along with a list of actions to run after the database was closed, as added with runAfter and removeFilesAfter.

shakeLiveFilesDatabase :: ShakeDatabase -> IO [FilePath]

Given a ShakeDatabase, what files did the execution ensure were up-to-date in the previous call to shakeRunDatabase. Corresponds to the list of files written out to shakeLiveFiles.

shakeProfileDatabase :: ShakeDatabase -> FilePath -> IO ()

Given a ShakeDatabase, generate profile information to the given file about the latest run. See shakeReport for the types of file that can be generated.

shakeErrorsDatabase :: ShakeDatabase -> IO [(String, SomeException)]

Given a ShakeDatabase, what files did the execution reach an error on last time. Some special considerations when using this function:

• The presence of an error does not mean the build will fail, specifically if a previously required dependency was run and raised an error, then the thing that previously required it will be run. If the build system has changed in an untracked manner, the build may succeed this time round.
• If the previous run actually failed then shakeRunDatabase will have thrown an exception. You probably want to catch that exception so you can make the call to shakeErrorsDatabase.
• You may see a single failure reported multiple times, with increasingly large call stacks, showing the ways in which the error lead to further errors throughout.
• The SomeException values are highly likely to be of type ShakeException.
• If you want as many errors as possile in one run set shakeStaunch=True.

shakeRunAfter :: ShakeOptions -> [IO ()] -> IO ()

Run a set of IO actions, treated as "after" actions, typically returned from shakeRunDatabase. The actions will be run with diagnostics etc as specified in the ShakeOptions.