[binutils-gdb] gdb/doc: some more details in the README file

[Andrew Burgess]

https://sourceware.org/git/gitweb.cgi?p=binutils-gdb.git;h=6b3000a544a37fcabf59371cb9bba15faf53eb85

commit 6b3000a544a37fcabf59371cb9bba15faf53eb85
Author: Andrew Burgess <aburgess@redhat.com>
Date:   Sat Oct 12 11:08:04 2024 +0100

    gdb/doc: some more details in the README file
    
    After some recent discussions on the mailing list, I've made some
    changes to the README to (I hope) provide more clarity.
    
    The changes I made are:
    
      1. Removed the use of a lone 'HOST' on the configure line.  I tried
      this and 'configure' gave me a warning:
    
        configure: WARNING: you should use --build, --host, --target
    
      So I don't think this is approved practice any more.  We should
      encourage users to use `--host` instead.
    
      2. Added and reworded the --host, --target, and --enable-targets
      descriptions in the 'configure options' section.  My goals here are
      to clarify that 'cross-debugging' is really the same as 'remote
      debugging', and also to make it clearer what the defaults are.
    
      3. Added some additional text to the 'Remote debugging' section
      mentioning that 'remote debugging' is basically the same as 'cross
      debugging', given that we use 'cross-debugging' in the text above.
    
    Reviewed-By: Keith Seitz <keiths@redhat.com>

Diff:
---
 gdb/README | 43 +++++++++++++++++++++++++++++++++----------
 1 file changed, 33 insertions(+), 10 deletions(-)

diff --git a/gdb/README b/gdb/README
index d85c37d5d17..b6eb3f12c56 100644
--- a/gdb/README
+++ b/gdb/README
@@ -354,7 +354,6 @@ explanation of `configure'.
                [--srcdir=PATH]
                [--target=TARGET]
 	       [--host=HOST]
-	       [HOST]
 
 You may introduce options with a single `-' rather than `--' if you
 prefer; but you may abbreviate option names if you use `--'.  Some
@@ -380,19 +379,30 @@ more obscure GDB `configure' options are not listed here.
      directories below PATH.
 
 `--host=HOST'
-     Configure GDB to run on the specified HOST.
+     Configure GDB to run on the specified HOST.  If you omit this,
+     GDB will guess; it's quite accurate.
+
+     The guess is done by running the `config.guess' script, which can
+     be found in the root of the binutils-gdb source tree.
 
      There is no convenient way to generate a list of all available
      hosts.
 
-`HOST ...'
-     Same as `--host=HOST'.  If you omit this, GDB will guess; it's
-     quite accurate.
-
 `--target=TARGET'
-     Configure GDB for cross-debugging programs running on the specified
-     TARGET.  Without this option, GDB is configured to debug programs
-     that run on the same machine (HOST) as GDB itself.
+     Configure GDB for cross-debugging programs running on the
+     specified TARGET.  One way in which GDB supports cross-debugging
+     is through the 'target remote' and 'target extended-remote'
+     commands for remote debugging.  See the 'Remote debugging'
+     section below.
+
+     If this option is not specified, the default is the value of
+     HOST, see `--host' above.
+
+     When TARGET matches HOST, GDB will be configured with support for
+     native debugging of programs running on the same machine as GDB.
+
+     When TARGET and HOST are different, GDB will only include support
+     for cross-debugging programs running on TARGET.
 
      There is no convenient way to generate a list of all available
      targets.
@@ -400,9 +410,13 @@ more obscure GDB `configure' options are not listed here.
 `--enable-targets=TARGET,TARGET,...'
 `--enable-targets=all`
      Configure GDB for cross-debugging programs running on the
-     specified list of targets.  The special value `all' configures
+     specified list of targets in addition to the target specified
+     with `--target' (see above).  The special value `all' configures
      GDB for debugging programs running on any target it supports.
 
+     There is no convenient way to generate a list of all available
+     targets.
+
 `--with-gdb-datadir=PATH'
      Set the GDB-specific data directory.  GDB will look here for
      certain supporting files or scripts.  This defaults to the `gdb'
@@ -617,6 +631,15 @@ other GNU tools recursively.
 Remote debugging
 =================
 
+   Remote debugging is when GDB runs on one machine type (see `--host'
+above), while debugging applications running on a possibly different
+machine using the 'target remote' or 'target extended-remote'
+commands.  The `--target' and `--enable-targets' configure options
+control which targets GDB can debug.  Remote debugging is one way in
+which GDB can support cross-debugging.  GDB runs on a machine of type
+HOST (see `--host' configure option) but can remote debug a machine of
+type TARGET (see `--target' and `--enable-targets' configure options).
+
    The files m68k-stub.c, i386-stub.c, and sparc-stub.c are examples
 of remote stubs to be used with remote.c.  They are designed to run
 standalone on an m68k, i386, or SPARC cpu and communicate properly