phony "name" $ do
actions
-Where name is the name used on the command line to invoke the actions, and actions are the list of things to do in response. These names are not dependency tracked and are simply run afresh each time they are requested.
+Where name is the name used on the command line to invoke the actions, and actions are the list of things to do in response. These names are not dependency tracked and are run afresh each time they are requested.
-The actions can be any standard build actions, although for a `clean` rule, `removeFilesAfter` is typical. This function waits until after any files have finished building (which will be none, if you do `runhaskell Build.hs clean`) then deletes all files matching `//*` in the `_build` directory. The `putNormal` function writes out a message to the console, as long as `--quiet` was not passed.
+The actions can be any standard build actions, although for a `clean` rule, `removeFilesAfter` is typical. This function waits until after any files have finished building (which will be none, if you do `runhaskell Shakefile.hs clean`) then deletes all files matching `//*` in the `_build` directory. The `putInfo` function writes out a message to the console, as long as `--quiet` was not passed.
## Running
@@ -280,17 +278,17 @@
#### Compiling the build system
-As shown before, we can use `runhaskell Build.hs` to execute our build system, but doing so causes the build script to be compiled afresh each time. A more common approach is to add a shell script that compiles the build system and runs it. In the example directory you will find `build.sh` (Linux) and `build.bat` (Windows), both of which execute the same interesting commands. Looking at `build.sh`:
+As shown before, we can use `runhaskell Shakefile.hs` to execute our build system, but doing so causes the build script to be compiled afresh each time. A more common approach is to add a shell script that compiles the build system and runs it. In the example directory you will find `build.sh` (Linux) and `build.bat` (Windows), both of which execute the same interesting commands. Looking at `build.sh`:
#!/bin/sh
mkdir -p _shake
- ghc --make Build.hs -rtsopts -with-rtsopts=-I0 -outputdir=_shake -o _shake/build && _shake/build "$@"
+ ghc --make Shakefile.hs -rtsopts -threaded -with-rtsopts=-I0 -outputdir=_shake -o _shake/build && _shake/build "$@"
-This script creates a folder named `_shake` for the build system objects to live in, then runs `ghc --make Build.hs` to produce `_shake/build`, then executes `_shake/build` with all arguments it was given. The `-with-rtsopts` flag instructs the Haskell compiler to disable "idle garbage collection", making more CPU available for the commands you are running, as [explained here](http://stackoverflow.com/questions/34588057/why-does-shake-recommend-disabling-idle-garbage-collection/).
+This script creates a folder named `_shake` for the build system objects to live in, then runs `ghc --make Shakefile.hs` to produce `_shake/build`, then executes `_shake/build` with all arguments it was given. The `-with-rtsopts` flag instructs the Haskell compiler to disable "idle garbage collection", making more CPU available for the commands you are running, as [explained here](https://stackoverflow.com/questions/34588057/why-does-shake-recommend-disabling-idle-garbage-collection/).
-Now you can run a build by simply typing `stack exec ./build.sh` on Linux, or `stack exec build.bat` on Windows. On Linux you may want to alias `build` to `stack exec ./build.sh`. For the rest of this document we will assume `build` runs the build system.
+Now you can run a build by typing `stack exec ./build.sh` on Linux, or `stack exec build.bat` on Windows. On Linux you may want to alias `build` to `stack exec ./build.sh`. For the rest of this document we will assume `build` runs the build system.
-_Warning:_ You should not use the `-threaded` for GHC 7.6 or below because of a [GHC bug](https://ghc.haskell.org/trac/ghc/ticket/7646). If you do turn on `-threaded`, you should include `-qg -qb` in `-with-rtsopts`.
+_Warning:_ You should not use the `-threaded` for GHC 7.6 or below because of a [GHC bug](https://ghc.haskell.org/trac/ghc/ticket/7646). If you do turn on `-threaded`, you should include `-qg` in `-with-rtsopts`.
#### Command line flags
@@ -313,22 +311,22 @@
* Running `build --progress`
* Setting `shakeOptions{shakeProgress = progressSimple}`
-The progress message will be displayed in the titlebar of the window, for example `3m12s (82%)` to indicate that the build is 82% complete and is predicted to take a further 3 minutes and 12 seconds. If you are running Windows 7 or higher and place the [`shake-progress`](https://github.org/ndmitchell/shake) utility somewhere on your `%PATH%` then the progress will also be displayed in the taskbar progress indicator:
+The progress message will be displayed in the titlebar of the window, for example `3m12s (82%)` to indicate that the build is 82% complete and is predicted to take a further 3 minutes and 12 seconds. If you are running Windows 7 or higher and place the [`shake-progress`](https://github.com/ndmitchell/shake/releases/tag/shake-progress-1) utility somewhere on your `%PATH%` then the progress will also be displayed in the taskbar progress indicator:
-Progress prediction is likely to be relatively poor during the first build and after running `build clean`, as then Shake has no information about the predicted execution time for each rule. To rebuild from scratch without running clean (because you really want to see the progress bar!) you can use the argument `--always-make`, which assumes all rules need rerunning.
+Progress prediction is likely to be relatively poor during the first build and after running `build clean`, as then Shake has no information about the predicted execution time for each rule. To rebuild from scratch without running clean (because you really want to see the progress bar!) you can use the argument `--always-make`, which assumes all rules need rerunning.
#### Lint
-Shake features a built in "lint" features to check the build system is well formed. To run use `build --lint`. You are likely to catch more lint violations if you first `build clean`. Sadly, lint does _not_ catch missing dependencies. However, it does catch:
+Shake features a built in "lint" feature to check the build system is well formed. To run use `build --lint`. You are likely to catch more lint violations if you first `build clean`. Sadly, lint does _not_ catch missing dependencies. However, it does catch:
-* Changing the current directory, typically with `setCurrentDirectory`. You should never change the current directory within the build system as multiple rules running at the same time share the current directory. You can still run `cmd` calls in different directories using the `Cwd` argument.
+* Changing the current directory, typically with `setCurrentDirectory`. You should never change the current directory within the build system as multiple rules running at the same time share the current directory. You can still run `cmd_` calls in different directories using the `Cwd` argument.
* Outputs that change after Shake has built them. The usual cause of this error is if the rule for `foo` also writes to the file `bar`, despite `bar` having a different rule producing it.
-There is a performance penalty for building with `--lint`, but it is typically small.
+There is a performance penalty for building with `--lint`, but it is typically small. For more details see [this page on all the Lint options](Lint.md).
@@ -344,8 +342,8 @@
* Run in single-threaded mode (`-j1`) to make any output clearer by not interleaving commands.
* By default a Shake build system prints out a message every time it runs a command. Use verbose mode (`--verbose`) to print more information to the screen, such as which rule is being run. Additional `--verbose` flags increase the verbosity. Three verbosity flags produce output intended for someone debugging the Shake library itself, rather than a build system based on it.
* To raise a build error call `error "error message"`. Shake will abort, showing the error message.
-* To output additional information use `putNormal "output message"`. This message will be printed to the console when it is reached.
-* To show additional information with either `error` or `putNormal`, use `error $ show ("message", myVariable)`. This allows you to show any local variables.
+* To output additional information use `putInfo "output message"`. This message will be printed to the console when it is reached.
+* To show additional information with either `error` or `putInfo`, use `error $ show ("message", myVariable)`. This allows you to show any local variables.
## Extensions
@@ -353,15 +351,15 @@
#### Advanced `cmd` usage
-The `cmd` function can also obtain the stdout and stderr streams, along with the exit code. As an example:
+The `cmd_` has a related function `cmd` that can also obtain the stdout and stderr streams, along with the exit code. As an example:
(Exit code, Stdout out, Stderr err) <- cmd "gcc --version"
Now the variable `code` is bound to the exit code, while `out` and `err` are bound to the stdout and stderr streams. If `ExitCode` is not requested then any non-zero return value will raise an error.
-The `cmd` function also takes additional parameters to control how the command is run. As an example:
+Both `cmd_` and `cmd` also take additional parameters to control how the command is run. As an example:
- cmd Shell (Cwd "temp") "pwd"
+ cmd_ Shell (Cwd "temp") "pwd"
This runs the `pwd` command through the system shell, after first changing to the `temp` directory.
@@ -370,8 +368,8 @@
You can use tracked dependencies on environment variables using the `getEnv` function. As an example:
link <- getEnv "C_LINK_FLAGS"
- let linkFlags = fromMaybe "" link
- cmd "gcc -o" [output] inputs linkFlags
+ let linkFlags = fromMaybe "" link
+ cmd_ "gcc -o" [output] inputs linkFlags
This example gets the `$C_LINK_FLAGS` environment variable (which is `Maybe String`, namely a `String` that might be missing), then using `fromMaybe` defines a local variable `linkFlags` that is the empty string when `$C_LINK_FLAGS` is not set. It then passes these flags to `gcc`.
@@ -398,9 +396,9 @@
want [show i <.> "exe" | i <- [1..100]]
"*.exe" %> \out -> do
withResource disk 1 $ do
- cmd "ld -o" [out] ...
+ cmd_ "ld -o" [out] ...
"*.o" %> \out -> do
- cmd "cl -o" [out] ...
+ cmd_ "cl -o" [out] ...
Assuming `-j8`, this allows up to 8 compilers, but only a maximum of 4 linkers.
@@ -410,19 +408,19 @@
["//*.bison.h","//*.bison.c"] &%> \[outh, outc] -> do
let src = outc -<.> "y"
- cmd "bison -d -o" [outc] [src]
+ cmd_ "bison -d -o" [outc] [src]
Now we define a list of patterns that are matched, and get a list of output files. If any output file is required, then all output files will be built, with proper dependencies.
#### Changing build rules
-Shake build systems are set up to rebuild files when the dependencies change, but mostly assume that the build rules themselves do not change. To minimise the impact of build rule changes there are three approaches:
+Shake build systems are set up to rebuild files when the dependencies change, but mostly assume that the build rules themselves do not change (including both the code and the shell commands contained within). To minimise the impact of build rule changes there are three approaches:
_Use configuration files:_ Most build information, such as which files a C file includes, can be computed from source files. Where such information is not available, such as which C files should be linked together to form an executable, use configuration files to provide the information. The rule for linking can use these configuration files, which can be properly tracked. Moving any regularly changing configuration into separate files will significantly reduce the number of build system changes.
_Depend on the build source:_ One approach is to depend on the build system source in each of the rules, then if _any_ rules change, _everything_ will rebuild. While this option is safe, it may cause a significant number of redundant rebuilds. As a restricted version of this technique, for a generated file you can include a dependency on the generator source and use `writeFileChanged`. If the generator changes it will rerun, but typically only a few generated files will change, so little is rebuilt.
-_Use a version stamp:_ There is a field named `shakeVersion` in the `ShakeOptions` record. If the build system changes in a significant and incompatible way, you can change this field to force a full rebuild. If you want all rules to depend on all rules, you can put a hash of the build system source in the version field, as [described here](http://stackoverflow.com/questions/18532552/shake-how-to-reliably-automatically-force-rebuild-when-my-rules-change-becomi/18532553#18532553).
+_Use a version stamp:_ There is a field named `shakeVersion` in the `ShakeOptions` record. If the build system changes in a significant and incompatible way, you can change this field to force a full rebuild. If you want all rules to depend on all rules, you can put a hash of the build system source in the version field, as [described here](https://stackoverflow.com/questions/18532552/shake-how-to-reliably-automatically-force-rebuild-when-my-rules-change-becomi/18532553#18532553).
## The Haskell Zone
@@ -445,7 +443,7 @@
pattern %> actions = (pattern ?==) ?> actions
-Where `?==` is a function for matching file patterns.
+Where `?==` is a function for matching file patterns.
#### Haskell Actions
diff --git a/docs/manual/Build.hs b/docs/manual/Build.hs
deleted file mode 100644
--- a/docs/manual/Build.hs
+++ /dev/null
@@ -1,24 +0,0 @@
-import Development.Shake
-import Development.Shake.Command
-import Development.Shake.FilePath
-import Development.Shake.Util
-
-main :: IO ()
-main = shakeArgs shakeOptions{shakeFiles="_build"} $ do
- want ["_build/run" <.> exe]
-
- phony "clean" $ do
- putNormal "Cleaning files in _build"
- removeFilesAfter "_build" ["//*"]
-
- "_build/run" <.> exe %> \out -> do
- cs <- getDirectoryFiles "" ["//*.c"]
- let os = ["_build" c -<.> "o" | c <- cs]
- need os
- cmd "gcc -o" [out] os
-
- "_build//*.o" %> \out -> do
- let c = dropDirectory1 $ out -<.> "c"
- let m = out -<.> "m"
- () <- cmd "gcc -c" [c] "-o" [out] "-MMD -MF" [m]
- needMakefileDependencies m
diff --git a/docs/manual/Shakefile.hs b/docs/manual/Shakefile.hs
new file mode 100644
--- /dev/null
+++ b/docs/manual/Shakefile.hs
@@ -0,0 +1,24 @@
+import Development.Shake
+import Development.Shake.Command
+import Development.Shake.FilePath
+import Development.Shake.Util
+
+main :: IO ()
+main = shakeArgs shakeOptions{shakeFiles="_build"} $ do
+ want ["_build/run" <.> exe]
+
+ phony "clean" $ do
+ putInfo "Cleaning files in _build"
+ removeFilesAfter "_build" ["//*"]
+
+ "_build/run" <.> exe %> \out -> do
+ cs <- getDirectoryFiles "" ["//*.c"]
+ let os = ["_build" c -<.> "o" | c <- cs]
+ need os
+ cmd_ "gcc -o" [out] os
+
+ "_build//*.o" %> \out -> do
+ let c = dropDirectory1 $ out -<.> "c"
+ let m = out -<.> "m"
+ cmd_ "gcc -c" [c] "-o" [out] "-MMD -MF" [m]
+ neededMakefileDependencies m
diff --git a/docs/manual/build.bat b/docs/manual/build.bat
--- a/docs/manual/build.bat
+++ b/docs/manual/build.bat
@@ -1,2 +1,2 @@
@mkdir _shake 2> nul
-@ghc --make Build.hs -rtsopts -with-rtsopts=-I0 -outputdir=_shake -o _shake/build && _shake\build %*
+@ghc --make Shakefile.hs -rtsopts -threaded -with-rtsopts=-I0 -outputdir=_shake -o _shake/build && _shake\build %*
diff --git a/docs/manual/build.sh b/docs/manual/build.sh
--- a/docs/manual/build.sh
+++ b/docs/manual/build.sh
@@ -1,3 +1,3 @@
#!/bin/sh
mkdir -p _shake
-ghc --make Build.hs -rtsopts -with-rtsopts=-I0 -outputdir=_shake -o _shake/build && _shake/build "$@"
+ghc --make Shakefile.hs -rtsopts -threaded -with-rtsopts=-I0 -outputdir=_shake -o _shake/build && _shake/build "$@"
diff --git a/html/profile.html b/html/profile.html
--- a/html/profile.html
+++ b/html/profile.html
@@ -6,167 +6,205 @@
-
| ||||
|
- - | ||||
|
- Loading...
- |