automake-1.16: Unconfigured Subdirectories
7.2.4 Unconfigured Subdirectories
---------------------------------
The semantics of ‘DIST_SUBDIRS’ are often misunderstood by some users
that try to _configure and build_ subdirectories conditionally. Here by
configuring we mean creating the ‘Makefile’ (it might also involve
running a nested ‘configure’ script: this is a costly operation that
explains why people want to do it conditionally, but only the ‘Makefile’
is relevant to the discussion).
The above examples all assume that every ‘Makefile’ is created, even
in directories that are not going to be built. The simple reason is
that we want ‘make dist’ to distribute even the directories that are not
being built (e.g., platform-dependent code), hence ‘make dist’ must
recurse into the subdirectory, hence this directory must be configured
and appear in ‘DIST_SUBDIRS’.
Building packages that do not configure every subdirectory is a
tricky business, and we do not recommend it to the novice as it is easy
to produce an incomplete tarball by mistake. We will not discuss this
topic in depth here, yet for the adventurous here are a few rules to
remember.
• ‘SUBDIRS’ should always be a subset of ‘DIST_SUBDIRS’.
It makes little sense to have a directory in ‘SUBDIRS’ that is not
in ‘DIST_SUBDIRS’. Think of the former as a way to tell which
directories listed in the latter should be built.
• Any directory listed in ‘DIST_SUBDIRS’ and ‘SUBDIRS’ must be
configured.
That is, the ‘Makefile’ must exist or the recursive ‘make’ rules
will not be able to process the directory.
• Any configured directory must be listed in ‘DIST_SUBDIRS’.
This is so the cleaning rules remove the generated ‘Makefile’s. It
would be correct to see ‘DIST_SUBDIRS’ as a variable that lists all
the directories that have been configured.
In order to prevent recursion in some unconfigured directory you must
therefore ensure that this directory does not appear in ‘DIST_SUBDIRS’
(and ‘SUBDIRS’). For instance, if you define ‘SUBDIRS’ conditionally
using ‘AC_SUBST’ and do not define ‘DIST_SUBDIRS’ explicitly, it will be
default to ‘$(SUBDIRS)’; another possibility is to force ‘DIST_SUBDIRS =
$(SUBDIRS)’.
Of course, directories that are omitted from ‘DIST_SUBDIRS’ will not
be distributed unless you make other arrangements for this to happen
(for instance, always running ‘make dist’ in a configuration where all
directories are known to appear in ‘DIST_SUBDIRS’; or writing a
‘dist-hook’ target to distribute these directories).
In a few packages, unconfigured directories are not even expected to
be distributed. Although these packages do not require the
aforementioned extra arrangements, there is another pitfall. If the
name of a directory appears in ‘SUBDIRS’ or ‘DIST_SUBDIRS’, ‘automake’
will make sure the directory exists. Consequently ‘automake’ cannot be
run on such a distribution when one directory has been omitted. One way
to avoid this check is to use the ‘AC_SUBST’ method to declare
conditional directories; since ‘automake’ does not know the values of
‘AC_SUBST’ variables it cannot ensure the corresponding directory
exists.
Info Catalog
automake-1.16: Subdirectories with AC_SUBST
automake-1.16: Conditional Subdirectories