Unconfigured Subdirectories (automake)

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.
I.e., 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 Makefiles. 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.