From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mailsec101.isp.belgacom.be (mailsec101.isp.belgacom.be [195.238.20.97]) by sourceware.org (Postfix) with ESMTPS id C32613857C62 for ; Sun, 6 Jun 2021 14:39:35 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org C32613857C62 IronPort-SDR: strFnE+FtjT9HNGzUH5C7zLdxwt/wrPXb7nl3TWb8VWs1+HLGbEWc3XaV5kLvYQvzljArta96F OpLatFamoLM8m4mZ5VOvSUPTyp09vxGqKli/5rlXWrGPwDyjczAFb8gtxRg7BuolpmOZwCW9zU DlF6+aVoELXvDSFhU+43QlC6oFOao9Y73ZiVWo8fufZYtUGIE7RhSVnDHGTcB5l1j+RCesF7Sx jmCboz/dxT9BQ9QhMqAEKY76tOOIV1fDjcSKczbd/CSi2HLcsYgQfPL/sLlEOF3LZIzsClQ5TA t74= X-IPAS-Result: =?us-ascii?q?A2BcBwCd3bxg/yFRiNlagRKBToN4iWiEUIZSgh87AVSaN?= =?us-ascii?q?xSBaAsBAQEBAQEBAQEJPgECBAEBhFCCAyY1CA4CBAEBAQEDAgMBAQEBBQEBB?= =?us-ascii?q?gEBAQEBAQUEAYEDhS9GgjgihCMBIyNPg3ODDKlhgQGEZINZgWKBOoh6foQpg?= =?us-ascii?q?VVEgRWCbYR6aoVPBIFULT8GARYnJisBBYEhCgw7BA4eCEEykHATqjssB4Mfg?= =?us-ascii?q?SYGC5wmGSuDXpFKkDsBtGCBEYQ6gVUBghJtU4JqTxkOjisWji5CZwIGCgEBA?= =?us-ascii?q?wlXASIBiksBAQ?= IronPort-PHdr: A9a23:F8DKaBJ3j3V3MMw5SdmcuL5mWUAX0o4c3iYr45Yqw4hDbr6kt8y7e hCGtLM21AOCBN2Ko9t/yMPu+5j6XmIB5ZvT+FsjS7drEyE/tMMNggY7C9SEA0CoZNTjbig9A dgQHAQ9pyLzPkdaAtvxaEPPqXOu8zESBg//NQ1oLejpB4Lelcu62/229pHJbQhEmDWwbbxvI BmqqQjaq9Ubj5ZlJqst0BXCv2FGe/5RxWNmJFKTmwjz68Kt95N98Cpepuws+ddYXar1Y6o3Q 7pYDC87M28u/83kqQPDTQqU6XQCVGgdjwdFDBLE7BH+WZfxrzf6u+9g0ySUIcH6UbY5Uimk4 qx2ShHnlT0HOiY5/m/Jl8J+gqFVrhWuqBJw2IPYfIKYOeBicq7HYd8WWWxMVdtRWSxbBYO8a pMCAfABPeZZq4n9pkMOrQOgCgKxBOzg0CVIhnjv3a0n0uQuDxvG3Bc9FN8JqHTUrNT1NKMTU eCt1KnH0y/Pbv1M1jfn74jIaw0hofCSUrJqasrc0lIvFwDFj1WWt4PlIymZ2f8TvGWC6edrS O2ghXI9pQ5rvjiv2tkjipPPho8NyV3J+jl1zJgpKdCmR0N2Y96qHZVeuS2GOIV4TcwvTW92t Cg01LALu4K3cSoFxpkm2RPSduCLfoqU7xzsW+udPDF1j29mdrKnnxu+71Wsx+/mWsWp3ltHr zBJn9rRunwX2RHe5M6KQeZn8Ei7wzaAzQXT5/lBIUAziKXUNYYswqU1lpoPqUTDGTL2mFnug K+WaEok/u+o5vziYrr7vJOcN4h0igTgPag2m8y/B/o3MhQWUmSF5Oix1qfv8VD3TbhLlPE7k bTVvIrUKMkVvqK5BhVa0ocn6xaxFTem19EYkGEfLFJFeRKHi4npO0nWIP/mF/u+jU6jkC1sx /DfI73hA4vCLmLYkLr6ZrZ96E5dyAwtwtBD/Z5bEa8OLOrpWkDtrNzYEgM5MwuszuboFdpyz ZoSWXqVDa+FLKzSsUGH5vk0LumXY48VpSz9JOQ76P/gl3A5g0EScbOu3ZsNZ3CyBu5mLFmBY XrwntcBFn8HvhI+TOzrjF2CUCZTZ26sUK4m6DA0EpimDYDaRoCwgbyOwj27HoZNa2BdCVCNE XHoeJuYW/sWcy2dPJwprjtRWrSrDpcoyRquuRTS0L16NOHZ5SQCuNTkztcmyffUkEQK9T1wD tyF3imyRntzh34JSiUtlPRnoU15y0+b3O5niuZfDMFS6ulSehw5JJjR06pwBoahCUr6Yt6VR QP+EZ2dCjYrQ4dpq+I= IronPort-HdrOrdr: A9a23:RIhGzavIwVy4B5z44TVajFpL7skDYdV00zEX/kB9WHVpm62j5q WTdZEgviMc5wx+ZJhNo7290cq7MBHhHPxOi7X5VI3KNDUO3lHIEGgI1+TfKlPbdxEX8IZmpM Rdm6wXMr3NMWQ= X-IronPort-Anti-Spam-Filtered: true Received: from 33.81-136-217.adsl-dyn.isp.belgacom.be (HELO md.home) ([217.136.81.33]) by relay.proximus.be with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 06 Jun 2021 16:39:33 +0200 From: Philippe Waroquiers 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 Message-Id: <20210606143927.29069-1-philippe.waroquiers@skynet.be> X-Mailer: git-send-email 2.20.1 MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Spam-Status: No, score=-13.2 required=5.0 tests=BAYES_00, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, GIT_PATCH_0, RCVD_IN_DNSWL_LOW, SPF_HELO_NONE, SPF_PASS, TXREP autolearn=ham autolearn_force=no version=3.4.2 X-Spam-Checker-Version: SpamAssassin 3.4.2 (2018-09-13) on server2.sourceware.org X-BeenThere: gdb-patches@sourceware.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Gdb-patches mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sun, 06 Jun 2021 14:39:39 -0000 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