From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 3602 invoked by alias); 24 Jan 2008 21:33:42 -0000 Received: (qmail 3475 invoked by uid 22791); 24 Jan 2008 21:33:20 -0000 X-Spam-Check-By: sourceware.org Received: from rock.gnat.com (HELO rock.gnat.com) (205.232.38.15) by sourceware.org (qpsmtpd/0.31) with ESMTP; Thu, 24 Jan 2008 21:33:01 +0000 Received: from localhost (localhost.localdomain [127.0.0.1]) by filtered-rock.gnat.com (Postfix) with ESMTP id 232332A9665 for ; Thu, 24 Jan 2008 16:32:59 -0500 (EST) Received: from rock.gnat.com ([127.0.0.1]) by localhost (rock.gnat.com [127.0.0.1]) (amavisd-new, port 10024) with LMTP id jS8yBKaxi8M4 for ; Thu, 24 Jan 2008 16:32:59 -0500 (EST) Received: from joel.gnat.com (localhost.localdomain [127.0.0.1]) by rock.gnat.com (Postfix) with ESMTP id ABB882A9660 for ; Thu, 24 Jan 2008 16:32:58 -0500 (EST) Received: by joel.gnat.com (Postfix, from userid 1000) id 7573FE7ACB; Thu, 24 Jan 2008 13:32:56 -0800 (PST) Date: Thu, 24 Jan 2008 21:36:00 -0000 From: Joel Brobecker To: gdb-patches@sourceware.org Subject: [RFA/doco] document "set/show multiple-choice-auto-select" Message-ID: <20080124213256.GA5796@adacore.com> Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="RnlQjJ0d97Da+TV1" Content-Disposition: inline User-Agent: Mutt/1.4.2.2i Mailing-List: contact gdb-patches-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-patches-owner@sourceware.org X-SW-Source: 2008-01/txt/msg00592.txt.bz2 --RnlQjJ0d97Da+TV1 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline Content-length: 2460 Hi Eli, I usually say that I'll send a doco update after a patch is accepted, but in this case, for once I'm sending the doco patch before I started working on the patch itself :). The patch will follow soon, but the general principal behind the change is accepted I think, so it's safe to work on the documentation a bit in advance. I expanded a bit on the "Breakpoint Menus" section, giving more details as to when a multiple-choice menu could happen in the context of breakpoints. This is because the text as it is written now assumes that you only get the menu when doing "break function_name", which is incorrect. I tried to make the text better as well as introducing the new set/show command. The problem I'm having which I haven't solved in this patch is that the menu can be needed in other circumstances than breakpoints. During general expression evaluations such as "print function_name" for instance, where function_name is ambiguous. In Ada, we also print a menu and ask the user to choose, except that the "all" choice is not available and the user can choose one and only one choice. In C++, I *think* that one symbol at random gets selected, but I'd appreciate if this could be confirmed. The documentation does not cover that aspect yet. Right now, the documentation about menus is included as part of breakpoint support. I updated the documentation within that context for now. I'm not sure how to extend the documentation to cover the cases where breakpoints are not involved yet. One way of doing it would be to extract the current section out of the breakpoint documentation and make it more general. Another way would be to leave it as is, and then make another section somewhere else (somewhere inside "Examining Data/Program_Variables" that explains what happens when an ambiguous symbol name is used, with a reference to the Breakpoints Menu node. I think that the first option is a little bit better, but it's hard to tell. One single general section allows us to have all the information in one single place. But the generality of it might make it harder to understand in practice. With two different locations, we can be more practical in our explanations. What do you think? 2008-01-24 Joel Brobecker * gdb.texinfo (Breakpoint Menus): Improve documentation. Add documentation for set/show multiple-choice-auto-select. Tested by rebuilding the HTML documentation. -- Joel --RnlQjJ0d97Da+TV1 Content-Type: text/plain; charset=us-ascii Content-Disposition: attachment; filename="mcas-doc.diff" Content-length: 3823 Index: gdb.texinfo =================================================================== RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v retrieving revision 1.458 diff -u -p -r1.458 gdb.texinfo --- gdb.texinfo 19 Jan 2008 13:37:13 -0000 1.458 +++ gdb.texinfo 24 Jan 2008 21:02:37 -0000 @@ -3798,19 +3798,31 @@ end @subsection Breakpoint Menus @cindex overloading @cindex symbol overloading +@cindex Ada generics +@cindex C++ templates -Some programming languages (notably C@t{++} and Objective-C) permit a -single function name -to be defined several times, for application in different contexts. -This is called @dfn{overloading}. When a function name is overloaded, -@samp{break @var{function}} is not enough to tell @value{GDBN} where you want -a breakpoint. You can use explicit signature of the function, as in -@samp{break @var{function}(@var{types})}, to specify which -particular version of the function you want. Otherwise, @value{GDBN} offers -you a menu of numbered choices for different possible breakpoints, and -waits for your selection with the prompt @samp{>}. The first two -options are always @samp{[0] cancel} and @samp{[1] all}. Typing @kbd{1} -sets a breakpoint at each definition of @var{function}, and typing +A breakpoint location expression (@ref{Specify Location}) is sometimes +ambiguous. For instance, some programming languages (notably Ada, +C@t{++} and Objective-C) permit a single function name to be defined +several times, for application in different contexts. This is called +@dfn{overloading}. Another example involving Ada is generics. A +@dfn{generic package} is similar to C@t{++} templates and is typically +instantiated several times, resulting in the same function name being +defined in different contexts. + +In some cases and depending on the language, it is possible to make +the location unambiguous. For instance in C@t{++}, you can specify +the signature of the function you want to break on, as in @samp{break +@var{function}(@var{types})}. In Ada, using the fully qualified +name of your function often makes the location expression unambiguous. + +By default when the location expression is ambiguous, @value{GDBN} +automatically selects all possible locations. But this behavior +can be configured so that a menu is of numbered choices for different +possible breakpoints is displayed (see below). In that case, +the @value{GDBN} waits for your selection with the prompt @samp{>}. +The first two options are always @samp{[0] cancel} and @samp{[1] all}. +Typing @kbd{1} sets a breakpoint at each possible locations and typing @kbd{0} aborts the @code{break} command without setting any new breakpoints. @@ -3841,6 +3853,26 @@ Use the "delete" command to delete unwan @end group @end smallexample +@table @code +@kindex set multiple-choice-auto-select +@item set multiple-choice-auto-select @var{mode} +@cindex menu auto select +This option allows you to adjust the debugger behavior when a location +expression is ambiguous. When set to @var{off}, the debugger does not +perform any automatic selection, and instead asks you to select from +a multiple-choice menu which choices should be used. When set to @var{all}, +@value{GDBN} automatically selects all possible choices. This is strictly +equivalent to selecting choice @var{1} in the multiple-choice menu, +except that the menu is not displayed. And finally, this option can be +set to @var{cancel}, which causes the abort of the command if the +location expression is ambiguous. By default, this option is set to +@var{all}. + +@kindex show multiple-choice-auto-select +@item show multiple-choice-auto-select +Show the current value of the multiple-choice-auto-select setting. +@end table + @c @ifclear BARETARGET @node Error in Breakpoints @subsection ``Cannot insert breakpoints'' --RnlQjJ0d97Da+TV1--