[rfc] README, doc/gdb.texinfo: warn against '.../configure/gdb-N.N/gdb/configure'

[Michael Elizabeth Chastain <mec@shout.net>]

Here is the first draft of some new doco about the difference
between '.../gdb-5.3/configure' and '.../gdb-5.3/gdb/configure'.

I don't expect this to get approved on the first round, although
that would be nice.

Testing: I tested the wrong way (.../gdb-5.3/gdb/configure) with gdb
HEAD%20030104 on native i686-pc-linux-gnu and observed the build error
that I documented.  This build error happens a lot sooner with the
new configury, which is nice.  I also did a full build + install
the right way to verify that makeinfo is happy with my input.

Comments please?

Michael C

Index: README
===================================================================
RCS file: /cvs/src/src/gdb/README,v
retrieving revision 1.24
diff -u -r1.24 README
--- README	13 Jan 2003 23:25:55 -0000	1.24
+++ README	15 Jan 2003 17:52:49 -0000
@@ -69,7 +69,20 @@
 `configure' can't determine your system type, specify one as its
 argument, e.g., `./configure sun4' or `./configure decstation'.
 
-   If you get compiler errors during this stage, see the `Reporting
+   Make sure that your 'configure' line ends in 'gdb-5.3/configure':
+
+      /berman/migchain/source/gdb-5.3/configure      # RIGHT
+      /berman/migchain/source/gdb-5.3/gdb/configure  # WRONG
+
+   The gdb package contains several subdirectories, such as 'gdb',
+'bfd', and 'readline'.  If your 'configure' line ends in
+'gdb-5.3/gdb/configure', then you are configuring only the gdb
+subdirectory, not the whole gdb package.  This leads to build errors
+such as:
+
+      make: *** No rule to make target `../bfd/bfd.h', needed by `gdb.o'.  Stop.
+
+   If you get other compiler errors during this stage, see the `Reporting
 Bugs' section below; there are a few known problems.
 
    GDB requires an ISO C (ANSI C) compiler.  If you do not have an ISO
Index: doc/gdb.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
retrieving revision 1.137
diff -u -r1.137 gdb.texinfo
--- doc/gdb.texinfo	13 Jan 2003 17:59:49 -0000	1.137
+++ doc/gdb.texinfo	15 Jan 2003 17:53:04 -0000
@@ -14148,19 +14148,15 @@
 creates configuration files for every directory level underneath (unless
 you tell it not to, with the @samp{--norecursion} option).
 
-You can run the @code{configure} script from any of the
-subordinate directories in the @value{GDBN} distribution if you only want to
-configure that subdirectory, but be sure to specify a path to it.
-
-For example, with version @value{GDBVN}, type the following to configure only
-the @code{bfd} subdirectory:
-
-@smallexample
-@group
-cd gdb-@value{GDBVN}/bfd
-../configure @var{host}
-@end group
-@end smallexample
+You should run the @code{configure} script from the top directory in
+the source tree, the @file{gdb-@var{version-number}} directory.  If you
+run @code{configure} from one of the subordinate directories, you will
+configure only that directory.  That is usually not what you want.
+In particular, if you run the first @code{configure} from the
+@file{gdb} subordinate directory of the @file{gdb-@var{version-number}}
+directory, you will omit the configuration of @file{bfd},
+@file{readline}, and other subordinate directories.  This leads to
+build errors about missing include files such as @file{bfd/bfd.h}.
 
 You can install @code{@value{GDBP}} anywhere; it has no hardwired paths.
 However, you should make sure that the shell on your path (named by
@@ -14212,6 +14208,12 @@
 the example, you'd find the Sun 4 library @file{libiberty.a} in the
 directory @file{gdb-sun4/libiberty}, and @value{GDBN} itself in
 @file{gdb-sun4/gdb}.
+
+Make sure that your path to the @file{configure} script has just one
+instance of @file{gdb} in it.  If your path to @file{configure} looks
+like @file{../gdb-@value{GDBVN}/gdb/configure}, you are configuring only
+one subdirectory of @value{GDBN}, not the whole package.  This leads to
+build errors about missing include files such as @file{bfd/bfd.h}.
 
 One popular reason to build several @value{GDBN} configurations in separate
 directories is to configure @value{GDBN} for cross-compiling (where