Safe Haskell	None
Language	Haskell2010

Development.Shake.Rule

Contents

Defining builtin rules
Calling builtin rules
User rules
Lint integration

Description

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.

Synopsis

Defining builtin rules

addBuiltinRule :: (RuleResult key ~ value, ShakeValue key, ShakeValue value) => BuiltinLint key value -> BuiltinRun key value -> Rules () Source #

Add a builtin rule, comprising of a lint rule and an action. Each builtin rule must be identified by a unique key.

type BuiltinLint key value = key -> value -> IO (Maybe String) Source #

The action performed by --lint for a given key/value pair. At the end of the build the lint action will be called for each key that was built this run, passing the value it produced. Return Nothing to indicate the value has not changed and is acceptable, or Just an error message to indicate failure.

For builtin rules where the value is expected to change use noLint.

noLint :: BuiltinLint key value Source #

A suitable BuiltinLint that always succeeds.

type BuiltinRun key value = key -> Maybe ByteString -> Bool -> Action (RunResult value) Source #

Define a rule between key and value. A rule for a class of artifacts (e.g. files) provides:

How to identify individual artifacts, given by the key type, e.g. with file names.
How to describe the state of an artifact, given by the value type, e.g. the file modification time.
How to persist the state of an artifact, using the ByteString values, e.g. seralised value.

The arguments comprise the key, the value of the previous serialisation or Nothing if the rule has not been run previously, and True to indicate the dependencies have changed or False that they have not.

data RunChanged Source #

How has a rule changed.

Constructors

ChangedNothing	Nothing has changed.
ChangedStore	The persisted value has changed, but in a way that should be considered identical.
ChangedRecomputeSame	I recomputed the value and it was the same.
ChangedRecomputeDiff	I recomputed the value and it was different.

Instances

Eq RunChanged Source #
Methods (==) :: RunChanged -> RunChanged -> Bool # (/=) :: RunChanged -> RunChanged -> Bool #
Show RunChanged Source #
Methods showsPrec :: Int -> RunChanged -> ShowS # show :: RunChanged -> String # showList :: [RunChanged] -> ShowS #
NFData RunChanged Source #
Methods rnf :: RunChanged -> () #

data RunResult value Source #

The result of BuiltinRun.

Constructors

RunResult
Fields runChanged :: RunChanged What has changed from the previous time. runStore :: ByteString Return the new value to store. Often a serialised version of `runValue`. runValue :: value Return the produced value.

Instances

Functor RunResult Source #
Methods fmap :: (a -> b) -> RunResult a -> RunResult b # (<$) :: a -> RunResult b -> RunResult a #
NFData value => NFData (RunResult value) Source #
Methods rnf :: RunResult value -> () #

Calling builtin rules

apply :: (RuleResult key ~ value, ShakeValue key, Typeable value) => [key] -> Action [value] Source #

Execute a rule, returning the associated values. If possible, the rules will be run in parallel. This function requires that appropriate rules have been added with addUserRule. All key values passed to apply become dependencies of the Action.

apply1 :: (RuleResult key ~ value, ShakeValue key, Typeable value) => key -> Action value Source #

Apply a single rule, equivalent to calling apply with a singleton list. Where possible, use apply to allow parallelism.

User rules

data UserRule a Source #

A UserRule data type, representing user-defined rules associated with a particular type. As an example ?> and %> will add entries to the UserRule data type.

Constructors

UserRule a	Added to the state with `addUserRule :: Typeable a => a -> Rules ()`.
Unordered [UserRule a]	Rules combined with the `Monad` / `Monoid`.
Priority Double (UserRule a)	Rules defined under `priority`.
Alternative (UserRule a)	Rule defined under `alternatives`, matched in order.

Instances

Functor UserRule Source #
Methods fmap :: (a -> b) -> UserRule a -> UserRule b # (<$) :: a -> UserRule b -> UserRule a #
Eq a => Eq (UserRule a) Source #
Methods (==) :: UserRule a -> UserRule a -> Bool # (/=) :: UserRule a -> UserRule a -> Bool #
Show a => Show (UserRule a) Source #
Methods showsPrec :: Int -> UserRule a -> ShowS # show :: UserRule a -> String # showList :: [UserRule a] -> ShowS #

addUserRule :: Typeable a => a -> Rules () Source #

Add a value of type UserRule.

getUserRules :: Typeable a => Action (UserRule a) Source #

Get the UserRule value at a given type. This UserRule will capture all rules added, along with things such as priority and alternatives.

userRuleMatch :: UserRule a -> (a -> Maybe b) -> [b] Source #

Give a UserRule, and a function that tests a given rule, return the most important values that match. In most cases the caller will raise an error if the rule matching returns anything other than a singleton.

Lint integration

trackUse :: ShakeValue key => key -> Action () Source #

Track that a key has been used by the action preceeding it.

trackChange :: ShakeValue key => key -> Action () Source #

Track that a key has been changed by the action preceding it.

trackAllow :: ShakeValue key => (key -> Bool) -> Action () Source #

Allow any matching key to violate the tracking rules.