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