From: Philippe Waroquiers <philippe.waroquiers@skynet.be>
To: gdb-patches@sourceware.org
Subject: [RFC] Fix/complete option list/description in manual and in gdb --help.
Date: Sun, 6 Jun 2021 16:39:27 +0200 [thread overview]
Message-ID: <20210606143927.29069-1-philippe.waroquiers@skynet.be> (raw)
The GDB option list given in gdb --help was incomplete.
This fixes it. A few fixes are also done in the user manual.
Open questions:
* is it worth describing in gdb --help that --enable-external-editor
is a 'noop' kept for backward compatibility ?
Or should that just not mentionned in --help ?
* should --annotate gdb --help output indicate its deprecation and that
new front ends should use GDB/MI (--interpret=mi) ?
* For an option such as "--eval-command=COMMAND, -ex", GDB accepts all of:
--eval-command=quit
-eval-command=quit
--eval-command quit
-eval-command quit
--ex=quit
-ex=quit
--ex quit
-ex quit
The gdb --help output uses quite systematically --XXXXX
for the "long option" XXXXX and -Y for the "short option" -y.
But the user manual has a mix of notations. For many options,
it uses -XXXXX. For some options, it uses --XXXXX. For some, it uses
both. For some, it uses -XXXXX in the text but --XXXXX for the index.
The manual indicates that many options have a long and short option,
and that options can be flagged with -- but that the manual illustrates
the 'more usual convention using a single -'.
(this is strangely documented in the 'Choosing Files' subsection,
while it should better be in the level above in 'Invoking GDB').
However, the --help assumes that the usual convention is -- for long options.
I am more used to the --long-option convention.
=> should the user manual be changed to consistently document and use
--long-option ? (and just mention the alternative accepted conventions?)
Changes in main.c are:
* the -w option was since 2003 commented as 'not sure actually useful'.
As -nw is disabling tui, and -w was activating an optional TK based
GUI, I changed the behaviour of -w to activate the TUI interface if
configured. In case both TK and TUI are configured, -w starts
the TUI interface.
So, now, -w is actually useful :).
* For some options, the addition of the short option letter needs more room.
So, the option description indentation is increased by 3 spaces,
still keeping the help output <= 80 characters.
* addition of short options for various long options
(--core, --exec, --pid; --symbols, --readnow, --fullname,
--interpreter, --cd)
* Addition of the long option for -w, --nw, -b.
* addition of the short and long options
--early--init-command=FILE, -eix
--early-init-eval-command=COMMAND, -eiex
--annotate=LEVEL
* Slightly reworded to --tui text to use the terminology GUI also used
by -w and --nw.
* addition of GDBTK options (--tclcommand, --enable-external-editor,
--editor-command).
Changes in the user manual are:
* Remove the -t TTY description. This short letter option is not defined
(and is already currently ambiguous between -tty and -tui).
* Added various synonyms
--cd=DIRECTORY = -cd DIRECTORY
--ui=INTERPRET and -i INTERPRET = --interpreter=INTERPRET
* Added description of --dbx
---
gdb/doc/gdb.texinfo | 13 +++++-
gdb/main.c | 102 ++++++++++++++++++++++++++------------------
2 files changed, 72 insertions(+), 43 deletions(-)
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index d09b86cda95..dd6b2e811c3 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -1193,6 +1193,7 @@ If @value{GDBN} includes a GUI, then this option requires it to be
used if possible.
@item -cd @var{directory}
+@itemx --cd=@var{directory}
@cindex @code{--cd}
Run @value{GDBN} using @var{directory} as its working directory,
instead of the current directory.
@@ -1252,9 +1253,7 @@ Set the timeout (in seconds) of any communication used by @value{GDBN}
for remote debugging.
@item -tty @var{device}
-@itemx -t @var{device}
@cindex @code{--tty}
-@cindex @code{-t}
Run using @var{device} for your program's standard input and output.
@c FIXME: kingdon thinks there is more to -tty. Investigate.
@@ -1269,7 +1268,11 @@ option if you run @value{GDBN} from Emacs (@pxref{Emacs, ,
Using @value{GDBN} under @sc{gnu} Emacs}).
@item -interpreter @var{interp}
+@itemx --ui=@var{interp}
+@itemx -i @var{interp}
@cindex @code{--interpreter}
+@cindex @code{--ui}
+@cindex @code{-i}
Use the interpreter @var{interp} for interface with the controlling
program or device. This option is meant to be set by programs which
communicate with @value{GDBN} using it as a back end.
@@ -1282,6 +1285,12 @@ version 2 (@code{mi2}), included in @value{GDBN} 6.0 and version 1 (@code{mi1}),
included in @value{GDBN} 5.3, are also available. Earlier @sc{gdb/mi}
interfaces are no longer supported.
+@item --dbx
+@cindex @code{--dbx}
+@samp{--dbx} causes @value{GDBN} to define various additional commands
+(such as @samp{assign}, @samp{use}, ...) providing some compatibility
+with the @var{dbx} debugger.
+
@item -write
@cindex @code{--write}
Open the executable and core files for both reading and writing. This
diff --git a/gdb/main.c b/gdb/main.c
index 5761ce2bdbe..c7325ce1077 100644
--- a/gdb/main.c
+++ b/gdb/main.c
@@ -887,12 +887,15 @@ captured_main_1 (struct captured_main_args *context)
#endif
break;
case OPT_WINDOWS:
- /* FIXME: cagney/2003-03-01: Not sure if this option is
- actually useful, and if it is, what it should do. */
#ifdef GDBTK
/* --windows is equivalent to -i=insight. */
xfree (interpreter_p);
interpreter_p = xstrdup (INTERP_INSIGHT);
+#endif
+#ifdef TUI
+ /* Or -i=tui, with a priority to tui if both are defined. */
+ xfree (interpreter_p);
+ interpreter_p = xstrdup (INTERP_TUI);
#endif
break;
case OPT_NOWINDOWS:
@@ -1403,66 +1406,83 @@ This is the GNU debugger. Usage:\n\n\
"), stream);
fputs_unfiltered (_("\
Selection of debuggee and its files:\n\n\
- --args Arguments after executable-file are passed to inferior.\n\
- --core=COREFILE Analyze the core dump COREFILE.\n\
- --exec=EXECFILE Use EXECFILE as the executable.\n\
- --pid=PID Attach to running process PID.\n\
- --directory=DIR Search for source files in DIR.\n\
- --se=FILE Use FILE as symbol file and executable file.\n\
- --symbols=SYMFILE Read symbols from SYMFILE.\n\
- --readnow Fully read symbol files on first access.\n\
- --readnever Do not read symbol files.\n\
- --write Set writing into executable and core files.\n\n\
+ --args Arguments after executable-file are passed to inferior.\n\
+ --core=COREFILE, -c Analyze the core dump COREFILE.\n\
+ --exec=EXECFILE, -e Use EXECFILE as the executable.\n\
+ --pid=PID, -p Attach to running process PID.\n\
+ --directory=DIR, -d Search for source files in DIR.\n\
+ --se=FILE Use FILE as symbol file and executable file.\n\
+ --symbols=SYMFILE, -s Read symbols from SYMFILE.\n\
+ --readnow, -r Fully read symbol files on first access.\n\
+ --readnever Do not read symbol files.\n\
+ --write Set writing into executable and core files.\n\n\
"), stream);
fputs_unfiltered (_("\
Initial commands and command files:\n\n\
- --command=FILE, -x Execute GDB commands from FILE.\n\
+ --command=FILE, -x Execute GDB commands from FILE.\n\
--init-command=FILE, -ix\n\
- Like -x but execute commands before loading inferior.\n\
+ Like -x but execute commands before loading inferior.\n\
--eval-command=COMMAND, -ex\n\
- Execute a single GDB command.\n\
- May be used multiple times and in conjunction\n\
- with --command.\n\
+ Execute a single GDB command.\n\
+ May be used multiple times and in conjunction\n\
+ with --command.\n\
--init-eval-command=COMMAND, -iex\n\
- Like -ex but before loading inferior.\n\
- --nh Do not read ~/.gdbinit.\n\
- --nx Do not read any .gdbinit files in any directory.\n\n\
+ Like -ex but before loading inferior.\n\
+ --early-init-command=FILE, -eix\n\
+ Like -x but FILE can only contain 'set' and 'source'\n\
+ commands to run before GDB initialization.\n\
+ --early-init-eval-command=COMMAND, -eiex\n\
+ Like -ex but only for 'set' and 'source' commands\n\
+ to run before GDB initialization.\n\
+ --nh Do not read ~/.gdbinit.\n\
+ --nx, -n Do not read any .gdbinit files in any directory.\n\n\
"), stream);
fputs_unfiltered (_("\
Output and user interface control:\n\n\
- --fullname Output information used by emacs-GDB interface.\n\
- --interpreter=INTERP\n\
- Select a specific interpreter / user interface.\n\
- --tty=TTY Use TTY for input/output by the program being debugged.\n\
- -w Use the GUI interface.\n\
- --nw Do not use the GUI interface.\n\
+ --annotate=LEVEL Output information used by graphical user interfaces.\n\
+ --fullname, -f Output information used by emacs-GDB interface.\n\
+ Like --annotate=1\n\
+ --interpreter=INTERP, --ui=INTERP, -i \n\
+ Select a specific interpreter / user interface.\n\
+ --tty=TTY Use TTY for input/output by the program being debugged.\n\
+ --windows, -w Use the GUI interface.\n\
+ --nowindows, --nw Do not use the GUI interface.\n\
"), stream);
#if defined(TUI)
fputs_unfiltered (_("\
- --tui Use a terminal user interface.\n\
+ --tui Use the terminal user interface GUI.\n\
+"), stream);
+#endif
+#if defined(GDBTK)
+ fputs_unfiltered (_("\
+ --tclcommand=FILE Load tclcommand FILE.\n\
+ --enable-external-editor\n\
+ Ignored for backward compatibility.\n\
+ --editor-command=COMMAND\n\
+ Set the external editor command when GDB\n\
+ is farming out files to be edited by another program.\n\
"), stream);
#endif
fputs_unfiltered (_("\
- --dbx DBX compatibility mode.\n\
- -q, --quiet, --silent\n\
- Do not print version number on startup.\n\n\
+ --dbx DBX compatibility mode.\n\
+ -q, --quiet, --silent Do not print version number on startup.\n\n\
"), stream);
fputs_unfiltered (_("\
Operating modes:\n\n\
- --batch Exit after processing options.\n\
- --batch-silent Like --batch, but suppress all gdb stdout output.\n\
- --return-child-result\n\
- GDB exit code will be the child's exit code.\n\
- --configuration Print details about GDB configuration and then exit.\n\
- --help Print this message and then exit.\n\
- --version Print version information and then exit.\n\n\
+ --batch Exit after processing options.\n\
+ --batch-silent Like --batch, but suppress all gdb stdout output.\n\
+ --return-child-result GDB exit code will be the child's exit code.\n\
+ --statistics Print time and memory usage after each command.\n\
+ --configuration Print details about GDB configuration and then exit.\n\
+ --help Print this message and then exit.\n\
+ --version Print version information and then exit.\n\n\
Remote debugging options:\n\n\
- -b BAUDRATE Set serial port baud rate used for remote debugging.\n\
- -l TIMEOUT Set timeout in seconds for remote debugging.\n\n\
+ --baud=BAUDRATE, -b Set serial port baud rate used for remote debugging.\n\
+ -l TIMEOUT Set timeout in seconds for remote debugging.\n\n\
Other options:\n\n\
- --cd=DIR Change current directory to DIR.\n\
+ --cd=DIR, -cd Change current directory to DIR.\n\
--data-directory=DIR, -D\n\
- Set GDB's data-directory to DIR.\n\
+ Set GDB's data-directory to DIR.\n\
"), stream);
fputs_unfiltered (_("\n\
At startup, GDB reads the following early init files and executes their\n\
--
2.20.1
next reply other threads:[~2021-06-06 14:39 UTC|newest]
Thread overview: 3+ messages / expand[flat|nested] mbox.gz Atom feed top
2021-06-06 14:39 Philippe Waroquiers [this message]
2021-06-06 16:58 ` Philippe Waroquiers
2021-06-06 18:06 ` Eli Zaretskii
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20210606143927.29069-1-philippe.waroquiers@skynet.be \
--to=philippe.waroquiers@skynet.be \
--cc=gdb-patches@sourceware.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).