Re: documentation about AM_CPPFLAGS and VPATH builds

[Bruno Haible]

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.

> > --- 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".

  - 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.).

  - Everyone has different preferences. For projects to which I contribute
    rarely, I can't remember each person's preferences.

Bruno
-- 
In memoriam Marie Trintignant <http://en.wikipedia.org/wiki/Marie_Trintignant>