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

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

[Michael Elizabeth Chastain]

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

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

[Eli Zaretskii]

> Date: Wed, 15 Jan 2003 12:43:40 -0600
> From: 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'.

Thanks.

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

This is approved, with the following comments/requests:

> +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.

I sugegst to use ``subdirectory'' instead of ``subordinate
directory'', like this:

  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 its subdirectories, you will
  configure only that subdirectory.

> +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.

Here, I suggest to use ``sibling directories'' as the collective term
for `bfd', `readline' and other subdirectories of gdb-VERSION.

It would also be nice to have some index entry for this text.  For
example:

  @cindex configuring @value{GDBN}, and source tree subdirectories

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

[Michael Elizabeth Chastain]

Hi Eli,

> I sugegst to use ``subdirectory'' instead of ``subordinate
> directory'', like this:

Done.  I had a ``subordinate'' lying around somewhere in my brain's
L1 cache.

mec> +In particular, if you run the first @code{configure} from the
mec> +@file{gdb} subordinate directory of the @file{gdb-@var{version-number}}
mec> +directory, you will omit the configuration of @file{bfd},
mec> +@file{readline}, and other subordinate directories.

eli> Here, I suggest to use ``sibling directories'' as the collective term
eli> for `bfd', `readline' and other subdirectories of gdb-VERSION.

I don't want to do this.

Documentation is for humans, not other computer programs.  Humans learn
by example.  When I write `bfd' and `readline', it's clear what I'm
talking about.  If I write `sibling directories', then the readers will
be confused.

Talking about `siblings of gdb' does not help because the directory name
`gdb' is already overloaded.  The whole section already talks about
`gdb-VERSION' and its subdirectories, including `gdb', but people still
run `configure' in the wrong directory and then come to us for help.

And I think there is no problem with getting specific about `bfd' and
`readline' because this section already specifically mentions these
names as subdirectories of `gdb-VERSION'.

> It would also be nice to have some index entry for this text.  For
> example:
> 
>   @cindex configuring @value{GDBN}, and source tree subdirectories

Done.

The CVS repository is not responding right now, so I can't make another
diff yet.

Michael C

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

[Eli Zaretskii]

On Wed, 15 Jan 2003, Michael Elizabeth Chastain wrote:

> mec> +In particular, if you run the first @code{configure} from the
> mec> +@file{gdb} subordinate directory of the @file{gdb-@var{version-number}}
> mec> +directory, you will omit the configuration of @file{bfd},
> mec> +@file{readline}, and other subordinate directories.
> 
> eli> Here, I suggest to use ``sibling directories'' as the collective term
> eli> for `bfd', `readline' and other subdirectories of gdb-VERSION.
> 
> I don't want to do this.
> 
> Documentation is for humans, not other computer programs.  Humans learn
> by example.  When I write `bfd' and `readline', it's clear what I'm
> talking about.  If I write `sibling directories', then the readers will
> be confused.
> 
> Talking about `siblings of gdb' does not help because the directory name
> `gdb' is already overloaded.  The whole section already talks about
> `gdb-VERSION' and its subdirectories, including `gdb', but people still
> run `configure' in the wrong directory and then come to us for help.
> 
> And I think there is no problem with getting specific about `bfd' and
> `readline' because this section already specifically mentions these
> names as subdirectories of `gdb-VERSION'.

I think I didn't explain myself clearly, because I didn't mean to ask to 
remove the names `bfd' and `readline'.  I was just suggesting to say 
something like this:

   [...] you will omit the configuration of @file{bfd},
   @file{readline}, and other sibling directories of the `gdb'
   subdirectory.

Thanks.

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

[Michael Elizabeth Chastain]

Hi Eli,

   [...] you will omit the configuration of @file{bfd},
   @file{readline}, and other sibling directories of the `gdb'
   subdirectory.

Ah, that's cool.  As long as I can keep the `bfd' and `readline'
I am happy.

Draft #2 to follow shortly.

Michael C