diff --git a/src/Development/Shake/Internal/Core/Types.hs b/src/Development/Shake/Internal/Core/Types.hs index 51652a52..13712578 100755 --- a/src/Development/Shake/Internal/Core/Types.hs +++ b/src/Development/Shake/Internal/Core/Types.hs @@ -60,8 +60,14 @@ import Prelude -- To raise an exception call 'error', 'fail' or @'liftIO' . 'throwIO'@. -- -- The 'Action' type is both a 'Monad' and 'Applicative'. Anything that is depended upon applicatively --- will have its dependencies run in parallel. For example @'need' [\"a\"] *> 'need [\"b\"]@ is equivalent --- to @'need' [\"a\", \"b\"]@. +-- will have its dependencies run in parallel. For example, +-- @'Development.Shake.Internal.Rules.File.need' [\"a\"] '*>' 'Development.Shake.Internal.Rules.File.need' [\"b\"]@ +-- is equivalent to @'need' [\"a\", \"b\"]@. +-- +-- Note that since Shake 0.18, the non-capturing monadic bind ('>>') will also run its dependencies in parallel. +-- For example, +-- @'Development.Shake.Internal.Rules.File.need' [\"a\"] '>>' 'Development.Shake.Internal.Rules.File.need' [\"b\"]@ +-- is also equivalent to @'Development.Shake.Internal.Rules.File.need' [\"a\", \"b\"]@. newtype Action a = Action {fromAction :: RAW ([String],[Key]) [Value] Global Local a} deriving (Functor, Applicative, Monad, MonadIO, Typeable, Semigroup, Monoid, MonadFail) diff --git a/src/Development/Shake/Internal/Rules/File.hs b/src/Development/Shake/Internal/Rules/File.hs index 3946ee2f..aadc7028 100644 --- a/src/Development/Shake/Internal/Rules/File.hs +++ b/src/Development/Shake/Internal/Rules/File.hs @@ -371,8 +371,13 @@ fileForward help act = addUserRule $ FileRule help $ fmap ModeForward . act -- 'Development.Shake.cmd' \"rot13\" [src] \"-o\" [out] -- @ -- --- Usually @need [foo,bar]@ is preferable to @need [foo] >> need [bar]@ as the former allows greater --- parallelism, while the latter requires @foo@ to finish building before starting to build @bar@. +-- Note that the following expressions are all equivalent. @foo@ and @bar@ are built in parallel: +-- +-- - @need [foo,bar]@ +-- - @need [foo] '*>' need [bar]@ +-- - @need [foo] '>>' need [bar]@ +-- +-- In this situation, @need [foo, bar]@ is preferable, since the parallelism is the most obvious. -- -- This function should not be called with wildcards (e.g. @*.txt@ - use 'getDirectoryFiles' to expand them), -- environment variables (e.g. @$HOME@ - use 'getEnv' to expand them) or directories (directories cannot be