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

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

- addBuiltinRule :: (RuleResult key ~ value, ShakeValue key, ShakeValue value) => BuiltinLint key value -> BuiltinRun key value -> Rules ()
- type BuiltinLint key value = key -> value -> IO (Maybe String)
- noLint :: BuiltinLint key value
- type BuiltinRun key value = key -> Maybe ByteString -> Bool -> Action (RunResult value)
- data RunChanged
  - = ChangedNothing
  - | ChangedStore
  - | ChangedRecomputeSame
  - | ChangedRecomputeDiff
- data RunResult value = RunResult {
  - runChanged :: RunChanged
  - runStore :: ByteString
  - runValue :: value
  }
- apply :: (RuleResult key ~ value, ShakeValue key, Typeable value) => [key] -> Action [value]
- apply1 :: (RuleResult key ~ value, ShakeValue key, Typeable value) => key -> Action value
- data UserRule a
  - = UserRule a
  - | Unordered [UserRule a]
  - | Priority Double (UserRule a)
  - | Alternative (UserRule a)
- addUserRule :: Typeable a => a -> Rules ()
- getUserRules :: Typeable a => Action (UserRule a)
- userRuleMatch :: UserRule a -> (a -> Maybe b) -> [b]
- trackUse :: ShakeValue key => key -> Action ()
- trackChange :: ShakeValue key => key -> Action ()
- trackAllow :: ShakeValue key => (key -> Bool) -> Action ()

# 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 # |
Instance details Defined in Development.Shake.Internal.Core.Types Methods (==) :: RunChanged -> RunChanged -> Bool Source # (/=) :: RunChanged -> RunChanged -> Bool Source #
Show RunChanged Source # |
Instance details Defined in Development.Shake.Internal.Core.Types Methods showsPrec :: Int -> RunChanged -> ShowS Source # show :: RunChanged -> String Source # showList :: [RunChanged] -> ShowS Source #
NFData RunChanged Source # |
Instance details Defined in Development.Shake.Internal.Core.Types Methods rnf :: RunChanged -> () Source #

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 # |
Instance details Defined in Development.Shake.Internal.Core.Types Methods fmap :: (a -> b) -> RunResult a -> RunResult b Source # (<$) :: a -> RunResult b -> RunResult a Source #
NFData value => NFData (RunResult value) Source # |
Instance details Defined in Development.Shake.Internal.Core.Types Methods rnf :: RunResult value -> () Source #

# 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 # |
Instance details Defined in Development.Shake.Internal.Core.Types Methods fmap :: (a -> b) -> UserRule a -> UserRule b Source # (<$) :: a -> UserRule b -> UserRule a Source #
Eq a => Eq (UserRule a) Source # |
Instance details Defined in Development.Shake.Internal.Core.Types Methods (==) :: UserRule a -> UserRule a -> Bool Source # (/=) :: UserRule a -> UserRule a -> Bool Source #
Show a => Show (UserRule a) Source # |
Instance details Defined in Development.Shake.Internal.Core.Types Methods showsPrec :: Int -> UserRule a -> ShowS Source # show :: UserRule a -> String Source # showList :: [UserRule a] -> ShowS Source #

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.