Development.Shake.Rule

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.

Defining builtin rules

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

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)

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

A suitable BuiltinLint that always succeeds.

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

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

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

Methods

(==) :: RunChanged -> RunChanged -> Bool

(/=) :: RunChanged -> RunChanged -> Bool

Show RunChanged

Methods

showsPrec :: Int -> RunChanged -> ShowS

show :: RunChanged -> String

showList :: [RunChanged] -> ShowS

NFData RunChanged

Methods

rnf :: RunChanged -> ()

data RunResult value

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

Methods

fmap :: (a -> b) -> RunResult a -> RunResult b

(<$) :: a -> RunResult b -> RunResult a

NFData value => NFData (RunResult value)

Methods

rnf :: RunResult value -> ()

Calling builtin rules

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

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, ShakeValue value) => key -> Action value

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

User rules

data UserRule a

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

Methods

fmap :: (a -> b) -> UserRule a -> UserRule b

(<$) :: a -> UserRule b -> UserRule a

Eq a => Eq (UserRule a)

Methods

(==) :: UserRule a -> UserRule a -> Bool

(/=) :: UserRule a -> UserRule a -> Bool

Show a => Show (UserRule a)

Methods

showsPrec :: Int -> UserRule a -> ShowS

show :: UserRule a -> String

showList :: [UserRule a] -> ShowS

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

Add a value of type UserRule.

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

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]

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 ()

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

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

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

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

Allow any matching key to violate the tracking rules.