10.4 Built sources

Because Automake's automatic dependency tracking works as a side-effect of compilation (see section 9.14 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), either 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 on make all or make check 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 actually 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.

It might be important to emphasize that BUILT_SOURCES is honored only by make all and make check. This means you cannot build a specific target (e.g., make foo) in a clean tree if it depends on a built source. However if 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.

10.4.1 Built sources example

Several ways to handle built sources.