* [RFA] Fix/complete option list/description in manual and in gdb --help.
@ 2021-06-11 19:26 Philippe Waroquiers
2021-06-12 10:04 ` Eli Zaretskii
2021-06-17 10:23 ` Pedro Alves
0 siblings, 2 replies; 5+ messages in thread
From: Philippe Waroquiers @ 2021-06-11 19:26 UTC (permalink / raw)
To: gdb-patches
The GDB option list given in gdb --help was incomplete.
This fixes it. Some fixes are also done in the user manual.
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, for backward
compatibility reasons, -w starts the TK 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
Note that --annotate is deprecated (front ends should use GDB/MI)
but --help is not modified to indicate this deprecation.
* 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).
Note that --enable-external-editor is a noop kept for backward compatibility,
but I have not modified the --help to indicate that.
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
* 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.
The user manual was using a mixture of notations, sometimes -XXXXXX,
sometimes --XXXXXX, sometimes both.
Manual changed to systematically use the same notation as the --help
output.
The manual now only describes that options can be quite freely accepted
with all the above different formats, but now uses in examples and index
the classical --XXXXXXX or -Y formats.
gdb/ChangeLog
2021-MM-DD Philippe Waroquiers <philippe.waroquiers@skynet.be>
* main.c (captured_main_1): Have -w starting TUI to TK,
use consistently -o or --option convention.
(print_gdb_help): fix/complete help.
gdb/doc/ChangeLog
2021-MM-DD Philippe Waroquiers <philippe.waroquiers@skynet.be>
* gdb.texinfo (Invoking GDB): Complete help. Use -- systematically
for all long options.
---
gdb/doc/gdb.texinfo | 149 ++++++++++++++++++++++++++------------------
gdb/main.c | 109 +++++++++++++++++++-------------
2 files changed, 152 insertions(+), 106 deletions(-)
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index d09b86cda95..0f5a4d0eca4 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -921,7 +921,7 @@ options. @value{GDBN} itself can remind you of the options available.
Type
@smallexample
-@value{GDBP} -help
+@value{GDBP} --help
@end smallexample
@noindent
@@ -932,6 +932,31 @@ All options and command line arguments you give are processed
in sequential order. The order makes a difference when the
@samp{-x} option is used.
+Many options have both long and short forms. Short options start with
+@samp{-}, and long options start with @samp{--}. @value{GDBN} also
+recognizes the long forms if you truncate them, so long as enough of
+the option is present to be unambiguous. If an option requires a
+value, the convention for long options is @samp{--option=value} and
+@samp{-o value} for short options.
+
+Note however that @value{GDBN} accepts all of the following conventions
+for most options:
+
+@table @code
+@item --option=value
+@item --option value
+@item -option=value
+@item -option value
+@item -o value
+@item -o=value
+@item --o value
+@item --o=value
+@end table
+
+@c NOTE: the @cindex entries here use double dashes ON PURPOSE. This
+@c way, both those who look for -foo and --foo in the index, will find
+@c it.
+
@menu
* File Options:: Choosing files
@@ -945,10 +970,10 @@ in sequential order. The order makes a difference when the
When @value{GDBN} starts, it reads any arguments other than options as
specifying an executable file and core file (or process ID). This is
-the same as if the arguments were specified by the @samp{-se} and
+the same as if the arguments were specified by the @samp{--se} and
@samp{-c} (or @samp{-p}) options respectively. (@value{GDBN} reads the
first argument that does not have an associated option flag as
-equivalent to the @samp{-se} option followed by that argument; and the
+equivalent to the @samp{--se} option followed by that argument; and the
second argument that does not have an associated option flag, if any, as
equivalent to the @samp{-c}/@samp{-p} option followed by that argument.)
If the second argument begins with a decimal digit, @value{GDBN} will
@@ -961,48 +986,39 @@ If @value{GDBN} has not been configured to included core file support,
such as for most embedded targets, then it will complain about a second
argument and ignore it.
-Many options have both long and short forms; both are shown in the
-following list. @value{GDBN} also recognizes the long forms if you truncate
-them, so long as enough of the option is present to be unambiguous.
-(If you prefer, you can flag option arguments with @samp{--} rather
-than @samp{-}, though we illustrate the more usual convention.)
-
-@c NOTE: the @cindex entries here use double dashes ON PURPOSE. This
-@c way, both those who look for -foo and --foo in the index, will find
-@c it.
@table @code
-@item -symbols @var{file}
+@item --symbols=@var{file}
@itemx -s @var{file}
@cindex @code{--symbols}
@cindex @code{-s}
Read symbol table from file @var{file}.
-@item -exec @var{file}
+@item --exec=@var{file}
@itemx -e @var{file}
@cindex @code{--exec}
@cindex @code{-e}
Use file @var{file} as the executable file to execute when appropriate,
and for examining pure data in conjunction with a core dump.
-@item -se @var{file}
+@item --se=@var{file}
@cindex @code{--se}
Read symbol table from file @var{file} and use it as the executable
file.
-@item -core @var{file}
+@item --core=@var{file}
@itemx -c @var{file}
@cindex @code{--core}
@cindex @code{-c}
Use file @var{file} as a core dump to examine.
-@item -pid @var{number}
+@item --pid=@var{number}
@itemx -p @var{number}
@cindex @code{--pid}
@cindex @code{-p}
Connect to process ID @var{number}, as with the @code{attach} command.
-@item -command @var{file}
+@item --command=@var{file}
@itemx -x @var{file}
@cindex @code{--command}
@cindex @code{-x}
@@ -1010,21 +1026,21 @@ Execute commands from file @var{file}. The contents of this file is
evaluated exactly as the @code{source} command would.
@xref{Command Files,, Command files}.
-@item -eval-command @var{command}
+@item --eval-command=@var{command}
@itemx -ex @var{command}
@cindex @code{--eval-command}
@cindex @code{-ex}
Execute a single @value{GDBN} command.
This option may be used multiple times to call multiple commands. It may
-also be interleaved with @samp{-command} as required.
+also be interleaved with @samp{--command} as required.
@smallexample
@value{GDBP} -ex 'target sim' -ex 'load' \
-x setbreakpoints -ex 'run' a.out
@end smallexample
-@item -init-command @var{file}
+@item -init-command=@var{file}
@itemx -ix @var{file}
@cindex @code{--init-command}
@cindex @code{-ix}
@@ -1032,7 +1048,7 @@ Execute commands from file @var{file} before loading the inferior (but
after loading gdbinit files).
@xref{Startup}.
-@item -init-eval-command @var{command}
+@item --init-eval-command=@var{command}
@itemx -iex @var{command}
@cindex @code{--init-eval-command}
@cindex @code{-iex}
@@ -1040,28 +1056,28 @@ Execute a single @value{GDBN} command before loading the inferior (but
after loading gdbinit files).
@xref{Startup}.
-@item -early-init-command @var{file}
+@item --early-init-command=@var{file}
@itemx -eix @var{file}
@cindex @code{--early-init-command}
@cindex @code{-eix}
Execute commands from @var{file} very early in the initialization
process, before any output is produced. @xref{Startup}.
-@item -early-init-eval-command @var{command}
+@item --early-init-eval-command=@var{command}
@itemx -eiex @var{command}
@cindex @code{--early-init-eval-command}
@cindex @code{-eiex}
Execute a single @value{GDBN} command very early in the initialization
process, before any output is produced.
-@item -directory @var{directory}
+@item --directory=@var{directory}
@itemx -d @var{directory}
@cindex @code{--directory}
@cindex @code{-d}
Add @var{directory} to the path to search for source and script files.
@item -r
-@itemx -readnow
+@itemx --readnow
@cindex @code{--readnow}
@cindex @code{-r}
Read each symbol file's entire symbol table immediately, rather than
@@ -1087,24 +1103,24 @@ You can run @value{GDBN} in various alternative modes---for example, in
batch mode or quiet mode.
@table @code
-@anchor{-nx}
-@item -nx
+@anchor{--nx}
+@item --nx
@itemx -n
@cindex @code{--nx}
@cindex @code{-n}
Do not execute commands found in any initialization files
(@pxref{Initialization Files}).
-@anchor{-nh}
-@item -nh
+@anchor{--nh}
+@item --nh
@cindex @code{--nh}
Do not execute commands found in any home directory initialization
file (@pxref{Initialization Files,,Home directory initialization
file}). The system wide and current directory initialization files
are still loaded.
-@item -quiet
-@itemx -silent
+@item --quiet
+@itemx --silent
@itemx -q
@cindex @code{--quiet}
@cindex @code{--silent}
@@ -1120,7 +1136,7 @@ current setting. Place @code{set startup-quietly on} into your early
initialization file (@pxref{Initialization Files,,Initialization
Files}) to have future @value{GDBN} sessions startup quietly.
-@item -batch
+@item --batch
@cindex @code{--batch}
Run in batch mode. Exit with status @code{0} after processing all the
command files specified with @samp{-x} (and all commands from
@@ -1143,11 +1159,11 @@ Program exited normally.
@value{GDBN} control terminates) is not issued when running in batch
mode.
-@item -batch-silent
+@item --batch-silent
@cindex @code{--batch-silent}
-Run in batch mode exactly like @samp{-batch}, but totally silently. All
+Run in batch mode exactly like @samp{--batch}, but totally silently. All
@value{GDBN} output to @code{stdout} is prevented (@code{stderr} is
-unaffected). This is much quieter than @samp{-silent} and would be useless
+unaffected). This is much quieter than @samp{--silent} and would be useless
for an interactive session.
This is particularly useful when using targets that give @samp{Loading section}
@@ -1156,7 +1172,7 @@ messages, for example.
Note that targets that give their output via @value{GDBN}, as opposed to
writing directly to @code{stdout}, will also be made silent.
-@item -return-child-result
+@item --return-child-result
@cindex @code{--return-child-result}
The return code from @value{GDBN} will be the return code from the child
process (the process being debugged), with the following exceptions:
@@ -1165,7 +1181,7 @@ process (the process being debugged), with the following exceptions:
@item
@value{GDBN} exits abnormally. E.g., due to an incorrect argument or an
internal error. In this case the exit code is the same as it would have been
-without @samp{-return-child-result}.
+without @samp{--return-child-result}.
@item
The user quits with an explicit value. E.g., @samp{quit 1}.
@item
@@ -1173,19 +1189,19 @@ The child process never runs, or is not allowed to terminate, in which case
the exit code will be -1.
@end itemize
-This option is useful in conjunction with @samp{-batch} or @samp{-batch-silent},
-when @value{GDBN} is being used as a remote program loader or simulator
-interface.
+This option is useful in conjunction with @samp{--batch} or
+@samp{--batch-silent}, when @value{GDBN} is being used as a remote
+program loader or simulator interface.
-@item -nowindows
-@itemx -nw
+@item --nowindows
+@itemx --nw
@cindex @code{--nowindows}
-@cindex @code{-nw}
+@cindex @code{--nw}
``No windows''. If @value{GDBN} comes with a graphical user interface
(GUI) built in, then this option tells @value{GDBN} to only use the command-line
interface. If no GUI is available, this option has no effect.
-@item -windows
+@item --windows
@itemx -w
@cindex @code{--windows}
@cindex @code{-w}
@@ -1193,11 +1209,12 @@ 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.
-@item -data-directory @var{directory}
+@item --data-directory=@var{directory}
@itemx -D @var{directory}
@cindex @code{--data-directory}
@cindex @code{-D}
@@ -1205,7 +1222,7 @@ Run @value{GDBN} using @var{directory} as its data directory.
The data directory is where @value{GDBN} searches for its
auxiliary files. @xref{Data Files}.
-@item -fullname
+@item --fullname
@itemx -f
@cindex @code{--fullname}
@cindex @code{-f}
@@ -1219,7 +1236,7 @@ and a newline. The Emacs-to-@value{GDBN} interface program uses the two
@samp{\032} characters as a signal to display the source code for the
frame.
-@item -annotate @var{level}
+@item --annotate=@var{level}
@cindex @code{--annotate}
This option sets the @dfn{annotation level} inside @value{GDBN}. Its
effect is identical to using @samp{set annotate @var{level}}
@@ -1239,7 +1256,7 @@ Change interpretation of command line so that arguments following the
executable file are passed as command line arguments to the inferior.
This option stops option processing.
-@item -baud @var{bps}
+@item --baud=@var{bps}
@itemx -b @var{bps}
@cindex @code{--baud}
@cindex @code{-b}
@@ -1251,15 +1268,13 @@ interface used by @value{GDBN} for remote debugging.
Set the timeout (in seconds) of any communication used by @value{GDBN}
for remote debugging.
-@item -tty @var{device}
-@itemx -t @var{device}
+@item --tty=@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.
@c resolve the situation of these eventually
-@item -tui
+@item --tui
@cindex @code{--tui}
Activate the @dfn{Text User Interface} when starting. The Text User
Interface manages several text windows on the terminal, showing
@@ -1268,8 +1283,12 @@ source, assembly, registers and @value{GDBN} command outputs
option if you run @value{GDBN} from Emacs (@pxref{Emacs, ,
Using @value{GDBN} under @sc{gnu} Emacs}).
-@item -interpreter @var{interp}
+@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,23 +1301,29 @@ 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 -write
+@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
is equivalent to the @samp{set write on} command inside @value{GDBN}
(@pxref{Patching}).
-@item -statistics
+@item --statistics
@cindex @code{--statistics}
This option causes @value{GDBN} to print statistics about time and
memory usage after it completes each command and returns to the prompt.
-@item -version
+@item --version
@cindex @code{--version}
This option causes @value{GDBN} to print its version number and
no-warranty blurb, and exit.
-@item -configuration
+@item --configuration
@cindex @code{--configuration}
This option causes @value{GDBN} to print details about its build-time
configuration parameters, and then exit. These details can be
@@ -1344,7 +1369,7 @@ Reads the initialization file (if any) in your home directory and
executes all the commands in that file, @pxref{Home Directory Init
File}.
-@anchor{Option -init-eval-command}
+@anchor{Option --init-eval-command}
@item
Executes commands and command files specified by the @samp{-iex} and
@samp{-ix} options in their specified order. Usually you should use the
@@ -1544,7 +1569,7 @@ While on Apple hosts the locations searched are:
@end table
It is possible to prevent the home directory initialization file from
-being loaded using the @samp{-nx} or @samp{-nh} command line options,
+being loaded using the @samp{--nx} or @samp{--nh} command line options,
@pxref{Mode Options,,Choosing Modes}.
The DJGPP port of @value{GDBN} uses the name @file{gdb.ini} instead of
@@ -1569,7 +1594,7 @@ directory initialization file then it will not be loaded a second
time.
It is possible to prevent the local directory initialization file from
-being loaded using the @samp{-nx} command line option, @pxref{Mode
+being loaded using the @samp{--nx} command line option, @pxref{Mode
Options,,Choosing Modes}.
@node Quitting GDB
@@ -26301,7 +26326,7 @@ control when to auto-load files and which files should be auto-loaded.
@item set auto-load off
Globally disable loading of all auto-loaded files.
You may want to use this command with the @samp{-iex} option
-(@pxref{Option -init-eval-command}) such as:
+(@pxref{Option --init-eval-command}) such as:
@smallexample
$ @kbd{gdb -iex "set auto-load off" untrusted-executable corefile}
@end smallexample
diff --git a/gdb/main.c b/gdb/main.c
index 5761ce2bdbe..3ea01f9f056 100644
--- a/gdb/main.c
+++ b/gdb/main.c
@@ -878,7 +878,7 @@ captured_main_1 (struct captured_main_args *context)
set_per_command_space (1);
break;
case OPT_TUI:
- /* --tui is equivalent to -i=tui. */
+ /* --tui is equivalent to -i tui. */
#ifdef TUI
xfree (interpreter_p);
interpreter_p = xstrdup (INTERP_TUI);
@@ -887,16 +887,20 @@ 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. */
+ /* --windows is equivalent to -i insight or -i tui.
+ If both are defined, for backward compatibility reasons,
+ priority is given to -i insight. */
+#ifdef TUI
+ xfree (interpreter_p);
+ interpreter_p = xstrdup (INTERP_TUI);
+#endif
#ifdef GDBTK
- /* --windows is equivalent to -i=insight. */
xfree (interpreter_p);
interpreter_p = xstrdup (INTERP_INSIGHT);
#endif
break;
case OPT_NOWINDOWS:
- /* -nw is equivalent to -i=console. */
+ /* -nw is equivalent to --interpreter=console. */
xfree (interpreter_p);
interpreter_p = xstrdup (INTERP_CONSOLE);
break;
@@ -1403,66 +1407,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
^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: [RFA] Fix/complete option list/description in manual and in gdb --help.
2021-06-11 19:26 [RFA] Fix/complete option list/description in manual and in gdb --help Philippe Waroquiers
@ 2021-06-12 10:04 ` Eli Zaretskii
2021-06-17 10:23 ` Pedro Alves
1 sibling, 0 replies; 5+ messages in thread
From: Eli Zaretskii @ 2021-06-12 10:04 UTC (permalink / raw)
To: Philippe Waroquiers; +Cc: gdb-patches
> Date: Fri, 11 Jun 2021 21:26:42 +0200
> From: Philippe Waroquiers via Gdb-patches <gdb-patches@sourceware.org>
>
> gdb/ChangeLog
> 2021-MM-DD Philippe Waroquiers <philippe.waroquiers@skynet.be>
>
> * main.c (captured_main_1): Have -w starting TUI to TK,
> use consistently -o or --option convention.
> (print_gdb_help): fix/complete help.
>
> gdb/doc/ChangeLog
> 2021-MM-DD Philippe Waroquiers <philippe.waroquiers@skynet.be>
>
> * gdb.texinfo (Invoking GDB): Complete help. Use -- systematically
> for all long options.
Thank you for doing this.
> +Many options have both long and short forms. Short options start with
> +@samp{-}, and long options start with @samp{--}. @value{GDBN} also
> +recognizes the long forms if you truncate them, so long as enough of
> +the option is present to be unambiguous. If an option requires a
> +value, the convention for long options is @samp{--option=value} and
> +@samp{-o value} for short options.
> +
> +Note however that @value{GDBN} accepts all of the following conventions
> +for most options:
> +
> +@table @code
> +@item --option=value
> +@item --option value
> +@item -option=value
> +@item -option value
> +@item -o value
> +@item -o=value
> +@item --o value
> +@item --o=value
> +@end table
The "value" parts above should have the @var markup.
> +@c NOTE: the @cindex entries here use double dashes ON PURPOSE. This
> +@c way, both those who look for -foo and --foo in the index, will find
> +@c it.
Should this comment be before the text above, as it is relevant for it
as well?
The documentation part is OK with those nits taken care of.
^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: [RFA] Fix/complete option list/description in manual and in gdb --help.
2021-06-11 19:26 [RFA] Fix/complete option list/description in manual and in gdb --help Philippe Waroquiers
2021-06-12 10:04 ` Eli Zaretskii
@ 2021-06-17 10:23 ` Pedro Alves
2021-06-20 20:58 ` Philippe Waroquiers
2021-08-01 23:19 ` Joel Brobecker
1 sibling, 2 replies; 5+ messages in thread
From: Pedro Alves @ 2021-06-17 10:23 UTC (permalink / raw)
To: Philippe Waroquiers, gdb-patches
On 2021-06-11 8:26 p.m., Philippe Waroquiers via Gdb-patches wrote:
> The GDB option list given in gdb --help was incomplete.
> This fixes it. Some fixes are also done in the user manual.
>
> 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, for backward
> compatibility reasons, -w starts the TK interface.
> So, now, -w is actually useful :).
Not sure I agree we should do this. Shouldn't we instead error out if
Insight (the TK GUI) is not compiled in? Like we do with --tui:
case OPT_TUI:
/* --tui is equivalent to -i tui. */
#ifdef TUI
xfree (interpreter_p);
interpreter_p = xstrdup (INTERP_TUI);
#else
error (_("%s: TUI mode is not supported"), gdb_program_name);
#endif
>
> * 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
> Note that --annotate is deprecated (front ends should use GDB/MI)
> but --help is not modified to indicate this deprecation.
>
> * Slightly reworded to --tui text to use the terminology GUI also used
> by -w and --nw.
That looks odd to me, to call it a GUI. TUI stands for "Text User Interface".
I'd say it's a TUI, not a GUI:
https://en.wikipedia.org/wiki/Text-based_user_interface
>
> * addition of GDBTK options (--tclcommand, --enable-external-editor,
> --editor-command).
> Note that --enable-external-editor is a noop kept for backward compatibility,
> but I have not modified the --help to indicate that.
>
> 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
>
> * 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.
>
> The user manual was using a mixture of notations, sometimes -XXXXXX,
> sometimes --XXXXXX, sometimes both.
> Manual changed to systematically use the same notation as the --help
> output.
> The manual now only describes that options can be quite freely accepted
> with all the above different formats, but now uses in examples and index
> the classical --XXXXXXX or -Y formats.
>
> gdb/ChangeLog
> 2021-MM-DD Philippe Waroquiers <philippe.waroquiers@skynet.be>
>
> * main.c (captured_main_1): Have -w starting TUI to TK,
> use consistently -o or --option convention.
> (print_gdb_help): fix/complete help.
>
> gdb/doc/ChangeLog
> 2021-MM-DD Philippe Waroquiers <philippe.waroquiers@skynet.be>
>
> * gdb.texinfo (Invoking GDB): Complete help. Use -- systematically
> for all long options.
> ---
> gdb/doc/gdb.texinfo | 149 ++++++++++++++++++++++++++------------------
> gdb/main.c | 109 +++++++++++++++++++-------------
> 2 files changed, 152 insertions(+), 106 deletions(-)
>
> diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
> index d09b86cda95..0f5a4d0eca4 100644
> --- a/gdb/doc/gdb.texinfo
> +++ b/gdb/doc/gdb.texinfo
> @@ -921,7 +921,7 @@ options. @value{GDBN} itself can remind you of the options available.
> Type
>
> @smallexample
> -@value{GDBP} -help
> +@value{GDBP} --help
> @end smallexample
>
> @noindent
> @@ -932,6 +932,31 @@ All options and command line arguments you give are processed
> in sequential order. The order makes a difference when the
> @samp{-x} option is used.
>
> +Many options have both long and short forms. Short options start with
> +@samp{-}, and long options start with @samp{--}. @value{GDBN} also
> +recognizes the long forms if you truncate them, so long as enough of
> +the option is present to be unambiguous. > If an option requires a
Should we actually describe this long vs short option distinction? It isn't
actually correct.
Short options in getopt programs are one letter options that you can combine
in a single '-'. For example "ls -als" vs "ls -a -l -s".
In GDB, you can't do that with the "short" options. GDB uses getopt_long_only.
"gdb -qf" is not the same as "gdb -q -f"
In GDB, the supposedly short options can also be specified with --, we install
long options for all them as well. Well, again, we use getopt_long_only.
These are the same:
gdb -q
gdb --q
Or these two:
gdb -f
gdb --f
etc.
Also, some options listed with single dash, supposedly indicating "short" option, like -ex here:
--eval-command=COMMAND, -ex
aren't really short options. They are more than one character long, and they work
with both "-" and "--":
gdb -ex CMD
gdb --ex CMD
Instead what we have, is I think:
All options can be specified with - or --. GDB recognizes (all, short and long if you must) options if
you truncate them, so long as enough of the option is present to be unambiguous. For some options,
GDB recognizes a shorter form even if it would be ambiguous with some other options.
So I wonder whether the direction should be the opposite, document all options with single '-'
consistently throughout?
I have to say that I never use = with "long" options, do you? I found it a bit weird to document
that as the canonical form, but maybe that's just me.
> -@item -init-command @var{file}
> +@item -init-command=@var{file}
This one missed the '-' -> '--'.
> @itemx -ix @var{file}
> @cindex @code{--init-command}
> @cindex @code{-ix}
> @@ -1032,7 +1048,7 @@ Execute commands from file @var{file} before loading the inferior (but
> after loading gdbinit files).
> @xref{Startup}.
>
^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: [RFA] Fix/complete option list/description in manual and in gdb --help.
2021-06-17 10:23 ` Pedro Alves
@ 2021-06-20 20:58 ` Philippe Waroquiers
2021-08-01 23:19 ` Joel Brobecker
1 sibling, 0 replies; 5+ messages in thread
From: Philippe Waroquiers @ 2021-06-20 20:58 UTC (permalink / raw)
To: Pedro Alves, gdb-patches
Thanks for the comments, I will send soon a patch RFA V2.
Some feedback about specific points below.
Philippe
On Thu, 2021-06-17 at 11:23 +0100, Pedro Alves wrote:
> On 2021-06-11 8:26 p.m., Philippe Waroquiers via Gdb-patches wrote:
> > The GDB option list given in gdb --help was incomplete.
> > This fixes it. Some fixes are also done in the user manual.
> >
> > 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, for backward
> > compatibility reasons, -w starts the TK interface.
> > So, now, -w is actually useful :).
>
> Not sure I agree we should do this. Shouldn't we instead error out if
> Insight (the TK GUI) is not compiled in? Like we do with --tui:
>
> case OPT_TUI:
> /* --tui is equivalent to -i tui. */
> #ifdef TUI
> xfree (interpreter_p);
> interpreter_p = xstrdup (INTERP_TUI);
> #else
> error (_("%s: TUI mode is not supported"), gdb_program_name);
> #endif
Currently, the code ignores -w --window if GDBTK is not configured,
and the user manual explicitly indicates this option is ignored in this case.
So, the idea of the change is:
* do not change the behaviour that -w --window is ignored.
* but starts the TUI if configured. It seems inconsistent to
have -nw --nowindows disabling the TUI but -w --window not enabling it.
I have changed the --help and user manual to indicate that these options are
enabling/disable 'GUI or TUI'.
> That looks odd to me, to call it a GUI. TUI stands for "Text User Interface".
Changed to use TUI or 'GUI or TUI' when relevant.
> ---
> > gdb/doc/gdb.texinfo | 149 ++++++++++++++++++++++++++------------------
> > gdb/main.c | 109 +++++++++++++++++++-------------
> > 2 files changed, 152 insertions(+), 106 deletions(-)
> >
> > diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
> > index d09b86cda95..0f5a4d0eca4 100644
> > --- a/gdb/doc/gdb.texinfo
> > +++ b/gdb/doc/gdb.texinfo
> > @@ -921,7 +921,7 @@ options. @value{GDBN} itself can remind you of the options available.
> > Type
> >
> > @smallexample
> > -@value{GDBP} -help
> > +@value{GDBP} --help
> > @end smallexample
> >
> > @noindent
> > @@ -932,6 +932,31 @@ All options and command line arguments you give are processed
> > in sequential order. The order makes a difference when the
> > @samp{-x} option is used.
> >
> > +Many options have both long and short forms. Short options start with
> > +@samp{-}, and long options start with @samp{--}. @value{GDBN} also
> > +recognizes the long forms if you truncate them, so long as enough of
> > +the option is present to be unambiguous. > If an option requires a
>
> Should we actually describe this long vs short option distinction? It isn't
> actually correct.
>
> Short options in getopt programs are one letter options that you can combine
> in a single '-'. For example "ls -als" vs "ls -a -l -s".
>
> In GDB, you can't do that with the "short" options. GDB uses getopt_long_only.
>
> "gdb -qf" is not the same as "gdb -q -f"
>
> In GDB, the supposedly short options can also be specified with --, we install
> long options for all them as well. Well, again, we use getopt_long_only.
>
> These are the same:
>
> gdb -q
> gdb --q
>
> Or these two:
>
> gdb -f
> gdb --f
>
> etc.
>
> Also, some options listed with single dash, supposedly indicating "short" option, like -ex here:
>
> --eval-command=COMMAND, -ex
>
> aren't really short options. They are more than one character long, and they work
> with both "-" and "--":
>
> gdb -ex CMD
> gdb --ex CMD
>
>
> Instead what we have, is I think:
>
> All options can be specified with - or --. GDB recognizes (all, short and long if you must) options if
> you truncate them, so long as enough of the option is present to be unambiguous. For some options,
> GDB recognizes a shorter form even if it would be ambiguous with some other options.
I have reworked the user manual based on the above.
>
> So I wonder whether the direction should be the opposite, document all options with single '-'
> consistently throughout?
I am more used to the --option=value notation for long options. Eli also replied that
we should use/document the --option form.
>
> I have to say that I never use = with "long" options, do you? I found it a bit weird to document
> that as the canonical form, but maybe that's just me.
Probably I am influenced a lot by many commands (e.g. ls) that accept and document
--option=value even if they also accept --option value.
I am likely also influenced by valgrind that only accepts --option=value form.
Note that gdb --help documents options with -- since quite a long time (1999 or before).
So, it looks to me that the user manual should better be consistent with --help.
^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: [RFA] Fix/complete option list/description in manual and in gdb --help.
2021-06-17 10:23 ` Pedro Alves
2021-06-20 20:58 ` Philippe Waroquiers
@ 2021-08-01 23:19 ` Joel Brobecker
1 sibling, 0 replies; 5+ messages in thread
From: Joel Brobecker @ 2021-08-01 23:19 UTC (permalink / raw)
To: Pedro Alves; +Cc: Philippe Waroquiers, gdb-patches, Joel Brobecker
> > +Many options have both long and short forms. Short options start with
> > +@samp{-}, and long options start with @samp{--}. @value{GDBN} also
> > +recognizes the long forms if you truncate them, so long as enough of
> > +the option is present to be unambiguous. > If an option requires a
>
>
> Should we actually describe this long vs short option distinction? It isn't
> actually correct.
>
> Short options in getopt programs are one letter options that you can combine
> in a single '-'. For example "ls -als" vs "ls -a -l -s".
>
> In GDB, you can't do that with the "short" options. GDB uses getopt_long_only.
>
> "gdb -qf" is not the same as "gdb -q -f"
>
> In GDB, the supposedly short options can also be specified with --, we install
> long options for all them as well. Well, again, we use getopt_long_only.
>
> These are the same:
>
> gdb -q
> gdb --q
>
> Or these two:
>
> gdb -f
> gdb --f
>
> etc.
>
> Also, some options listed with single dash, supposedly indicating "short" option, like -ex here:
>
> --eval-command=COMMAND, -ex
>
> aren't really short options. They are more than one character long, and they work
> with both "-" and "--":
>
> gdb -ex CMD
> gdb --ex CMD
>
>
> Instead what we have, is I think:
>
> All options can be specified with - or --. GDB recognizes (all, short and long if you must) options if
> you truncate them, so long as enough of the option is present to be unambiguous. For some options,
> GDB recognizes a shorter form even if it would be ambiguous with some other options.
>
> So I wonder whether the direction should be the opposite, document all options with single '-'
> consistently throughout?
>
> I have to say that I never use = with "long" options, do you? I found it a bit weird to document
> that as the canonical form, but maybe that's just me.
>
> > -@item -init-command @var{file}
> > +@item -init-command=@var{file}
>
> This one missed the '-' -> '--'.
>
> > @itemx -ix @var{file}
> > @cindex @code{--init-command}
> > @cindex @code{-ix}
> > @@ -1032,7 +1048,7 @@ Execute commands from file @var{file} before loading the inferior (but
> > after loading gdbinit files).
> > @xref{Startup}.
Fascinating... I had never realized that this.
I really don't have a real preference about what the cannonical form
should be. My initial reaction was that the typical format for long
options is with '--'. But then I thought of the single-letter "long"
options like "q"; do we really want to promote "--q"? It does make it
clear that this is indeed a single-letter option name, and that it's
not to be combined with other such single-letter options. But I do
not think this is sufficient to justify emphasizing "--q" over "-q",
knowing that this will steer people towards the longer option. I know
we're talking nano-gains in terms of efficiency, but for me, -q is
cleaner and more efficient.
If we think as long-time GDB users, I think the simplest is to
start the help and documentation by explaining that, for all
options, we treat -OPTION and --OPTION exactly the same. And then
document the -OPTION version.
But, if people think we should make an effort to conform better
to more traditional argument handling, we could, in addition to
the doc about -OPTION and --OPTIONS, chose the following approach:
- For all options that are single-letter, use the single-dash form.
- For all multi-letter options, use the double-dashes form.
--
Joel
^ permalink raw reply [flat|nested] 5+ messages in thread
end of thread, other threads:[~2021-08-01 23:19 UTC | newest]
Thread overview: 5+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2021-06-11 19:26 [RFA] Fix/complete option list/description in manual and in gdb --help Philippe Waroquiers
2021-06-12 10:04 ` Eli Zaretskii
2021-06-17 10:23 ` Pedro Alves
2021-06-20 20:58 ` Philippe Waroquiers
2021-08-01 23:19 ` Joel Brobecker
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).