Raises an errorCommand line does the wrong thingWeird things are rebuilding

Debugging

This page discusses how to debug a Shake-based build system – how to determine why it is going wrong. The page is presented as a series of common problems and how they can be investigated. The common techniques for solving any Shake problem are:

Raises an error

Most Shake errors are formatted as:

Error when running Shake build system:
* stack_element1.txt
* stack_eLement2.txt
* real_file.o
Error, rule failed to build file:
  real_rile.o

The lines starting with * provide a stack trace, where stack_element1.txt depended on stack_element2.txt, which in turn depended on and ran the rule for real_file.o. The specific error in this example is that the rule for producing real_file.o failed to actually create the file - either the file was not created, or was creating in the wrong place.

All Shake errors contain the dependency stack, which is usually the most important thing about diagnosing an error. Often the first step is to map the bottom entry on the stack to the rule that executes to produce it - e.g. *.o or similar.

Some typical errors you may encounter are:

Command line does the wrong thing

Since build systems typically spend most of their time calling out to command line tools, much of the debugging effort is around getting these tools to behave properly. The easiest way to debug a system command is to avoid it entirely - tools like rm, cat and sed can usually be replaced with Haskell code, which can fix issues and improve portability.

The first step to debugging a command line tool is to reproduce the error outside of Shake, typically by passing -v to see the command line and pasting it into a shell. Unfortunately all the platform abstractions can sometimes get in the way, in particular pay attention to:

Alas, each tool is different, and all present unique challenges. Where possible copy the command lines from other systems, rather than trying to rediscover this arcane knowledge.

Weird things are rebuilding

See the HTML Profile Reports, which provide overviews of dependencies. These can be mined to figure out the causes of rebuilding.