shake-0.19.8: Build system library, like Make, but more accurate dependencies.

Safe Haskell | None
Language | Haskell2010

Development.Shake.Database

Description

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

Synopsis

- data ShakeDatabase
- shakeOpenDatabase :: ShakeOptions -> Rules () -> IO (IO ShakeDatabase, IO ())
- shakeWithDatabase :: ShakeOptions -> Rules () -> (ShakeDatabase -> IO a) -> IO a
- shakeOneShotDatabase :: ShakeDatabase -> IO ()
- shakeRunDatabase :: ShakeDatabase -> [Action a] -> IO ([a], [IO ()])
- shakeLiveFilesDatabase :: ShakeDatabase -> IO [FilePath]
- shakeProfileDatabase :: ShakeDatabase -> FilePath -> IO ()
- shakeErrorsDatabase :: ShakeDatabase -> IO [(String, SomeException)]
- shakeRunAfter :: ShakeOptions -> [IO ()] -> IO ()

# 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 possible 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`.