gdb/doc: some more details in the README file

Message ID 8ba49e21f99e8e08528f3053bbdc623d53669bc0.1728762272.git.aburgess@redhat.com
State New
Headers
Series gdb/doc: some more details in the README file |

Checks

Context Check Description
linaro-tcwg-bot/tcwg_gdb_build--master-arm success Build passed
linaro-tcwg-bot/tcwg_gdb_build--master-aarch64 success Build passed
linaro-tcwg-bot/tcwg_gdb_check--master-arm success Test passed
linaro-tcwg-bot/tcwg_gdb_check--master-aarch64 success Test passed

Commit Message

Andrew Burgess Oct. 12, 2024, 7:44 p.m. UTC
  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.
---
 gdb/README | 40 ++++++++++++++++++++++++++++++----------
 1 file changed, 30 insertions(+), 10 deletions(-)


base-commit: 5bc1b13676bc5eeefc50d25379991f5f9255eb80
  

Patch

diff --git a/gdb/README b/gdb/README
index d85c37d5d17..a52bad1ec55 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,27 @@  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.
 
      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 support 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 given then 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 +407,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 +628,15 @@  other GNU tools recursively.
 Remote debugging
 =================
 
+   Remote debugging is when GDB runs on one maching 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