(automake-1.16.info)Unconfigured Subdirectories

---

Prev: Subdirectories with AC_SUBST Up: Conditional Subdirectories

---

Enter node , (file) or (file)node

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 exists or the recursive ‘make’ rules will
     not be able to process the directory.
   • Any configured directory must be listed in ‘DIST_SUBDIRS’.

     So that 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 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.