-- | This module is used for defining new types of rules for Shake build systems, e.g. to support values stored in a database.-- Most users will find the built-in set of rules sufficient. The functions in this module are designed for high-performance,-- not ease of use or abstraction. As a result, they are difficult to work with and change more often than the other parts of Shake.-- Before writing a builtin rule you are encouraged to use 'Development.Shake.addOracle' or 'Development.Shake.addOracleCache' if possible.-- With all those warnings out the way, read on for the grungy details.moduleDevelopment.Shake.Rule(-- * Builtin rules-- $builtin_rules-- ** Extensions-- $extensions-- ** Worked example-- $example-- * Defining builtin rules-- | Functions and types for defining new types of Shake rules.addBuiltinRule ,BuiltinLint ,noLint ,BuiltinIdentity ,noIdentity ,BuiltinRun ,RunMode (..),RunChanged (..),RunResult (..),-- * Calling builtin rules-- | Wrappers around calling Shake rules. In general these should be specialised to a builtin rule.apply ,apply1 ,-- * User rules-- | Define user rules that can be used by builtin rules.-- Absent any builtin rule making use of a user rule at a given type, a user rule will have on effect --- they have no inherent effect or interpretation on their own.addUserRule ,getUserRuleList ,getUserRuleMaybe ,getUserRuleOne ,-- * Lint integration-- | Provide lint warnings when running code.lintTrackRead ,lintTrackWrite ,lintTrackAllow ,-- * History caching-- | Interact with the non-local cache. When using the cache it is important that all-- rules have accurate 'BuiltinIdentity' functions.historyIsEnabled ,historySave ,historyLoad )whereimportDevelopment.Shake.Internal.Core.Types importDevelopment.Shake.Internal.Core.Action importDevelopment.Shake.Internal.Core.Build importDevelopment.Shake.Internal.Core.Rules -- $builtin_rules---- Shake \"Builtin\" rules are ones map keys to values - e.g. files to file contents. For each builtin rule you need to think:---- * What is the @key@ type, which uniquely identifies each location, e.g. a filename.---- * What is the @value@ type. The @value@ is not necessarily the full value, but is the result people can get if they ask-- for the value associated with the @key@. As an example, for files when you 'need' a file you don't get any value back from-- the file, so a simple file rule could have @()@ as its value.---- * What information is stored between runs. This information should be sufficient to check if the value has changed since last time,-- e.g. the modification time for files.---- Typically a custom rule will define a wrapper of type 'Rules' that calls 'addBuiltinRule', along with a type-safe wrapper over-- 'apply' so users can introduce dependencies.-- $extensions---- Once you have implemented the basic functionality there is more scope for embracing additional features of Shake, e.g.:---- * You can integrate with cached history by providing a working 'BuiltinIdentity' and using 'historySave' and 'historyLoad'.---- * You can let users provide their own rules which you interpret with 'addUserRule'.---- * You can integrate with linting by specifying a richer 'BuiltinLint' and options like 'lintTrackRead'.---- There are lots of rules defined in the Shake repo at <https://github.com/ndmitchell/shake/tree/master/src/Development/Shake/Internal/Rules>.-- You are encouraged to read those for inspiration.-- $example---- Shake provides a very comprehensive file rule which currently runs to over 500 lines of code, and supports lots of features-- and optimisations. However, let's imagine we want to define a simpler rule type for files. As mentioned earlier, we have to make some decisions.---- * A @key@ will just be the file name.---- * A @value@ will be @()@ - when the user depends on a file they don't expect any information in return.---- * The stored information will be the contents of the file, in it's entirety. Alternative choices would be the modtime or a hash of the contents,-- but Shake doesn't require that. The stored information in Shake must be stored in a 'ByteString', so we 'Data.ByteString.pack' and-- 'Data.ByteString.unpack' to convert.---- * We will allow user rules to be defined saying how to build any individual file.---- First we define the type of key and value, deriving all the necessary type classes. We define a @newtype@ over 'FilePath' so we can-- guarantee not to conflict with anyone else. Typically you wouldn't export the @File@ type, providing only sugar functions over it.---- > newtype File = File FilePath-- > deriving (Show,Eq,Hashable,Binary,NFData)-- > type instance RuleResult File = ()---- Since we have decided we are also going to have user rules, we need to define a new type to capture the information stored by the rules.-- We need to store at least the file it is producing and the action, which we do with:---- > data FileRule = FileRule File (Action ())---- With the definitions above users could call 'apply' and 'addUserRule' directly, but that's tedious and not very type safe. To make it easier-- we introduce some helpers:---- > fileRule :: FilePath -> Action () -> Rules ()-- > fileRule file act = addUserRule $ FileRule (File file) act-- >-- > fileNeed :: FilePath -> Action ()-- > fileNeed = apply1 . File---- These helpers just add our type names, providing a more pleasant interface for the user. Using these function we can-- exercise our build system with:---- > example = do-- > fileRule "a.txt" $ return ()-- > fileRule "b.txt" $ do-- > fileNeed "a.txt"-- > liftIO $ writeFile "b.txt" . reverse =<< readFile "a.txt"-- >-- > action $ fileNeed "b.txt"---- This example defines rules for @a.txt@ (a source file) and @b.txt@ (the 'reverse' of @a.txt@). At runtime this example will-- complain about not having a builtin rule for @File@, so the only thing left is to provide one.---- > addBuiltinFileRule :: Rules ()-- > addBuiltinFileRule = addBuiltinRule noLint noIdentity run-- > where-- > fileContents (File x) = do b <- IO.doesFileExist x; if b then IO.readFile' x else return ""-- >-- > run :: BuiltinRun File ()-- > run key old mode = do-- > now <- liftIO $ fileContents key-- > if mode == RunDependenciesSame && fmap BS.unpack old == Just now then-- > return $ RunResult ChangedNothing (BS.pack now) ()-- > else do-- > (_, act) <- getUserRuleOne key (const Nothing) $ \(FileRule k act) -> if k == key then Just act else Nothing-- > act-- > now <- liftIO $ fileContents key-- > return $ RunResult ChangedRecomputeDiff (BS.pack now) ()---- We define a wrapper @addBuiltinFileRule@ that calls @addBuiltinRule@, opting out of linting and cached storage.-- The only thing we provide is a 'BuiltinRun' function which gets the previous state, and whether any dependency has changed,-- and decides whether to rebuild. If something has changed we call 'getUserRuleOne' to find the users rule and rerun it.-- The 'RunResult' says what changed (either 'ChangedNothing' or 'ChangedRecomputeDiff' in our cases), gives us a new stored value-- (just packing the contents) and the @value@ which is @()@.---- To execute our example we need to also call @addBuiltinFileRule@, and now everything works.