cpp.texi: Clarify documentation of relationship between #line and #include.

	* doc/cpp.texi: Clarify documentation of relationship between
	#line and #include.

From-SVN: r50208

diff --git a/gcc/ChangeLog b/gcc/ChangeLog
index 99924569a42e163cd11287d0a14d4bfbc8459847..01f34607f044ea691e51e269b4be52aab3559fba 100644 (file)
--- a/gcc/ChangeLog
+++ b/gcc/ChangeLog
@@ -1,3 +1,8 @@
+2002-03-01  Zack Weinberg  <zack@codesourcery.com>
+
+       * doc/cpp.texi: Clarify documentation of relationship between
+       #line and #include.
+
 Don Feb 28 16:46:03 CET 2002  Jan Hubicka  <jh@suse.cz>
 
        * i386.h (HARD_REGNO_RENAME_OK): Define.

diff --git a/gcc/doc/cpp.texi b/gcc/doc/cpp.texi
index c299e09e6031e48545948e41344ffaad47a31092..a6b39531d951f19238bf61b40237cbf6871185c3 100644 (file)
--- a/gcc/doc/cpp.texi
+++ b/gcc/doc/cpp.texi
@@ -3029,7 +3029,35 @@ The result should match one of the above two forms.
 @samp{#line} directives alter the results of the @code{__FILE__} and
 @code{__LINE__} predefined macros from that point on.  @xref{Standard
 Predefined Macros}.  They do not have any effect on @samp{#include}'s
-idea of the directory containing the current file.
+idea of the directory containing the current file.  This is a change
+from GCC 2.95.  Previously, a file reading
+
+@smallexample
+#line 1 "../src/gram.y"
+#include "gram.h"
+@end smallexample
+
+would search for @file{gram.h} in @file{../src}, then the @option{-I}
+chain; the directory containing the physical source file would not be
+searched.  In GCC 3.0 and later, the @samp{#include} is not affected by
+the presence of a @samp{#line} referring to a different directory.
+
+We made this change because the old behavior caused problems when
+generated source files were transported between machines.  For instance,
+it is common practice to ship generated parsers with a source release,
+so that people building the distribution do not need to have yacc or
+Bison installed.  These files frequently have @samp{#line} directives
+referring to the directory tree of the system where the distribution was
+created.  If GCC tries to search for headers in those directories, the
+build is likely to fail.
+
+The new behavior can cause failures too, if the generated file is not
+in the same directory as its source and it attempts to include a header
+which would be visible searching from the directory containing the
+source file.  However, this problem is easily solved with an additional
+@option{-I} switch on the command line.  The failures caused by the old
+semantics could sometimes be corrected only by editing the generated
+files, which is difficult and error-prone.
 
 @node Pragmas
 @chapter Pragmas
@@ -3765,6 +3793,14 @@ were still available in traditional mode.  It is now a separate program
 and does not implement any of the GNU extensions, except for a partial
 implementation of assertions.  Even those may be removed in a future
 release.
+
+@item @samp{#line} and @samp{#include}
+
+The @samp{#line} directive used to change GCC's notion of the
+``directory containing the current file,'' used by @samp{#include} with
+a double-quoted header file name.  In 3.0 and later, it does not.
+@xref{Line Control}, for further explanation.
+
 @end itemize
 
 @node Invocation