Re: troubles with autotools

[Stefano Lattarini]

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
>  
>  
> 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?
> +
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:
> +
> 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}).
> +
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 ...
> address@hidden
> +Add the line @code{AC_CONFIG_FILES([sub/foo/Makefile])} to the
> address@hidden file (@pxref{Requirements}).
> address@hidden 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