Hi Ralf. This patch seems useful to me (but note that IMO, in this matter, a review by an automake newbie would be much more valuable than mine).
Still, I have a couple of nits below. On Wednesday 09 February 2011, Ralf Wildenhues wrote: > 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 > > > +@node Adding a Makefile.am > +@section Adding a @file{Makefile.am} to an existing project > +@cindex adding @file{Makefile.am} > +@cindex @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? > + What about using @display, like is done for sections "Per-Object Flags Emulation" and "Installing to Hard-Coded Locations" above? > +In general, it takes three steps: > + > +@itemize > +@item > +Write the @file{sub/foo/Makefile.am} file itself. > + > +@item > +In a recursive @file{Makefile} project, edit the next higher-up > +@file{Makefile.am} 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}: > + > +@example > +## sub/Makefile.am > +SUBDIRS = ... > + > +SUBDIRS += foo > +@end example > + > +@noindent > +or add @file{sub/foo} to the @samp{SUBDIRS} variable in the toplevel > +@file{Makefile.am} 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}: > + > +@example > +## toplevel Makefile.am > +... > +include sub/foo/Makefile.am > +@end example > + > +@noindent > +Note that in this case you also need to use the relative subdir prefixes > +in file names used inside the fragment file (@pxref{Alternative}). > + Hmm... information overloading here? I mean, if a user is employing a non-recursive setup, my guess is that he knows he has to add a proper `include' to the top-level makefile. Plus, in this case ... > +@item > +Add the line @code{AC_CONFIG_FILES([sub/foo/Makefile])} to the > +@file{configure.ac} file (@pxref{Requirements}). > +@end itemize > + ... he won't need to add this line to configure.ac. IMVHO this FAQ entry makes real sense only about recursive setups -- and maybe the question might even be modified to read e.g.: What do I need to do when I want to add a @file{sub/foo/Makefile.am} to an existing project (in a recursive @file{Makefile} setup)? WDYT? > +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} > + Why not just "@command{autoreconf}" here? The user should be assumed to know which options he wants to employ (for example, I tend to use `autoreconf -vi', not just `autoreconf -v'). Also, what about projects using a custom `autogen.sh' script? Should the documentation cater to them too, or would that just be distracting (or an information overload)? > +in the toplevel source directory. @xref{amhello Explained}, for a > + small but complete example package. > + > + > @node Reporting Bugs > @section Reporting Bugs > Regards, Stefano
