Because Automake’s automatic dependency tracking works as a side-effect of compilation (see Automatic dependency tracking) there is a bootstrap issue: a target should not be compiled before its dependencies are made, but these dependencies are unknown until the target is first compiled.
Ordinarily this is not a problem, because dependencies are distributed
sources: they preexist and do not need to be built. Suppose that
foo.c includes foo.h. When it first compiles
foo.o, make only knows that foo.o depends on
foo.c. As a side-effect of this compilation depcomp
records the foo.h dependency so that following invocations of
make will honor it. In these conditions, it’s clear there is
no problem: either foo.o doesn’t exist and has to be built
(regardless of the dependencies), or accurate dependencies exist and
they can be used to decide whether foo.o should be rebuilt.
It’s a different story if foo.h doesn’t exist by the first
make run. For instance, there might be a rule to build
foo.h. This time file.o’s build will fail because the
compiler can’t find foo.h. make failed to trigger the
rule to build foo.h first by lack of dependency information.
The BUILT_SOURCES variable is a workaround for this problem. A
source file listed in BUILT_SOURCES is made when ‘make
all’, ‘make check’, ‘make install’, ‘make install-exec’
(or make dist) is run, before other targets are processed.
However, such a source file is not compiled unless explicitly
requested by mentioning it in some other _SOURCES variable.
So, to conclude our introductory example, we could use ‘BUILT_SOURCES = foo.h’ to ensure foo.h gets built before any other target (including foo.o) during ‘make all’ or ‘make check’.
BUILT_SOURCES is a bit of a misnomer, as any file which must be
created early in the build process can be listed in this variable.
Moreover, all built sources do not necessarily have to be listed in
BUILT_SOURCES. For instance, a generated .c file
doesn’t need to appear in BUILT_SOURCES (unless it is included
by another source), because it’s a known dependency of the associated
object.
To emphasize, BUILT_SOURCES is honored only by ‘make all’,
‘make check’, ‘make install’, and make install-exec
(and ‘make dist’). This means you cannot build an arbitrary
target (e.g., ‘make foo’) in a clean tree if it depends on a
built source. However it will succeed if you have run ‘make all’
earlier, because accurate dependencies are already available.
The next section illustrates and discusses the handling of built sources on a toy example.