Re: [PATCH 2/4] GDBServer: give more complete usage information

Pedro Alves
2015-03-21T17:05:42Z

On 03/21/2015 02:34 AM, Cleber Rosa wrote:
> --attach/--multi are currently only mentioned on the usage info first lines,
> the meaning of PROG is completely absent and COMM/PID text is unstructured.
>
> The words and structure chosen may not be perfect but IMHO this is an improvement.

Thanks, indeed this is in clear need of TLC.

I don't think we should put the FOO BAR options under structured
output though. I don't think it's usual. Looking at a few core
utils's --help, I saw none that did that. I think its better to just
extend the intro part to explain PROG, etc.

I went ahead and did that, along with a few more changes. Let me
know what you think.

Thanks!

------------
From 2e305602202b753b29d4088ff722150dd7b7fccd Mon Sep 17 00:00:00 2001
From: Pedro Alves <palves@redhat.com>
Date: Sat, 21 Mar 2015 17:00:23 +0000
Subject: [PATCH] GDBServer: give more complete usage information

--attach/--multi are currently only mentioned on the usage info first
lines, the meaning of PROG is completely absent and the COMM text does
not mention 'stdio'.

A few options are missing:

. '-/stdio' is not mentioned as COMM variant.

. --disable-randomization / --no-disable-randomization is not mentioned.

Although the manual has a comment saying these are superceded by
QDisableRandomization, that only makes sense for "run" in
extended-remote mode. When we start gdbserver passing it a PROG,
--disable-randomization / --no-disable-randomization do take effect.
So I think we should document these.

. We show --debug / --remote-debug, so might as well show --disable-packet too.

GDB's --help has this "For more information, consult the GDB manual"
blurb that is missing in GDBserver's --help.

Then shuffle things around a bit into "Operating modes", "Other
options" and "Debug options" sections, similarly to GDB's --help
structure.

Before:

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
$ ./gdbserver/gdbserver --help
Usage: gdbserver [OPTIONS] COMM PROG [ARGS ...]
gdbserver [OPTIONS] --attach COMM PID
gdbserver [OPTIONS] --multi COMM

COMM may either be a tty device (for serial debugging), or
HOST:PORT to listen for a TCP connection.

Options:
--debug Enable general debugging output.
--debug-format=opt1[,opt2,...]
Specify extra content in debugging output.
Options:
all
none
timestamp
--remote-debug Enable remote protocol debugging output.
--version Display version information and exit.
--wrapper WRAPPER -- Run WRAPPER to start new programs.
--once Exit after the first connection has closed.
Report bugs to "<http://www.gnu.org/software/gdb/bugs/>".
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

After:

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
$ ./gdbserver/gdbserver --help
Usage: gdbserver [OPTIONS] COMM PROG [ARGS ...]
gdbserver [OPTIONS] --attach COMM PID
gdbserver [OPTIONS] --multi COMM

COMM may either be a tty device (for serial debugging),
HOST:PORT to listen for a TCP connection, or '-' or 'stdio' to use
stdin/stdout of gdbserver.
PROG is the executable program. ARGS are arguments passed to inferior.
PID is the process ID to attach to, when --attach is specified.

Operating modes:

--attach Attach to running process PID.
--multi Start server without a specific program, and
only quit when explicitly commanded.
--once Exit after the first connection has closed.
--help Print this message and then exit.
--version Display version information and exit.

Other options:

--wrapper WRAPPER -- Run WRAPPER to start new programs.
--disable-randomization
Run PROG with address space randomization disabled.
--no-disable-randomization
Don't disable address space randomization when
starting PROG.

Debug options:

--debug Enable general debugging output.
--debug-format=opt1[,opt2,...]
Specify extra content in debugging output.
Options:
all
none
timestamp
--remote-debug Enable remote protocol debugging output.
--disable-packet=opt1[,opt2,...]
Disable support for RSP packets or features.
Options:
vCont, Tthread, qC, qfThreadInfo and
threads (disable all threading packets).

For more information, consult the GDB manual (available as on-line
info or a printed manual).
Report bugs to "<http://www.gnu.org/software/gdb/bugs/>".
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

gdb/gdbserver/ChangeLog:
2015-03-20 Pedro Alves <palves@redhat.com>
Cleber Rosa <crosa@redhat.com>

* server.c (gdbserver_usage): Reorganize and extend the usage
message.
---
gdb/gdbserver/server.c | 40 +++++++++++++++++++++++++++++++++-------
1 file changed, 33 insertions(+), 7 deletions(-)

diff --git a/gdb/gdbserver/server.c b/gdb/gdbserver/server.c
index 96b31b8..3408ef7 100644
--- a/gdb/gdbserver/server.c
+++ b/gdb/gdbserver/server.c
@@ -2996,10 +2996,32 @@ gdbserver_usage (FILE *stream)
"\tgdbserver [OPTIONS] --attach COMM PID\n"
"\tgdbserver [OPTIONS] --multi COMM\n"
"\n"
- "COMM may either be a tty device (for serial debugging), or \n"
- "HOST:PORT to listen for a TCP connection.\n"
+ "COMM may either be a tty device (for serial debugging),\n"
+ "HOST:PORT to listen for a TCP connection, or '-' or 'stdio' to use \n"
+ "stdin/stdout of gdbserver.\n"
+ "PROG is the executable program. ARGS are arguments passed to inferior.\n"
+ "PID is the process ID to attach to, when --attach is specified.\n"
+ "\n"
+ "Operating modes:\n"
+ "\n"
+ " --attach Attach to running process PID.\n"
+ " --multi Start server without a specific program, and\n"
+ " only quit when explicitly commanded.\n"
+ " --once Exit after the first connection has closed.\n"
+ " --help Print this message and then exit.\n"
+ " --version Display version information and exit.\n"
+ "\n"
+ "Other options:\n"
+ "\n"
+ " --wrapper WRAPPER -- Run WRAPPER to start new programs.\n"
+ " --disable-randomization\n"
+ " Run PROG with address space randomization disabled.\n"
+ " --no-disable-randomization\n"
+ " Don't disable address space randomization when\n"
+ " starting PROG.\n"
+ "\n"
+ "Debug options:\n"
"\n"
- "Options:\n"
" --debug Enable general debugging output.\n"
" --debug-format=opt1[,opt2,...]\n"
" Specify extra content in debugging output.\n"
@@ -3008,10 +3030,14 @@ gdbserver_usage (FILE *stream)
" none\n"
" timestamp\n"
" --remote-debug Enable remote protocol debugging output.\n"
- " --version Display version information and exit.\n"
- " --wrapper WRAPPER -- Run WRAPPER to start new programs.\n"
- " --once Exit after the first connection has "
- "closed.\n");
+ " --disable-packet=opt1[,opt2,...]\n"
+ " Disable support for RSP packets or features.\n"
+ " Options:\n"
+ " vCont, Tthread, qC, qfThreadInfo and \n"
+ " threads (disable all threading packets).\n"
+ "\n"
+ "For more information, consult the GDB manual (available as on-line \n"
+ "info or a printed manual).\n");
if (REPORT_BUGS_TO[0] && stream == stdout)
fprintf (stream, "Report bugs to \"%s\".\n", REPORT_BUGS_TO);
}
--
1.9.3