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