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.

diff --git a/ChangeLog b/ChangeLog
index 63ae2200f71a1a2b5ad2e8c2946e21d617141d93..8d5e33af6a3769674c74f084cb934c587b0fe47a 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,9 @@
+2011-08-03  Bruno Haible  <bruno@clisp.org>
+
+       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  <stefano.lattarini@gmail.com>
 
        tests: relax a test on amhello examples to cater to Solaris tar

diff --git a/doc/automake.texi b/doc/automake.texi
index e1864892219df41c2bb089da94e5982dd77d4a6c..49a6cd1547d428cc6e9f038dcbdb0409537b03b6 100644 (file)
--- 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.,
+@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.
+
 @code{AM_CPPFLAGS} is ignored in preference to a per-executable (or
 per-library) @code{_CPPFLAGS} variable if it is defined.