From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mailsec109.isp.belgacom.be (mailsec109.isp.belgacom.be [195.238.20.105]) by sourceware.org (Postfix) with ESMTPS id E7CBC388E81F for ; Sun, 21 Jun 2020 18:31:40 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.3.2 sourceware.org E7CBC388E81F IronPort-SDR: x33BoXXHNaNjjTmmV66NdzipeyO9cAc30cRabrqd4wvq9hbkkKQ4honk1MgjaZ2CHV56JbRlSs lkeqj2St+jxkF8nS7R1SvPP5XOzDqxGA11vRjT/3YA22UE/Y2xLCF/1eXhglRbTYJtF1ai2EuL wvZp1im8MxjNucPWtuMYZhmOiS561SFOLwN9yUSC1GAPBBsxv3jhwvTfThA/1cx5SaduYdfIIe eZhigwYudtnciQ7YRFpSf6o7WfFz1d+SROJtfU3C99g/9/Z7zIim1GXKkcFnk7lEAZ28VQ+zeE V6Y= IronPort-PHdr: =?us-ascii?q?9a23=3AlxaD0RzV2eaCsqbXCy+O+j09IxM/srCxBDY+r6?= =?us-ascii?q?Qd2u4RIJqq85mqBkHD//Il1AaPAdyGrasU06GP6f6ocFdDyK7JiGoFfp1IWk?= =?us-ascii?q?1NouQttCtkPvS4D1bmJuXhdS0wEZcKflZk+3amLRodQ56mNBXdrXKo8DEdBA?= =?us-ascii?q?j0OxZrKeTpAI7SiNm82/yv95HJbAhEmTqwbalvIBi1sQndudQajZVjJ60s1h?= =?us-ascii?q?bHv3xEdvhMy2h1P1yThRH85smx/J5n7Stdvu8q+tBDX6vnYak2VKRUAzs6PW?= =?us-ascii?q?874s3rrgTDQhCU5nQASGUWkwFHDBbD4RrnQ5r+qCr6tu562CmHIc37SK0/VD?= =?us-ascii?q?q+46t3ThLjlSEKPCM7/m7KkMx9lKJVrgy8qRJxwIDaZ4OaNPRxca3SZt4WWW?= =?us-ascii?q?lMU9xNWyFbHo+wc40CBPcBM+ZCqIn9okMDowG+BQmtAOPvyydIhmfo0qYn0+?= =?us-ascii?q?suCxvG3As5H9ITsXTbss/1NLwPWu2y1KnIzTTDb/dX2Tfl8IjHbAotoP+WUr?= =?us-ascii?q?JqdsrR0FQvFwLbgVWKsozoJCiV1ucNsmid8eVgSfijhHU5pAxopDWk28gjhJ?= =?us-ascii?q?XTiI0P1lDE6Tt2wJwzJdCgR0B2YcCpHZReui+VOYZ7Xt4uTn1ntis+xLALt5?= =?us-ascii?q?+2cDYExpkp2hLSb/OKfoeG7xzjWuicPSt1iWxkdb+hhxu/9U6twfD/WMmsyF?= =?us-ascii?q?tGsDdJn9vWunwQ2RHe69KLR/hg8ku71zuC2Qbe4fxeL08uj6rUMZshz6Y1lp?= =?us-ascii?q?oUrEvMADf7mF7zjK+KbkUk/fWo6/j/brXmuJCcM4h0hxn7MqszgMC/AeM4Mg?= =?us-ascii?q?0QUGSD+OS80qPs/VHhTblUk/E7kLPVvI3UKMkavKK0ABJZ3pwt5huxFzum1c?= =?us-ascii?q?4XnXgDLFJLYhKHiI3pNknWIPD4DPe/h1WskC9zx//YJLHgDI/CLmLEkLf4YL?= =?us-ascii?q?Z96lBTyBAozd1E/JJUCbEAIPTtVU/trtDXFQE2PxSuw+n7ENV9yp8eWWWXD6?= =?us-ascii?q?+WLazdqkaE5vo1LOmQeIAVuCjyK+M+6v71in85hEUdcrW30poZcn+4BOppL1?= =?us-ascii?q?+eYXr2jdcLCX0KsRYmTOz2lF2CViZeZ26yX6I94jE7CZqmDZ/dSYy3jr2Oxj?= =?us-ascii?q?27HppPZmBbC1CDD23od56fVvcXayKTIslhnSIYVbS7UIAuy0LmiAivxLZta/?= =?us-ascii?q?Ld5iYYuInLz99o/ebeihgo+HpzFcvO/XuKSjRMnmIMRicu0ehAqFZ600qC3L?= =?us-ascii?q?Jjy6hAFd1X5utRX0ElPITb1vF7BsrpchnCb9GEVBCsT4P1UnkKUtstzopWMA?= =?us-ascii?q?5GENK4g0Wb0g=3D=3D?= X-IronPort-Anti-Spam-Filtered: true X-IronPort-Anti-Spam-Result: =?us-ascii?q?A2BNCgCZpu9e/yFRiNlmHQEBAQEJARI?= =?us-ascii?q?BBQUBR4FDAoNrX40lhXmDEZp9CwEBAQEBAQEBAQgsAQIEAQGERwKCKSU4EwI?= =?us-ascii?q?DAQEBAwIFAQEGAQEBAQEBBQQBhg5FQgEQAQQBgWIigxYGMgEjIxA/ElcZGoM?= =?us-ascii?q?MgwG4NIVRg2+BQIE4AYd1coQKgUw/gRABgluFB4V7IgSPA4oCmkxaKAeCXYE?= =?us-ascii?q?GBAuNUIo1DyCCcZwKIZJtmTSDWYFqgXhtU4JpUBkNhUyJCY4SQjA3AgYIAQE?= =?us-ascii?q?DCVcBIgGIbIQZOyyCGgEB?= X-IPAS-Result: =?us-ascii?q?A2BNCgCZpu9e/yFRiNlmHQEBAQEJARIBBQUBR4FDAoNrX?= =?us-ascii?q?40lhXmDEZp9CwEBAQEBAQEBAQgsAQIEAQGERwKCKSU4EwIDAQEBAwIFAQEGA?= =?us-ascii?q?QEBAQEBBQQBhg5FQgEQAQQBgWIigxYGMgEjIxA/ElcZGoMMgwG4NIVRg2+BQ?= =?us-ascii?q?IE4AYd1coQKgUw/gRABgluFB4V7IgSPA4oCmkxaKAeCXYEGBAuNUIo1DyCCc?= =?us-ascii?q?ZwKIZJtmTSDWYFqgXhtU4JpUBkNhUyJCY4SQjA3AgYIAQEDCVcBIgGIbIQZO?= =?us-ascii?q?yyCGgEB?= Received: from 33.81-136-217.adsl-dyn.isp.belgacom.be (HELO md.home) ([217.136.81.33]) by relay.skynet.be with ESMTP/TLS/ECDHE-RSA-AES128-GCM-SHA256; 21 Jun 2020 20:31:36 +0200 From: Philippe Waroquiers To: gdb-patches@sourceware.org Subject: [RFAv8 3/3] NEWS and documentation for alias default-args related concept and commands. Date: Sun, 21 Jun 2020 20:31:30 +0200 Message-Id: <20200621183130.11503-4-philippe.waroquiers@skynet.be> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20200621183130.11503-1-philippe.waroquiers@skynet.be> References: <20200621183130.11503-1-philippe.waroquiers@skynet.be> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Spam-Status: No, score=-12.6 required=5.0 tests=BAYES_00, DKIM_SIGNED, DKIM_VALID, GIT_PATCH_0, RCVD_IN_DNSWL_LOW, RCVD_IN_MSPIKE_H4, RCVD_IN_MSPIKE_WL, 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, 21 Jun 2020 18:31:43 -0000 gdb/ChangeLog YYYY-MM-DD Philippe Waroquiers * NEWS: Mention changeto the alias command. gdb/doc/ChangeLog YYYY-MM-DD Philippe Waroquiers * gdb.texinfo (Command aliases default args): New node documenting how to use default args for a command using aliases. (Aliases): Document the new 'DEFAULT-ARGS...' option. (Help): Update help aliases text and describe when full alias definition is provided. --- gdb/NEWS | 15 ++++++ gdb/doc/gdb.texinfo | 118 +++++++++++++++++++++++++++++++++++++++++--- 2 files changed, 127 insertions(+), 6 deletions(-) diff --git a/gdb/NEWS b/gdb/NEWS index cebfd18f0c..f7585133c5 100644 --- a/gdb/NEWS +++ b/gdb/NEWS @@ -79,6 +79,21 @@ tui new-layout NAME WINDOW WEIGHT [WINDOW WEIGHT]... Define a new TUI layout, specifying its name and the windows that will be displayed. +* Changed commands + +alias [-a] [--] ALIAS = COMMAND [DEFAULT-ARGS...] + The alias command can now specify default args for an alias. + GDB automatically prepends the alias default args to the argument list + provided explicitly by the user. + For example, to have a backtrace with full details, you can define + an alias 'bt_ALL' as + 'alias bt_ALL = backtrace -entry-values both -frame-arg all + -past-main -past-entry -full'. + Alias default arguments can also use a set of nested 'with' commands, + e.g. 'alias pp10 = with print pretty -- with print elem 10 -- print' + defines the alias pp10 that will pretty print a maximum of 10 elements + of the given expression (if the expression is an array). + * New targets GNU/Linux/RISC-V (gdbserver) riscv*-*-linux* diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index 59e3e75d18..7f572c37c5 100644 --- a/gdb/doc/gdb.texinfo +++ b/gdb/doc/gdb.texinfo @@ -1577,6 +1577,7 @@ show you the alternatives available, if there is more than one possibility). * Command Settings:: How to change default behavior of commands * Completion:: Command completion * Command Options:: Command options +* Command aliases default args:: Automatically prepend default arguments to user-defined aliases * Help:: How to ask @value{GDBN} for help @end menu @@ -1997,6 +1998,89 @@ uppercase. (For more on using the @code{print} command, see @ref{Data, ,Examining Data}.) +@node Command aliases default args +@section Automatically prepend default arguments to user-defined aliases + +You can tell @value{GDBN} to always prepend some default arguments to +the list of arguments provided explicitly by the user when using a +user-defined alias. + +If you repeatedly use the same arguments or options for a command, you +can define an alias for this command and tell @value{GDBN} to +automatically prepend these arguments or options to the list of +arguments you type explicitly when using the alias@footnote{@value{GDBN} +could easily accept default arguments for pre-defined commands and aliases, +but it was deemed this would be confusing, and so is not allowed.}. + +For example, if you often use the command @code{thread apply all} +specifying to work on the threads in ascending order and to continue in case it +encounters an error, you can tell @value{GDBN} to automatically preprend +the @code{-ascending} and @code{-c} options by using: + +@smallexample +(@value{GDBP}) alias thread apply asc-all = thread apply all -ascending -c +@end smallexample + +Once you have defined this alias with its default args, any time you type +the @code{thread apply asc-all} followed by @code{some arguments}, +@value{GDBN} will execute @code{thread apply all -ascending -c some arguments}. + +To have even less to type, you can also define a one word alias: +@smallexample +(@value{GDBP}) alias t_a_c = thread apply all -ascending -c +@end smallexample + +As usual, unambiguous abbreviations can be used for @var{alias} +and @var{default-args}. + +The different aliases of a command do not share their default args. +For example, you define a new alias @code{bt_ALL} showing all possible +information and another alias @code{bt_SMALL} showing very limited information +using: +@smallexample +(@value{GDBP}) alias bt_ALL = backtrace -entry-values both -frame-arg all \ + -past-main -past-entry -full +(@value{GDBP}) alias bt_SMALL = backtrace -entry-values no -frame-arg none \ + -past-main off -past-entry off +@end smallexample + +(For more on using the @code{alias} command, see @ref{Aliases}.) + +Default args are not limited to the arguments and options of @var{command}, +but can specify nested commands if @var{command} accepts such a nested command +as argument. +For example, the below defines @code{faalocalsoftype} that lists the +frames having locals of a certain type, together with the matching +local vars: +@smallexample +(@value{GDBP}) alias faalocalsoftype = frame apply all info locals -q -t +(@value{GDBP}) faalocalsoftype int +#1 0x55554f5e in sleeper_or_burner (v=0xdf50) at sleepers.c:86 +i = 0 +ret = 21845 +@end smallexample + +This is also very useful to define an alias for a set of nested @code{with} +commands to have a particular combination of temporary settings. For example, +the below defines the alias @code{pp10} that pretty prints an expression +argument, with a maximum of 10 elements if the expression is a string or +an array: +@smallexample +(@value{GDBP}) alias pp10 = with print pretty -- with print elements 10 -- print +@end smallexample +This defines the alias @code{pp10} as being a sequence of 3 commands. +The first part @code{with print pretty --} temporarily activates the setting +@code{set print pretty}, then launches the command that follows the separator +@code{--}. +The command following the first part is also a @code{with} command that +temporarily changes the setting @code{set print elements} to 10, then +launches the command that follows the second separator @code{--}. +The third part @code{print} is the command the @code{pp10} alias will launch, +using the temporary values of the settings and the arguments explicitly given +by the user. +For more information about the @code{with} command usage, +see @ref{Command Settings}. + @node Help @section Getting Help @cindex online documentation @@ -2016,7 +2100,7 @@ display a short list of named classes of commands: (@value{GDBP}) help List of classes of commands: -aliases -- Aliases of other commands +aliases -- User-defined aliases of other commands breakpoints -- Making program stop at certain points data -- Examining data files -- Specifying and examining files @@ -2043,8 +2127,9 @@ Command name abbreviations are allowed if unambiguous. Using one of the general help classes as an argument, you can get a list of the individual commands in that class. If a command has aliases, the aliases are given after the command name, separated by -commas. For example, here is the help display for the class -@code{status}: +commas. If an alias has default arguments, the full definition of +the alias is given after the first line. +For example, here is the help display for the class @code{status}: @smallexample (@value{GDBP}) help status @@ -2056,7 +2141,10 @@ List of commands: @c to fit in smallbook page size. info, inf, i -- Generic command for showing things about the program being debugged -info address -- Describe where symbol SYM is stored. +info address, iamain -- Describe where symbol SYM is stored. + alias iamain = info address main +info all-registers -- List of all registers and their contents, + for selected stack frame. ... show, info set -- Generic command for showing things about the debugger @@ -2072,6 +2160,8 @@ With a command name as @code{help} argument, @value{GDBN} displays a short paragraph on how to use that command. If that command has one or more aliases, @value{GDBN} will display a first line with the command name and all its aliases separated by commas. +This first line will be followed by the full definition of all aliases +having default arguments. @kindex apropos @item apropos [-v] @var{regexp} @@ -2092,7 +2182,7 @@ results in: @smallexample @group alias -- Define a new command that is an alias of an existing command -aliases -- Aliases of other commands +aliases -- User-defined aliases of other commands @end group @end smallexample @@ -27502,7 +27592,7 @@ You can define a new alias with the @samp{alias} command. @table @code @kindex alias -@item alias [-a] [--] @var{ALIAS} = @var{COMMAND} +@item alias [-a] [--] @var{ALIAS} = @var{COMMAND} [DEFAULT-ARGS...] @end table @@ -27513,12 +27603,28 @@ underscores. @var{COMMAND} specifies the name of an existing command that is being aliased. +@var{COMMAND} can also be the name of an existing alias. In this case, +@var{COMMAND} cannot be an alias that has default arguments. + The @samp{-a} option specifies that the new alias is an abbreviation of the command. Abbreviations are not used in command completion. The @samp{--} option specifies the end of options, and is useful when @var{ALIAS} begins with a dash. +You can specify @var{default-args} for your alias. +These @var{default-args} will be automatically added before the alias +arguments typed explicitly on the command line. + +For example, the below defines an alias @code{btfullall} that shows all local +variables and all frame arguments: +@smallexample +(@value{GDBP}) alias btfullall = backtrace -full -frame-arguments all +@end smallexample + +For more information about @var{default-args}, see @ref{Command aliases default args, +,Automatically prepend default arguments to user-defined aliases}. + Here is a simple example showing how to make an abbreviation of a command so that there is less to type. Suppose you were tired of typing @samp{disas}, the current -- 2.20.1