troubles with autotools

[Ralf Wildenhues]

Hello Laura, automake-patches readers,

I help maintain autotools, and I've seen your blog
http://programmermusings.blogspot.com/2011/02/new-gstreamer-plugin.html
and while I can sympathize with you for the steep learning curve that
autotools unfortunately have, let's try to improve things.

So, a couple of questions: would the new FAQ entry below have helped?
If not, what is unclear about it, what should be changed?  Second, OK to
add your name and email to THANKS when committing the patch?

Third, please be encouraged to ask questions on the automake at gnu.org
mailing list.  We do expect users to become better over time in
searching list archives before asking, and gain understanding, but
initially we do try to be helpful even to complete newcomers.

Last but not least, I would like to use the image from your blog post
maybe in a future talk.  Did you create it, can I used it, are there
strings attached to it?

Others, do you see any issues with the patch?

Thanks,
Ralf

    Add FAQ entry about adding a new directory to an existing project.
    
    * doc/automake.texi (FAQ, Adding a Makefile.am): New FAQ section.
    * THANKS: Update.
    Prompted by a blog entry from Laura Lucas Alday.

diff --git a/doc/automake.texi b/doc/automake.texi
index 3af5201..ee73092 100644
--- a/doc/automake.texi
+++ b/doc/automake.texi
@@ -354,6 +354,7 @@ Top
 * Multiple Outputs::            Writing rules for tools with many output files
 * Hard-Coded Install Paths::    Installing to hard-coded locations
 * Debugging Make Rules::        Strategies when things don't work as expected
+* Adding a Makefile.am::        Adding a Makefile.am to an existing project
 * Reporting Bugs::              Feedback on bugs and feature requests
 
 History of Automake
@@ -10524,6 +10525,7 @@ FAQ
 * Multiple Outputs::            Writing rules for tools with many output files
 * Hard-Coded Install Paths::    Installing to hard-coded locations
 * Debugging Make Rules::        Strategies when things don't work as expected
+* Adding a Makefile.am::        Adding a Makefile.am to an existing project
 * Reporting Bugs::              Feedback on bugs and feature requests
 @end menu
 
@@ -11919,6 +11921,64 @@ Debugging Make Rules
 @end itemize
 
 
address@hidden Adding a Makefile.am
address@hidden Adding a @file{Makefile.am} to an existing project
address@hidden adding @file{Makefile.am}
address@hidden @file{Makefile.am}, adding
+
+What do I need to do when I want to add a @file{sub/foo/Makefile.am} to
+an existing project?
+
+In general, it takes three steps:
+
address@hidden
address@hidden
+Write the @file{sub/foo/Makefile.am} file itself.
+
address@hidden
+In a recursive @file{Makefile} project, edit the next higher-up
address@hidden and add the relative directory in its @samp{SUBDIRS};
+i.e., in this case, either add @file{foo} to the @samp{SUBDIRS} variable
+in @file{sub/Makefile.am}:
+
address@hidden
+## sub/Makefile.am
+SUBDIRS = ...
+
+SUBDIRS += foo
address@hidden example
+
address@hidden
+or add @file{sub/foo} to the @samp{SUBDIRS} variable in the toplevel
address@hidden if there is no intermediate @file{sub/Makefile.am}
+(@pxref{Subdirectories}).
+
+In a nonrecursive @file{Makefile} project, depending on local
+convention, you would probably write a fragment file to be included in
+the toplevel @file{Makefile.am}:
+
address@hidden
+## toplevel Makefile.am
+...
+include sub/foo/Makefile.am
address@hidden example
+
address@hidden
+Note that in this case you also need to use the relative subdir prefixes
+in file names used inside the fragment file (@pxref{Alternative}).
+
address@hidden
+Add the line @code{AC_CONFIG_FILES([sub/foo/Makefile])} to the
address@hidden file (@pxref{Requirements}).
address@hidden itemize
+
+Then, rerunning @command{make} in the build directory should do the
+right thing unless you have rebuild rules disabled
+(@pxref{maintainer-mode}); alternatively, run @command{autoreconf -v} in
+the toplevel source directory.  @xref{amhello Explained}, for a small
+but complete example package.
+
+
 @node Reporting Bugs
 @section Reporting Bugs