Re: documentation about AM_CPPFLAGS and VPATH builds

[Stefano Lattarini]

On Tuesday 02 August 2011, Bruno Haible wrote:
> Hi Stefano,
> 
> > > +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.
> 
> Often people don't want to understand abstract principles, but just want to
> know whether their AM_CPPFLAGS value is correct. Such as in
> 
> AM_CPPFLAGS = -I.. -I$(srcdir)/.. -I$(srcdir)/../../include \
>         -I$(srcdir)/../../intl -I../../intl
> 
> (taken from binutils-2.20.1/bfd/doc/Makefile.am) or
> 
> AM_CPPFLAGS = -I../lib -I$(top_srcdir)/lib
> 
> (taken from diffutils-2.8.4/src/Makefile.am) or
> 
> AM_CPPFLAGS = -I$(top_srcdir)/lib -I../lib
> 
> (taken from m4-1.4.10/src/Makefile.am).
> 
> If you find something confusing, please change or add to the text, sure.
>
What about this slightly extended text?  I'll wait at least until tomorrow
before pushing, since I'd like to hear your opinion on this.

  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 especially for packages that
  use header files placed in sub- or super-directories and want to allow
  builds outside the source tree (@pxref{VPATH Builds}). In that case we
  recommend to use a pair of @option{-I} options, such as, e.g.,
  @samp{-Isome/subdir -I$(srcdir)/some/subdir} or
  @samp{-I$(top_builddir)/some/subdir -I$(top_srcdir)/some/subdir}.
  Note that 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.

> > > --- 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"?
> 
> I'm not using "git format-patch" usually because
> 
>   - Different projects use different SCMs. I imagine I would annoy people
>     who use 'hg' or 'cvs' if I send them a git formatted patch.
>
>   - If I include a ChangeLog change in the git formatted patch, then if
>     the receiver does not have git-merge-changelog installed, "git am"
>     fails just because it can't apply the ChangeLog part. Whereas if
>     I don't include a ChangeLog change, some people say "please provide
>     a ChangeLog entry next time".
>
Well, I have git-merge-changelog installed; and in fact I coulnd't live
easily without it anymore ;-)

>   - The likelihood is high that you will change something in my proposed
>     patch. Maybe only the date of ChangeLog entry. The effort to do so
>     is higher when you applied a complete git-formatted patch (you need
>     to use "git commit --amend" etc.).
>
I disagree on this.  I find it much, much easier to amend patches using
"git commit --amend" than in any other way.  In fact, that is one of the
git commands I use most frequently, even for solo work.

>   - Everyone has different preferences. For projects to which I contribute
>     rarely, I can't remember each person's preferences.
>
This is a good point.  Let's say that, if any problem arises, I'll just
ask you to "please provide a patch created with 'git format-patch'".

Thanks,
  Stefano