Command line flags
There are a number of different modes in which Shake can run, which have an overarching effect on what Shake does. None of these are directly available from the Shake API.
-h, --help– print the a message about supported command line flags and exit.
-v, --version, --numeric-version– print version information and exit. This will always be the Shake version number as available on Hackage.
--demo– run in demo mode, which creates a demo project and compiles it, producing this output.
-f FILE, --file=FILE, --makefile=FILE– read in
FILEas a Makefile or Ninja project. By default will look for
build.ninjaand use that if it exists.
-t TOOL, --tool=TOOL– Ninja-compatible tools such as
compdb, only valid when operating on a Ninja project.
By default all
action statements in
Rules will be run. If any non-flag arguments are passed then these statements will be ignored, and the non-flag arguments will be passed to
want will build either
phony rules or file rules (through
%>). The remaining flags in this section control when things get built.
--no-build– don't build anything, useful for profiling the previous run.
-k, --keep-going– keep going if there are errors, failing only once nothing further can be built, sets
shakeStaunch. Also known as staunch mode. Use
-S, --no-keep-going, --stopto turn off.
--skip-commands– try and avoid running external programs, sets
False. Useful for profiling.
--rule-version=VERSION– set the
shakeVersion, if this field changes everything will rebuild – useful for the version of the build system, rather than the source files.
--no-rule-version– ignore the
shakeVersionsetting, equivalent to setting
shakeVersionIgnore, useful if you compute
shakeVersionas the hash of the build system and want to ignore changes temporarily.
--digest, --digest-and, --digest-and-input, --digest-or, --digest-not– set the
shakeChangefield to one of the
Changevalues. Defaults to comparing files by modification time, but
--digest-and(compare all files using a digest) or
--digest-and-input(compare all input files using a digest) are often useful. However, this value is usually set in the code.
In addition, there are a number of flags for controlling whether files are treated as dirty despite being clean, or clean despite being dirty. The exact semantics remain somewhat confusing, and should be cleaned up.
These options control what gets printed to the console. All output produced by Shake goes through the
shakeOutput function, which provides another point to control the output.
--color, --colour– colorize the output, implemented via
-a FULL=SHORT, --abbrev=FULL=SHORT– use abbreviation in status messages. Adds to the
shakeAbbreviationsfield. A list of substrings that should be abbreviated in status messages, and their corresponding abbreviation. Commonly used to replace the long paths (e.g.
.make/i586-linux-gcc/output) with an abbreviation (e.g.
-d[=FILE], --debug[=FILE]– print lots of debugging information, optionally to a file.
-q, --quiet– don't print much, decreases the
-s, --silent– don't print anything, sets the
-V, --verbose, --trace– print more information, increases the
shakeVerbositylevel each time the flag appears, to
--no-time– don't print the build time after execution.
Shake can generate a number of different reports to help examine additional aspects of a build system.
-r[=FILE], --report[=FILE], --profile[=FILE]– generate a profile report to
FILE, defaults to
shakeReport. The report extension determines the type of data that is written, for example
.htmlfor an HTML report, or
.jsonfor the raw JSON data. Pass
FILEto print a summary report to the console. To interpret the reports and for future settings see the profiling page. Can be disabled with
--live[=FILE]– list the files that are still "live" to
FILE, defaults to
shakeLiveFiles. After the build system completes, write a list of all files which were live in that run, i.e. those which Shake checked were valid or rebuilt. Produces best answers if nothing rebuilds.
-p[=N], --progress[=N]– show progress messages every
Nseconds, defaulting to 5 seconds. Sets
progressSimple. Progress messages will be shown in the window titlebar. Can be disabled by passing
--storage– write a storage log to the next to a file location controlled by
--metadata. This storage log will be written to occasionally – whenever a partially truncated database is found, or when the database is compacted. Generally useful only for debugging.
Shake can perform additional checks on an execution using linting.
-l, --lint– perform limited lint checking after the run, sets
LintBasic. Checks that the current directory does not change and that results do not change after they are first written. Any calls to
neededwill assert that they do not cause a rule to be rebuilt. Can be disabled with
--lint-fsatrace– use the
fsatraceprogram to do validation, sets
LintFSATrace, tracking which files are accessed by command line programs.
Finally there are some general settings, which control miscellaneous features of Shake.
-j[=N], --jobs[=N]– allow
Njobs/threads to run at, sets
shakeThreads. Defaults to 1 thread if the flag is omitted, or the number of CPUs if passing
-jwith no argument value.
-m PREFIX, --metadata=PREFIX– prefix for storing Shake produced metadata files, sets
shakeFiles. Generally this setting should be controlled in the code.
shakeFlush, defaults to
--flush=10. How often to flush Shake metadata files in seconds. It is possible that on abnormal termination (not Haskell exceptions but killing processes) that any rules that completed in the last
Nseconds will be lost. Flushing can be disabled entirely with
--never-flush, if you like living on the edge.
--directory=DIRECTORY– change to
DIRECTORYbefore doing anything.
-w, --print-directory– print the current directory after changing directory, can be disabled with
--no-print-directory(these flags are in
make– probably for historical reasons).
--sleep– sleep for one second before building.
--exception– if set throws exceptions, otherwise exceptions will be printed to
stderrand it will throw