[PATCH] {maint} docs: recursive make considered harmful

[Stefano Lattarini]

In the documentation, we shouldn't confuse "packages using subdirectories"
with "packages using recursive make invocations".  A package can have a
careful organization in subdirectories, make no (or almost no) use of make
recursion (examples of such packages are GNU bison, GNU cppi, and Automake
itself).

In fact, make recursion should be used as seldom as possible, because it
makes the build system more brittle and dependency declarations less
faithful.  See Peter Miller's article "Recursive Make Considered Harmful"
for more a more in-depth discussion:

    http://miller.emu.id.au/pmiller/books/rmch/

* doc/automake.texi (Directories): Clarify how a build system based on
make recursion does.  Observe that such a system, albeit being very
widespread, has its own issues and drawbacks, and that one can have a
non-recursive setup also for projects using complex directory layout.
(Recursing subdirectories): Speak of "packages that use make recursion"
rather than of "packages with subdirectories".

Signed-off-by: Stefano Lattarini <address@hidden>
---

 I plan to push this by tomorrow.  Reviews welcome.

 Regards,
   Stefano

 doc/automake.texi |   31 +++++++++++++++++++++----------
 1 file changed, 21 insertions(+), 10 deletions(-)

diff --git a/doc/automake.texi b/doc/automake.texi
index 222f9ec..536c61c 100644
--- a/doc/automake.texi
+++ b/doc/automake.texi
@@ -4183,13 +4183,25 @@ For simple projects that distribute all files in the 
same directory
 it is enough to have a single @file{Makefile.am} that builds
 everything in place.
 
-In larger projects it is common to organize files in different
-directories, in a tree.  For instance one directory per program, per
-library or per module.  The traditional approach is to build these
-subdirectories recursively: each directory contains its @file{Makefile}
-(generated from @file{Makefile.am}), and when @command{make} is run
-from the top level directory it enters each subdirectory in turn to
-build its contents.
+In larger projects, it is common to organize files in different
+directories, in a tree.  For example, there could be a directory
+for the program's source, one for the testsuite, and one for the
+documentation; or, for very large projects, there could be one
+directory per program, per library or per module.
+
+The traditional approach is to build these subdirectories recursively,
+employing @emph{make recursion}: each directory contains its
+own @file{Makefile}, and when @command{make} is run from the top-level
+directory, it enters each subdirectory in turn, and invokes there a
+new @command{make} instance to build the directory's contents.
+
+Because this approach is very widespread, Automake offers built-in
+support for it.  However, it is worth nothing that the use of make
+recursion has its own serious issues and drawbacks, and that it's
+well possible to have packages with a multi directory layout that
+make little or no use of such recursion (examples of such packages
+are GNU Bison and GNU Automake itself); see also the @ref{Alternative}
+section below.
 
 @menu
 * Subdirectories::              Building subdirectories recursively
@@ -4203,7 +4215,7 @@ build its contents.
 
 @cindex @code{SUBDIRS}, explained
 
-In packages with subdirectories, the top level @file{Makefile.am} must
+In packages using make recursion, the top level @file{Makefile.am} must
 tell Automake which subdirectories are to be built.  This is done via
 the @code{SUBDIRS} variable.
 @vindex SUBDIRS
@@ -4484,7 +4496,7 @@ variables it cannot ensure the corresponding directory 
exists.
 If you've ever read Peter Miller's excellent paper,
 @uref{http://miller.emu.id.au/pmiller/books/rmch/,
 Recursive Make Considered Harmful}, the preceding sections on the use of
-subdirectories will probably come as unwelcome advice.  For those who
+make recursion will probably come as unwelcome advice.  For those who
 haven't read the paper, Miller's main thesis is that recursive
 @command{make} invocations are both slow and error-prone.
 
@@ -4494,7 +4506,6 @@ believe.  This work is new and there are probably warts.
 to write a single @file{Makefile.am} for a complex multi-directory
 package.
 
-
 By default an installable file specified in a subdirectory will have its
 directory name stripped before installation.  For instance, in this
 example, the header file will be installed as
-- 
1.7.9.5