Rule.hs

-- | 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.
module Development.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
    ) where

import Development.Shake.Internal.Core.Types
import Development.Shake.Internal.Core.Action
import Development.Shake.Internal.Core.Build
import Development.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" $ pure ()
-- >     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 pure ""
-- >
-- >         run :: BuiltinRun File ()
-- >         run key old mode = do
-- >             now <- liftIO $ fileContents key
-- >             if mode == RunDependenciesSame && fmap BS.unpack old == Just now then
-- >                 pure $ 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
-- >                 pure $ 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.