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
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
@@ -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