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.
- class (ShakeValue key, ShakeValue value) => Rule key value where
- data EqualCost
- rule :: Rule key value => (key -> Maybe (Action value)) -> Rules ()
- apply :: Rule key value => [key] -> Action [value]
- apply1 :: Rule key value => key -> Action value
- trackUse :: ShakeValue key => key -> Action ()
- trackChange :: ShakeValue key => key -> Action ()
- trackAllow :: ShakeValue key => (key -> Bool) -> Action ()
- defaultRule :: Rule key value => (key -> Maybe (Action value)) -> Rules ()
Define a pair of types that can be used by Shake rules. To import all the type classes required see Development.Shake.Classes.
Rule instance for a class of artifacts (e.g. files) provides:
- How to identify individual artifacts, given by the
keytype, e.g. with file names.
- How to describe the state of an artifact, given by the
valuetype, e.g. the file modification time.
- A way to compare two states of the same individual artifact, with
- A way to query the current state of an artifact, with
storedValuereturning the current state, or
Nothingif there is no current state (e.g. the file does not exist).
Checking if an artifact needs to be built consists of comparing two
of the same
equalValue. The first value is obtained by applying
storedValue to the
key and the second is the value stored in the build
database after the last successful build.
As an example, below is a simplified rule for building files, where files are identified
FilePath and their state is identified by a hash of their contents
(the builtin functions
provide a similar rule).
newtype File = File FilePath deriving (Show, Typeable, Eq, Hashable, Binary, NFData) newtype Modtime = Modtime Double deriving (Show, Typeable, Eq, Hashable, Binary, NFData) getFileModtime file = ... instance Rule File Modtime where storedValue _ (File x) = do exists <- System.Directory.doesFileExist x if exists then Just <$> getFileModtime x else return Nothing equalValue _ _ t1 t2 = if t1 == t2 then EqualCheap else NotEqual
This example instance means:
- A value of type
Fileuniquely identifies a generated file.
- A value of type
Modtimewill be used to check if a file is up-to-date.
It is important to distinguish
Rule instances from actual rules.
instances are one component required for the creation of rules.
Actual rules are functions from a
key to an
Action; they are
Rules using the
A rule can be created for the instance above with:
-- Compile foo files; for every foo output file there must be a -- single input file named "filename.foo". compileFoo ::
Rules() compileFoo =
rule(Just . compile) where compile :: File ->
ActionModtime compile (File outputFile) = do -- figure out the name of the input file let inputFile = outputFile
cmd"fooCC" inputFile outputFile -- return the (new) file modtime of the output file: getFileModtime outputFile
Note: In this example, the timestamps of the input files are never
used, let alone compared to the timestamps of the ouput files.
Dependencies between output and input files are not expressed by
Rule instances. Dependencies are created automatically by
[Required] Retrieve the
value associated with a
key, if available.
[Optional] Equality check, with a notion of how expensive the check was.
An equality check and a cost.
The equality check was cheap.
The equality check was expensive, as the results are not trivially equal.
The values are not equal.
Track that a key has been used by the action preceeding it.
Track that a key has been changed by the action preceeding it.
Allow any matching key to violate the tracking rules.