Re: Documentation for conditional SUBDIRS (+ test cases)

[Bruce Korb]

Alexandre Duret-Lutz wrote:

> I'm including the text version of this section in addition to
> the patch; It'll be easier to read and comment.

That's true ;-)

> What do you think of it?  Is there anything that should be
> corrected/clarified?

My comments below.   Can I have comments vis-a-vis:

  http://autogen.sf.net/blocksort.html  :-)

> The patch also add test cases for the two solutions presented
> (there were no checks for DIST_SUBDIRS in the test suite).

Great!

> --->8--->8--->8--->8--->8--->8---
> 
> The top-level `Makefile.am'
> ***************************
> 
> Recursing subdirectories
> ========================
> 
>    In packages with subdirectories, the top level `Makefile.am' must
> tell Automake which subdirectories are to be built.  This is done via
> the `SUBDIRS' variable.
> 
>    The `SUBDIRS' variable holds a list of subdirectories in which
> building of various sorts can occur.

CAVEAT:  the list must *not* include the AC_CONFIG_AUX_DIR() directory,
if used.  There are horrible, unexplained failures if you do.
<< leastwise, it happens that way to me.  The problem appeared
   when I added that directory to SUBDIRS and went away when I
   removed it.  But I was adding and removing Makefile from
   AC_CONFIG_FILES at the same time.  There *is* a problem, but
   I guess I should isolate which it is.>>

> [[...]]  The directories mentioned in
> `SUBDIRS' must be direct children of the current directory.  For
> instance, you cannot put `src/subdir' into `SUBDIRS'.

<< at this point I would like to see either mention of how to handle
   sub-subdirectories, or else a link to such a discussion. >>

>    The use of `SUBDIRS' is not restricted to just the top-level
> `Makefile.am'.  Automake can be used to construct packages of arbitrary
> depth.

<< now I'm confused. >>

>    By default, Automake generates `Makefiles' which work depth-first
> (`postfix').  However, it is possible to change this ordering.  You can
> do this by putting `.' into `SUBDIRS'.  For instance, putting `.'
> first will cause a `prefix' ordering of directories.  All `clean'
> targets are run in reverse order of build targets.

<< This is a poor design, but likely not at issue here.  The action
   is being made as a side-effect of doing something not really related.
   I would suggest using the normal mechanism for telling automake
   about what/how things need to be done.  e.g.:

      AM_DEPTH_FIRST = true  >>

> Conditional subdirectories
> ==========================
> 
>    It is possible to define the `SUBDIRS' variable conditionally if,
> like in the case of GNU `Inetutils', you want to only build a subset of
> the entire package.
> 
>    To illustrate how this works, let's assume we have two directories
> `src/' and `opt/'.  `src/' should always be built, but we want to
> decide in `./configure' whether `opt/' will be built or not.  (For this
> example we will assume that `opt/' should be built when the variable
> `$want_opt' was set to `yes'.)
> 
>    Running `make' should thus recurse into `src/' always, and then
> maybe in `opt/'.
> 
>    However `make dist' should always recurse into both `src/' and
> `opt/'.  Because `opt/' should be distributed even if it is not needed
> in the current configuration. This means `opt/Makefile' should be
> created unconditionally.  (1)
> 
>    There is two ways to setup a project like this.  You can use Automake
           ^^ are
> conditionals (*note Conditionals::) or use Autoconf `AC_SUBST'
> variables (*note Setting Output Variables: (autoconf)Setting Output
> Variables.).  Automake conditionals is the preferred solution.
               ^ Using

> Conditional subdirectories with `AM_CONDITIONAL'
> ------------------------------------------------
> 
>    `configure' should output the `Makefile' for each directory and
> define a condition into which `opt/' should be built.
> 
>      ...
>      AM_CONDITIONAL([COND_OPT], [test "$want_opt" = yes])
>      AC_CONFIG_FILES([Makefile src/Makefile opt/Makefile])
>      ...
> 
>    Then `SUBDIRS' can be defined in the top-level `Makefile.am' as
> follows.
> 
>      if COND_OPT
>        MAYBE_OPT = opt
>      endif
>      SUBDIRS = src $(MAYBE_OPT)
> 
>    As you can see, running `make' will rightly recurse into `src/' and
> maybe `opt/'.
> 
>    As you can't see, running `make dist' will recurse into both `src/'
                                               ^ always
> and `opt/', always.  How comes?  Because `make dist', unlike `make',
            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ directories because      ^ all
> doesn't use the `SUBDIRS' variable, it uses the `DIST_SUBDIRS' variable
                                    ^^^^ .  It
> instead.
  xxxxxxx  <<omit -- "unlike" and "instead" imply the same thing.>>

>    In this case Automake will define `DIST_SUBDIRS = src opt'
> automatically because it knows that `MAYBE_OPT' can contain `opt' in
> some condition.
> 
>    The `DIST_SUBDIRS' variable will also be used when the user runs
> `make distclean' or `make maintainer-clean'.

<< It sounds like we need a table of standard targets and which
   SUBDIRS variable gets used, and a discussion of how DIST_SUBDIRS
   gets derived >>

> Conditional subdirectories with `AC_SUBST'
> ------------------------------------------
> 
>    Another idea is to define `MAYBE_OPT' from `./configure' using
> `AC_SUBST':
> 
>      ...
>      if test "$want_opt" = yes; then
>        MAYBE_OPT=opt
>      else
>        MAYBE_OPT=
>      fi
>      AC_SUBST([MAYBE_OPT])
>      AC_CONFIG_FILES([Makefile src/Makefile opt/Makefile])
>      ...
> 
>    In this case the top-level `Makefile.am' should look as follows.
> 
>      SUBDIRS = src $(MAYBE_OPT)
>      DIST_SUBDIRS = src opt
> 
>    The drawback is that since Automake cannot guess what the possible
> values of `MAYBE_OPT' are, we have to define `DIST_SUBDIRS' ourselves.
                             ^^^^^^^ it is necessary          xxxxxxxxx