Chapter 26. Troubleshooting

The experience of configuring any
software build tool to build a large code base
usually, at some point,
involves trying to figure out why
the tool is behaving a certain way,
and how to get it to behave the way you want.
SCons is no different.
This appendix contains a number of
different ways in which you can
get some additional insight into SCons' behavior.

Note that we're always interested in trying to
improve how you can troubleshoot configuration problems.
If you run into a problem that has
you scratching your head,
and which there just doesn't seem to be a good way to debug,
odds are pretty good that someone else will run into
the same problem, too.
If so, please let the SCons development team know
(preferably by filing a bug report
or feature request at our project pages at tigris.org)
so that we can use your feedback
to try to come up with a better way to help you,
and others, get the necessary insight into SCons behavior
to help identify and fix configuration issues.

In this example,
the underlying cause is obvious:
we've intentionally misspelled the output file name
in the cp command,
so the command doesn't actually
build the file.out file that we've told SCons to expect.
But if the problem weren't obvious,
it would be helpful
to specify the --debug=explain option
on the command line
to have SCons tell us very specifically
why it's decided to rebuild the target:

If this had been a more complicated example
involving a lot of build output,
having SCons tell us that
it's trying to rebuild the target file
because it doesn't exist
would be an important clue
that something was wrong with
the command that we invoked to build it.

The --debug=explain option also comes in handy
to help figure out what input file changed.
Given a simple configuration that builds
a program from three source files,
changing one of the source files
and rebuilding with the --debug=explain
option shows very specifically
why SCons rebuilds the files that it does:

This becomes even more helpful
in identifying when a file is rebuilt
due to a change in an implicit dependency,
such as an incuded .h file.
If the file1.c
and file3.c files
in our example
both included a hello.h file,
then changing that included file
and re-running SCons with the --debug=explain option
will pinpoint that it's the change to the included file
that starts the chain of rebuilds:

(Note that the --debug=explain option will only tell you
why SCons decided to rebuild necessary targets.
It does not tell you what files it examined
when deciding not
to rebuild a target file,
which is often a more valuable question to answer.)