Re: documentation about AM_CPPFLAGS and VPATH builds

[Stefano Lattarini]

Attached is what I've finally pushed in Bruno's name.  Both the
generated HTML and PDF look good to me.

Thanks again to Bruno and to all the other people involved in the
creation of this patch.

Regards,
  Stefano

From 5d4dc886c0863ed2a4fdec933a1bded31402094b Mon Sep 17 00:00:00 2001
Message-Id: <address@hidden>
From: Bruno Haible <address@hidden>
Date: Wed, 3 Aug 2011 15:05:22 +0200
Subject: [PATCH] docs: how to use '-I' option in AM_CPPFLAGS for best VPATH 
support

* doc/automake.texi (Program Variables): Recommend -I options to
both the build directory and the source directory when needed.
---
 ChangeLog         |    6 ++++++
 doc/automake.texi |   12 ++++++++++++
 2 files changed, 18 insertions(+), 0 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 63ae220..8d5e33a 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,9 @@
+2011-08-03  Bruno Haible  <address@hidden>
+
+       docs: how to use '-I' option in AM_CPPFLAGS for best VPATH support
+       * doc/automake.texi (Program Variables): Recommend -I options to
+       both the build directory and the source directory when needed.
+
 2011-07-23  Stefano Lattarini  <address@hidden>
 
        tests: relax a test on amhello examples to cater to Solaris tar
diff --git a/doc/automake.texi b/doc/automake.texi
index e186489..49a6cd1 100644
--- a/doc/automake.texi
+++ b/doc/automake.texi
@@ -6036,6 +6036,18 @@ the C preprocessor.  In particular it generates 
@samp{-I.},
 @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 especially for packages that
+use header files placed in sub-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.,
address@hidden/subdir -I$(srcdir)/some/subdir} or
address@hidden(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.
+
 @code{AM_CPPFLAGS} is ignored in preference to a per-executable (or
 per-library) @code{_CPPFLAGS} variable if it is defined.
 
-- 
1.7.2.3