Re: documentation about AM_CPPFLAGS and VPATH builds

[Stefano Lattarini]

On Sunday 31 July 2011, Bruno Haible wrote:
> Hi,
>
Hi Bruno.  Thanks for the patch, and sorry for the delay.

> Paul and Jim approved the idea to give a recommendation about how to set up
> the -I options in AM_CPPFLAGS for dealing with VPATH builds.
> 
> Originally I wanted to document this in the Autoconf manual, but I didn't
> find the appropriate place: The Autoconf manual talks more about the CPPFLAGS
> variable as an environment variable, and is silent about how the user is meant
> to write his Makefile.in files.
> 
> So here's a proposal for the Automake manual.
>
> [1] http://lists.gnu.org/archive/html/bug-gnulib/2011-07/msg00443.html
> [2] http://lists.gnu.org/archive/html/bug-gnulib/2011-07/msg00448.html
>
I like your proposed addition, as it is clear and documents existing "best
practices".  I'll apply it by tomorrow or so if Ralf does not step in by
then.  I only have a couple of small nits (inlined below).

> 2011-07-30  Bruno Haible  <address@hidden>
> 
>       Document how to compose the -I options in AM_CPPFLAGS.
>       * doc/automake.texi (Program Variables): Recommend -I options to both
>       the build directory and the source directory when needed.
> 
> --- doc/automake.texi.orig    Sun Jul 31 02:35:24 2011
> +++ doc/automake.texi Sun Jul 31 02:34:29 2011
>
In general, I prefer patches formatted with "git format-patch": that makes
it much easier for me to apply them (ok, not in this particular case I
must admit; but you get my point).  Is there any reason why you're not
using "git format-patch"?

> @@ -6022,6 +6022,16 @@
>  @code{AM_CONFIG_HEADER}).  You can disable the default @option{-I}
>  options using the @option{nostdinc} option.
>  
> +When a file to be included is generated during the build and not part
> +of a distribution tarball, its location is under @code{$(builddir)},
> +not under @code{$(srcdir)}.  This matters for builds outside the source
> +tree (@pxref{VPATH Builds}).  Therefore we recommend to use a pair of
> address@hidden options: @samp{-Isome/subdir -I$(srcdir)/some/subdir}

> +or @samp{-I$(top_builddir)/some/subdir -I$(top_srcdir)/some/subdir}.
>
I'm not sure this sentence is truly warrented: it is redundant for someone
who has understood the principle you're exposing, and it is IMHO confusing
for someone who hasn't understood it yet.  But this might just be wrong
impression of mine, so I'll still keep the sentence if you still think it
useful.

> +Here the reference to the build tree should come before the reference
> +to the source tree, so that accidentally leftover generated files in
> +the source directory are ignored.
> +
>  @code{AM_CPPFLAGS} is ignored in preference to a per-executable (or
>  per-library) @code{_CPPFLAGS} variable if it is defined.
>  

Thanks,
  Stefano