documentation about AM_CPPFLAGS and VPATH builds

[Bruno Haible]

Hi,

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


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
@@ -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
address@hidden(top_builddir)/some/subdir -I$(top_srcdir)/some/subdir}.
+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.
 

-- 
In memoriam Ebrahim Berookhim 
<http://www.jewishjournal.com/iranianamericanjews/item/conversations_about_berookhims_execution_30_years_ago_in_iran/>