diff --git a/Development/Shake.hs b/Development/Shake.hs --- a/Development/Shake.hs +++ b/Development/Shake.hs @@ -1,7 +1,6 @@ --- | Main module for defining Shake build systems. You may also want to include --- "Development.Shake.FilePath", for manipulating file paths. As a simple example, --- let us build a @result.tar@ file from the contents of @result.txt@: +-- | 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" @@ -15,8 +14,50 @@ -- 'system'' \"tar\" $ [\"-cf\",out] ++ contents -- @ -- --- For the background theory behind a previous version of Shake the online video: --- . +-- 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. +-- +-- When writing a Shake build system, start by defining what you 'want', then write rules +-- with '*>' to produce the results. Before calling 'system'' 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 CmdArgs package () is well suited to providing +-- command line parsing for build systems, often using flags to set fields in 'shakeOptions'. +-- +-- * Put all result files in a distinguished directory, for example @_make@. You can implement a @clean@ +-- command by removing that directory, using 'removeDirectoryRecursive'. +-- +-- * To obtain paralell builds set 'shakeThreads' to a number greater than 1. You may also need to +-- compile with @-threaded@. +-- +-- * Often the 'want' commands will be determined by command line arguments, to mirror the behaviour of @make@ +-- targets. +-- +-- * 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'. +-- +-- The theory behind an old version of Shake is described in a video at . module Development.Shake( shake, -- * Core of Shake diff --git a/Development/Shake/Core.hs b/Development/Shake/Core.hs --- a/Development/Shake/Core.hs +++ b/Development/Shake/Core.hs @@ -44,7 +44,7 @@ ,shakeVerbosity :: Verbosity -- ^ What messages to print out (defaults to 'Normal'). ,shakeStaunch :: Bool -- ^ Operate in staunch mode, where building continues even after errors (defaults to 'False'). ,shakeDump :: Bool -- ^ Dump all profiling information to 'shakeFiles' plus the extension @.js@ (defaults to 'False'). - ,shakeLint :: Bool -- ^ Perform basic sanity checks after building. + ,shakeLint :: Bool -- ^ Perform basic sanity checks after building (defaults to 'False'). } deriving (Show, Eq, Ord) diff --git a/Development/Shake/Oracle.hs b/Development/Shake/Oracle.hs --- a/Development/Shake/Oracle.hs +++ b/Development/Shake/Oracle.hs @@ -29,7 +29,7 @@ -- > addOracle ["ghc"] $ return ["7.2.1"] -- > addOracle ["ghc-pkg","shake"] $ return ["1.0"] -- --- If a rule depends on the GHC version, it can then use @'getOracle' ["ghc"]@, and +-- If a rule depends on the GHC version, it can then use @'getOracle' [\"ghc\"]@, and -- if the GHC version changes, the rule will rebuild. It is common for the value returned -- by 'askOracle' to be ignored. -- @@ -40,7 +40,7 @@ -- sometimes are used as sets - for example the list of packages returned by @ghc-pkg@. -- -- Actions passed to 'addOracle' will be run in every Shake execution they are required, --- there value will not be kept between runs. To get a similar behaviour using files, see +-- their value will not be kept between runs. To get a similar behaviour using files, see -- 'alwaysRerun'. addOracle :: [String] -> Action [String] -> Rules () addOracle question act = rule $ \(Question q) -> diff --git a/Examples/C/constants.c b/Examples/C/constants.c new file mode 100644 --- /dev/null +++ b/Examples/C/constants.c @@ -0,0 +1,7 @@ + +char msg[] = "Hello Shake Users!"; + +char* message() +{ + return msg; +} diff --git a/Examples/C/constants.h b/Examples/C/constants.h new file mode 100644 --- /dev/null +++ b/Examples/C/constants.h @@ -0,0 +1,1 @@ +char* message(); diff --git a/Examples/C/main.c b/Examples/C/main.c new file mode 100644 --- /dev/null +++ b/Examples/C/main.c @@ -0,0 +1,8 @@ +#include +#include "constants.h" + +int main() +{ + printf("%s\n", message()); + return 0; +} diff --git a/LICENSE b/LICENSE --- a/LICENSE +++ b/LICENSE @@ -1,4 +1,4 @@ -Copyright Neil Mitchell 2006-2007. +Copyright Neil Mitchell 2011-2012. All rights reserved. Redistribution and use in source and binary forms, with or without diff --git a/shake.cabal b/shake.cabal --- a/shake.cabal +++ b/shake.cabal @@ -1,14 +1,14 @@ cabal-version: >= 1.6 build-type: Simple name: shake -version: 0.2.3 +version: 0.2.4 license: BSD3 license-file: LICENSE category: Development author: Neil Mitchell maintainer: Neil Mitchell -copyright: Neil Mitchell 2011 -synopsis: Build system library, like Make, but properly supports generated files. +copyright: Neil Mitchell 2011-2012 +synopsis: Build system library, like Make, but more accurate dependencies. description: Shake is a Haskell library for writing build systems - designed as a replacement for make. To use Shake the user writes a Haskell program @@ -23,26 +23,28 @@ build systems, including automatic parallelism and minimal rebuilds. Shake provides highly accurate dependency tracking, including seamless support for generated files, and dependencies on system information - (i.e. compiler version). Shake will eventually be able to produce profile reports, indicating + (i.e. compiler version). Shake can produce profile reports, indicating which files and take longest to build, and providing an analysis of the parallelism. . The theory behind an old version of Shake is described in a video at , and an example is given at the top of - "Development.Shake". Some further examples are included in the Cabal tarball, + "Development.Shake". Further examples are included in the Cabal tarball, under the @Examples@ directory. homepage: http://community.haskell.org/~ndm/shake/ stability: Beta extra-source-files: + Examples/C/constants.c + Examples/C/constants.h + Examples/C/main.c Examples/Tar/list.txt - source-repository head type: darcs location: http://community.haskell.org/~ndm/darcs/shake/ flag testprog - default: True + default: False description: Build the test program library