{-# LANGUAGE TypeFamilies, ConstraintKinds #-}-- | This module is used for defining Shake build systems. As a simple example of a Shake build system,-- let us build the file @result.tar@ from the files listed by @result.txt@:---- @-- import "Development.Shake"-- import "Development.Shake.FilePath"---- main = 'shakeArgs' 'shakeOptions' $ do-- 'want' [\"result.tar\"]-- \"*.tar\" '%>' \\out -> do-- contents \<- 'readFileLines' $ out 'Development.Shake.FilePath.-<.>' \"txt\"-- 'need' contents-- 'cmd' \"tar -cf\" [out] contents-- @---- We start by importing the modules defining both Shake and routines for manipulating 'FilePath' values.-- We define @main@ to call 'shake' with the default 'shakeOptions'. As the second argument to-- 'shake', we provide a set of rules. There are two common forms of rules, 'want' to specify target files,-- and '%>' to define a rule which builds a 'FilePattern'. We use 'want' to require that after the build-- completes the file @result.tar@ should be ready.---- The @*.tar@ rule describes how to build files with the extension @.tar@, including @result.tar@.-- We 'readFileLines' on @result.txt@, after changing the @.tar@ extension to @.txt@. We read each line-- into the variable @contents@ -- being a list of the files that should go into @result.tar@. Next, we-- depend ('need') all the files in @contents@. If any of these files change, the rule will be repeated.-- Finally we call the @tar@ program. If either @result.txt@ changes, or any of the files listed by @result.txt@-- change, then @result.tar@ will be rebuilt.---- To find out more:---- * The user manual contains a longer example and background information on how to use Shake-- <https://www.shakebuild.com/manual>.---- * The home page has links to additional information <https://www.shakebuild.com/>, including-- a mailing list.---- * The theory behind Shake is described in an ICFP 2012 paper,-- <https://ndmitchell.com/downloads/paper-shake_before_building-10_sep_2012.pdf Shake Before Building -- Replacing Make with Haskell>.-- The <https://www.youtube.com/watch?v=xYCPpXVlqFM associated talk> forms a short overview of Shake.moduleDevelopment.Shake(-- * Writing a build system-- $writing-- * GHC build flags-- $flags-- * Other Shake modules-- $modules-- * Coreshake ,shakeOptions ,Rules ,action ,withoutActions ,alternatives ,priority ,versioned ,Action ,traced ,liftIO,actionOnException ,actionFinally ,actionCatch ,actionRetry ,runAfter ,ShakeException (..),-- * ConfigurationShakeOptions (..),Rebuild (..),Lint (..),Change (..),getShakeOptions ,getShakeOptionsRules ,getHashedShakeVersion ,getShakeExtra ,getShakeExtraRules ,addShakeExtra ,-- ** Command lineshakeArgs ,shakeArgsWith ,shakeArgsOptionsWith ,shakeOptDescrs ,-- ** Progress reportingProgress (..),progressSimple ,progressDisplay ,progressTitlebar ,progressProgram ,getProgress ,-- ** VerbosityVerbosity (..),getVerbosity ,putLoud ,putNormal ,putQuiet ,withVerbosity ,quietly ,-- * Running commandscommand ,command_ ,cmd ,cmd_ ,unit,Stdout (..),Stderr (..),Stdouterr (..),Exit (..),Process (..),CmdTime (..),CmdLine (..),CmdResult ,CmdString ,CmdOption (..),addPath ,addEnv ,-- * Explicit parallelismparallel ,forP ,par ,-- * Utility functionscopyFile' ,copyFileChanged ,readFile' ,readFileLines ,writeFile' ,writeFileLines ,writeFileChanged ,removeFiles ,removeFilesAfter ,withTempFile ,withTempDir ,withTempFileWithin ,withTempDirWithin ,-- * File rulesneed ,want ,(%> ),(|%> ),(?> ),phony ,(~> ),phonys ,(&%> ),(&?> ),orderOnly ,orderOnlyAction ,FilePattern ,(?== ),(<//> ),filePattern ,needed ,trackRead ,trackWrite ,trackAllow ,-- * Directory rulesdoesFileExist ,doesDirectoryExist ,getDirectoryContents ,getDirectoryFiles ,getDirectoryDirs ,getDirectoryFilesIO ,-- * Environment rulesgetEnv ,getEnvWithDefault ,-- * Oracle rulesShakeValue ,RuleResult ,addOracle ,addOracleCache ,addOracleHash ,askOracle ,-- * Special rulesalwaysRerun ,-- * ResourcesResource ,newResource ,newResourceIO ,withResource ,withResources ,newThrottle ,newThrottleIO ,unsafeExtraThread ,-- * CachenewCache ,newCacheIO ,historyDisable ,produces ,-- * BatchingneedHasChanged ,resultHasChanged ,batch ,deprioritize ,-- * Deprecated(*> ),(|*> ),(&*> ),(**> ),(*>> ),(?>> ),askOracleWith )whereimportPrelude(Maybe,FilePath)-- Since GHC 7.10 duplicates *>-- I would love to use module export in the above export list, but alas Haddock-- then shows all the things that are hidden in the docs, which is terrible.importControl.Monad.IO.ClassimportDevelopment.Shake.Internal.Value importDevelopment.Shake.Internal.Options importDevelopment.Shake.Internal.Core.Types importDevelopment.Shake.Internal.Core.Action importDevelopment.Shake.Internal.Core.Rules importDevelopment.Shake.Internal.Resource importDevelopment.Shake.Internal.Derived importDevelopment.Shake.Internal.Errors importDevelopment.Shake.Internal.Progress importDevelopment.Shake.Internal.Args importDevelopment.Shake.Command importDevelopment.Shake.Internal.FilePattern importDevelopment.Shake.Internal.Rules.Directory importDevelopment.Shake.Internal.Rules.File importDevelopment.Shake.Internal.Rules.Files importDevelopment.Shake.Internal.Rules.Oracle importDevelopment.Shake.Internal.Rules.OrderOnly importDevelopment.Shake.Internal.Rules.Rerun -- $writing---- When writing a Shake build system, start by defining what you 'want', then write rules-- with '%>' to produce the results. Before calling 'cmd' you should ensure that any files the command-- requires are demanded with calls to 'need'. We offer the following advice to Shake users:---- * If @ghc --make@ or @cabal@ is capable of building your project, use that instead. Custom build systems are-- necessary for many complex projects, but many projects are not complex.---- * The 'shakeArgs' function automatically handles command line arguments. To define non-file targets use 'phony'.---- * Put all result files in a distinguished directory, for example @_make@. You can implement a @clean@-- command by removing that directory, using @'removeFilesAfter' \"_make\" [\"\/\/\*\"]@.---- * To obtain parallel builds set 'shakeThreads' to a number greater than 1.---- * Lots of compilers produce @.o@ files. To avoid overlapping rules, use @.c.o@ for C compilers,-- @.hs.o@ for Haskell compilers etc.---- * Do not be afraid to mix Shake rules, system commands and other Haskell libraries -- use each for what-- it does best.---- * The more accurate the dependencies are, the better. Use additional rules like 'doesFileExist' and-- 'getDirectoryFiles' to track information other than just the contents of files. For information in the environment-- that you suspect will change regularly (perhaps @ghc@ version number), either write the information to-- a file with 'alwaysRerun' and 'writeFileChanged', or use 'addOracle'.-- $flags---- For large build systems the choice of GHC flags can have a significant impact. We recommend:---- > ghc --make MyBuildSystem -threaded -rtsopts "-with-rtsopts=-I0 -qg"---- * @-rtsopts@: Allow the setting of further GHC options at runtime.---- * @-I0@: Disable idle garbage collection, to avoid frequent unnecessary garbage collection, see-- <https://stackoverflow.com/questions/34588057/why-does-shake-recommend-disabling-idle-garbage-collection/ a full explanation>.---- * With GHC 7.6 and before, omit @-threaded@: <https://ghc.haskell.org/trac/ghc/ticket/7646 GHC bug 7646>-- can cause a race condition in build systems that write files then read them. Omitting @-threaded@ will-- still allow your 'cmd' actions to run in parallel, so most build systems will still run in parallel.---- * With GHC 7.8 and later you may add @-threaded@, and pass the options @-qg@ to @-with-rtsopts@-- to disable parallel garbage collection. Parallel garbage collection in Shake-- programs typically goes slower than sequential garbage collection, while occupying many cores that-- could be used for running system commands.-- $modules---- The main Shake module is this one, "Development.Shake", which should be sufficient for most-- people writing build systems using Shake. However, Shake provides some additional modules,---- * "Development.Shake.Classes" provides convenience exports of the classes Shake relies on,-- in particular 'Binary', 'Hashable' and 'NFData'. Useful for deriving these types using-- @GeneralizedNewtypeDeriving@ without adding dependencies on the associated packages.---- * "Development.Shake.Command" provides the command line wrappers. These are reexported by-- "Development.Shake", but if you want to reuse just the command-line running functionality-- in a non-Shake program you can import just that.---- * "Development.Shake.Config" provides a way to write configuration files that are tracked.-- The configuration files are in the Ninja format. Useful for users of bigger systems who-- want to track the build rules not in Haskell.---- * "Development.Shake.Database" provides lower level primitives to drive Shake, particularly-- useful if you want to run multiple Shake runs in a row without reloading from the database.---- * "Development.Shake.FilePath" is an extension of "System.FilePath" with a few additional-- methods and safer extension manipulation code.---- * "Development.Shake.Forward" is an alternative take on build systems, where you write the-- rules as a script where steps are skipped, rather than as a set of dependencies. Only really-- works if you use @fsatrace@.---- * "Development.Shake.Rule" provides tools for writing your own types of Shake rules. Useful-- if you need something new, like a rule that queries a database or similar.---- * "Development.Shake.Util" has general utilities that are useful for build systems, e.g.-- reading @Makefile@ syntax and alternative forms of argument parsing.----------------------------------------------------------------------- DEPRECATED SINCE 0.13, MAY 2014infix1**> ,?>> ,*>> {-# DEPRECATED(**>)"Use |%> instead"#-}-- | /Deprecated:/ Alias for '|%>'.(**>)::[FilePattern ]->(FilePath->Action ())->Rules ()(**> )=(|%> ){-# DEPRECATED(?>>)"Use &?> instead"#-}-- | /Deprecated:/ Alias for '&?>'.(?>>)::(FilePath->Maybe[FilePath])->([FilePath]->Action ())->Rules ()(?>> )=(&?> ){-# DEPRECATED(*>>)"Use &%> instead"#-}-- | /Deprecated:/ Alias for '&%>'.(*>>)::[FilePattern ]->([FilePath]->Action ())->Rules ()(*>> )=(&%> )----------------------------------------------------------------------- DEPRECATED SINCE 0.14, MAY 2014infix1*> ,|*> ,&*> {-# DEPRECATED(*>)"Use %> instead"#-}-- | /Deprecated:/ Alias for '%>'. Note that @*>@ clashes with a Prelude operator in GHC 7.10.(*>)::FilePattern ->(FilePath->Action ())->Rules ()(*> )=(%> ){-# DEPRECATED(|*>)"Use |%> instead"#-}-- | /Deprecated:/ Alias for '|%>'.(|*>)::[FilePattern ]->(FilePath->Action ())->Rules ()(|*> )=(|%> ){-# DEPRECATED(&*>)"Use &%> instead"#-}-- | /Deprecated:/ Alias for '&%>'.(&*>)::[FilePattern ]->([FilePath]->Action ())->Rules ()(&*> )=(&%> )----------------------------------------------------------------------- DEPRECATED SINCE 0.16.1, NOV 2017-- | /Deprecated:/ Replace @'askOracleWith' q a@ by @'askOracle' q@-- since the 'RuleResult' type family now fixes the result type.askOracleWith::(RuleResultq ~a ,ShakeValue q ,ShakeValue a )=>q ->a ->Action a askOracleWith question _=askOracle question