Shake reports provide a way of filtering, grouping and viewing the result of running a Shake build system. A query is entered at the top using the text box, run using the 'Run' button, and produces a report whose type is selected from the drop-down box. The 'Link' hyperlink provides a link to the currently entered query, which is useful for copying/sharing.
Report types
The drop-down box, currently displaying 'Help', let's you pick the type of report. The best way to learn about the report types is to try them out (all work with the empty query). The types are:
- Summary: Display summary statistics about the Shake database. The term 'rule' refers to any Shake rule, and there will be one rule for everything that gets built or tracked, including source files. The term 'traced command' refers to any call to traced, which is automatically inserted by the command function. The reported parallelism refers to the average number of traced commands executing during the last build - for example, a parallelism of 4.0 when using shakeThreads=4 would be a perfect speedup. The time spent not executing traced commands includes time when Shake was checking dependencies and any Haskell operations performed by the rules.
- Help: This help document.
- Command plot: This plot shows which traced commands were executing at any time. The Y axis is the number of simultaneous traced commands and the X axis is the progress through the last run of the build system that executed any rules. Some useful queries are:
- Command table: This table shows all traced commands. 'name' is the group name, by default the string passed to trace. 'count' is the number of commands that were grouped together. 'time' is the amount of time spent executing the commands, both in absolute terms and as a percentage of the time required to build everything (including rules which are not traced). Some useful queries are:
- Rule table: This table shows all rules. 'name', 'count' and 'time' are the same as for the command table, with the default name being the rule result. 'cost' is the time to rebuild if all the files changed, where a higher cost is worse. 'leaf' is true if the rule has no dependencies, typically source files. 'runs' is the number of executions since the file was built, where 0 means it was built in the last run. 'unchanged' is true if the last time the rule built it did not change value, and thus rules depending on it did not rebuild. Some useful queries are:
- Rule graph: This table shows the rules and their dependencies. An arrow from a child node to a parent node indicates that the child depends on the parent. A solid line is a direct dependency, a dashed line is an indirect dependency, through some hidden intermediate node. Some useful queries are:
Query language
The query language is a Javascript expression which produces true to include the row, and may call group to indicate grouping. You can use the standard Javascript operators (e.g. == and &&). Anything which takes a RegExp can also accept a string, which is then treated as a literal unanchored regular expression. The following functions are available:
group(x : string) : true - assign this item the given group. Multiple calls to group result in a space-separated name. The group name can also be set using name or command with captured regular expressions.leaf() : bool - is the rule a leaf, with no dependencies.run() : int - when was the rule last run, with 0 for run in the last tracked build, and higher numbers for run longer ago.run(x : int) : bool - equality against a run number, run(0) is equivalent to run() == 0.unchanged() : bool - last time the rule was built, did the value not change.slowestRule() : string - the name of the rule which took longest to build.name() : string - the name of the current rule.name(x : RegExp) : bool - a regular expression to match against the name of the current rule. If the regular expression contains captured patterns, these will be used as the groupname(x : RegExp, def : string) : true - a regular expression to match against the name of the current rule, including captured patterns for the group. If the regular expression does not match, the function will still return true but def will be used as the group.rename(from : string, to : string) : true - change name so any string from is replaced with to, useful for replacing an object directory (which is uninteresting) with something like $OBJ.rename(from : string) : true - rename using "" as the replacement string.command() : string - when matching rules this is the name of the first command the rule executed, or "" if the rule ran no commands. When matching commands this is the name of each command in turn.command(x : RegExp) : bool - a regular expression to match against any of the commands, including grouping as per name.command(x : RegExp, def : string) : true - works the same as the name function which takes two arguments.childOf(x : RegExp) : bool - is this rule a direct child of x, the rule for this item calls need/apply on x.descendantOf(x : RegExp) : bool - is this rule a descendant of x, a change in x will cause this rule to rebuild (ignoring unchanging rules).parentOf(x : RegExp) : bool - is this rule a direct parent of x, the rule for x calls need/apply on this item.ancestorOf(x : RegExp) : bool - is this rule an ancestor of x, a change in this rule will cause x to rebuild (ignoring unchanging rules).textColor(c : color) : true - set the color of this group to the given color, represented as a string - either the name of a color ("red") or a hex value ("#ff0000). If multiple textColor calls are given in one query, the last one will be used. If multiple different textColor values are given to one group, the group will not be colored.textColor(c : color, b : bool) : true - set the textColor of this group if the second argument is true.backColor(c : color) : true - like textColor but to set the background color.backColor(c : color, b : bool) : true - like textColor but to set the background color.