Re: [PATCH 40/40] Document breakpoints / linespec & co improvements (manual + NEWS)

[Pedro Alves <palves at redhat dot com>]

On 06/02/2017 02:33 PM, Pedro Alves wrote:
> On 06/02/2017 02:01 PM, Eli Zaretskii wrote:
>>> From: Pedro Alves <palves@redhat.com>
>>> Date: Fri,  2 Jun 2017 13:22:38 +0100
>>>
>>> +For example, assuming a program with symbols named @code{A::B::func}
>>> +and @code{B::func}, both commands @code{break -function func} and
>>> +@code{break -function B::func} set a breakpoint on both symbols.
>>
>> The 2 commands are long and include whitespace, so I'd suggest
>> enclosing each one in @w{..}, to avoid a line break in the middle of a
>> command.
>>
>> Also, I think @kbd is more appropriate here than @code, since you mean
>> commands the user will type, not just command names.
>>
>> I'm surprised you didn't change anything where the manual discusses
>> quoting of names and symbols.  For example, the node "Completion"
>> explicitly describes a use case with overloaded functions in C++; the
>> node "Symbols" describes a case with "::" that requires quoting.
>> There's another example in "Machine Code", and also in "Ambiguous
>> Expression", and in "Variables".  Maybe you already reviewed all of
>> those and concluded no changes were necessary, but I just thought I'd
>> mention them.
> 
> Thanks, I just didn't think of looking for quoting bits in the
> manual, for some reason.  I'll take a closer look.

I've now reviewed these, and it looks to be like only the "Completion"
node needs adjustment.  I replaced the example there with another
example that came to mind when I tried to think of when I use quoting.
I'm not sure it's "the most frequent" case, so I softened the "the"
to "a".  I also found there an ancient paragraph saying that GDB
inserts quoting automatically, which is plain false (and I don't
recall ever running a version of GDB that did that).  I also
added a cross reference to elsewhere in the manual where we discuss
the need for quoting of symbol names.

> 
>>
>>> +  ** GDB now has a much improved linespec and explicit locations TAB
>>> +     completion support, that better understands what you're
>>> +     completing and offers better suggestions.
>>
>> Is this a general improvement, or is it limited to C++ symbols?  If
>> the latter, suggest to mention that.
> 
> You're right.  It's more general than C++.

I've reordered the sections and split appart the C++-related
subsections to their own sections, to hopefully make things
a bit clearer.  I've also adjusted the wording in a couple
cases, and extended some cases with examples.

> 
>>
>>> +  ** GDB can now complete function parameters in linespecs and
>>> +     explicit locations, even without quoting.  When setting
>>> +     breakpoints, quoting around functions names to help with
>>> +     TAB-completion is generally no longer necessary.
>>
>> Likewise.
>>
>>> +  ** GDB can now set breakpoints functions marked with [abi:cxx11]
>>> +     tags.
>>
>> "on functions", I think.

Fixed.

>>
>> And btw, what are those tags?  
> 
> This is the best document that I know describing them:
> 
>  https://developers.redhat.com/blog/2015/02/05/gcc5-and-the-c11-abi/
> 
> Functions that ended up requiring an abi tag are demangled like this:
> 
>   string_printf[abi:cxx11](char const*, ...)
>                ^^^^^^^^^^^
> 
> That's an actual function in GDB.  It ended requiring an ABI tag
> because it returns std::string.  See intro of patch 39 for more.
> 
>> I don't think I see them documented in the manual; did I miss something?
> 
> Hmm, I guess we could add something, indeed.

I've added something now.  The "Debugging C Plus Plus" node has a 
section talking about setting breakpoints on overloaded functions
which looked like the right place for this.

The only thing I didn't address was the @code vs @kbd point.
See the other email.

Otherwise, how does this version look?

>From 746f2009e4d27da6d43844c36cc4b04ce71fe1d5 Mon Sep 17 00:00:00 2001
From: Pedro Alves <palves@redhat.com>
Date: Wed, 21 Jun 2017 16:04:40 +0100
Subject: [PATCH] Document breakpoints / linespec & co improvements (manual +
 NEWS)

gdb/doc/ChangeLog:
yyyy-mm-dd  Pedro Alves  <palves@redhat.com>

	* NEWS: Mention breakpoints, linespecs and explicit locations, and
	completion improvements.

gdb/doc/ChangeLog:
yyyy-mm-dd  Pedro Alves  <palves@redhat.com>

	* gdb.texinfo (Completion): Update need-quoting examples.  Remove
	false claim that GDB inserts quoting automatically.
	(Linespec Locations): Document how "function" is
	interpreted in C++.
	(Explicit Locations): Document how "-function" is interpreted in
	C++.  Document -qualified.
	(Debugging C Plus Plus): Document setting breakpoints in functions
	with ABI tags.
---
 gdb/doc/gdb.texinfo | 131 +++++++++++++++++++++++++++++++++++++++++++---------
 gdb/NEWS            |  71 ++++++++++++++++++++++++++++
 2 files changed, 180 insertions(+), 22 deletions(-)

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 9fb70f6..eff1f55 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -1638,39 +1638,56 @@ its notion of a word.  To permit word completion to work in this
 situation, you may enclose words in @code{'} (single quote marks) in
 @value{GDBN} commands.
 
-The most likely situation where you might need this is in typing the
-name of a C@t{++} function.  This is because C@t{++} allows function
-overloading (multiple definitions of the same function, distinguished
-by argument type).  For example, when you want to set a breakpoint you
-may need to distinguish whether you mean the version of @code{name}
-that takes an @code{int} parameter, @code{name(int)}, or the version
-that takes a @code{float} parameter, @code{name(float)}.  To use the
-word-completion facilities in this situation, type a single quote
+A likely situation where you might need this is in typing an
+expression that involves a C@t{++} symbol name with template
+parameters.  This is because when completing expressions, GDB treats
+the @samp{<} character as word delimiter, assuming that it's the
+less-than comparison operator (@pxref{C Operators, , C and C@t{++}
+Operators}).
+
+For example, when you want to call a C@t{++} template function
+interactively using the @code{print} or @code{call} commands, you may
+need to distinguish whether you mean the version of @code{name} that
+was specialized for @code{int}, @code{name<int>()}, or the version
+that was specialized for @code{float}, @code{name<float>()}.  To use
+the word-completion facilities in this situation, type a single quote
 @code{'} at the beginning of the function name.  This alerts
 @value{GDBN} that it may need to consider more information than usual
 when you press @key{TAB} or @kbd{M-?} to request word completion:
 
 @smallexample
-(@value{GDBP}) b 'bubble( @kbd{M-?}
-bubble(double,double)    bubble(int,int)
-(@value{GDBP}) b 'bubble(
+(@value{GDBP}) p 'func< @kbd{M-?}
+func<int>()    func<float>()
+(@value{GDBP}) p 'func<
 @end smallexample
 
-In some cases, @value{GDBN} can tell that completing a name requires using
-quotes.  When this happens, @value{GDBN} inserts the quote for you (while
-completing as much as it can) if you do not type the quote in the first
-place:
+When setting breakpoints however (@pxref{Specify Location}), you don't
+usually need to type a quote before the function name, because
+@value{GDBN} understands that you want to set a breakpoint on a
+function:
 
 @smallexample
-(@value{GDBP}) b bub @key{TAB}
-@exdent @value{GDBN} alters your input line to the following, and rings a bell:
-(@value{GDBP}) b 'bubble(
+(@value{GDBP}) b func< @kbd{M-?}
+func<int>()    func<float>()
+(@value{GDBP}) b func<
 @end smallexample
 
-@noindent
-In general, @value{GDBN} can tell that a quote is needed (and inserts it) if
-you have not yet started typing the argument list when you ask for
-completion on an overloaded symbol.
+This is true even in the case of typing the name of C@t{++} overloaded
+functions (multiple definitions of the same function, distinguished by
+argument type).  For example, when you want to set a breakpoint you
+don't need to distinguish whether you mean the version of @code{name}
+that takes an @code{int} parameter, @code{name(int)}, or the version
+that takes a @code{float} parameter, @code{name(float)}.
+
+@smallexample
+(@value{GDBP}) b bubble( @kbd{M-?}
+bubble(int)    bubble(double)
+(@value{GDBP}) b bubble(dou @kbd{M-?}
+bubble(double)
+@end smallexample
+
+See @ref{quoting names} for a description of other scenarios that
+require quoting.
 
 For more information about overloaded functions, see @ref{C Plus Plus
 Expressions, ,C@t{++} Expressions}.  You can use the command @code{set
@@ -7845,6 +7862,16 @@ name of @file{/build/trunk/gcc/expr.c}, but not
 Specifies the line that begins the body of the function @var{function}.
 For example, in C, this is the line with the open brace.
 
+For C@t{++}, @var{function} is interpreted as specifying all functions
+named @var{function} ignoring missing leading specifiers (namespaces
+and classes).
+
+For example, assuming a program with symbols named @code{A::B::func}
+and @code{B::func}, both commands @w{@code{break func}} and
+@w{@code{break B::func}} set a breakpoint on both symbols.  To
+override this, you can use the explicit location option
+@code{-qualified}.  @xref{Explicit Locations}.
+
 @item @var{function}:@var{label}
 Specifies the line where @var{label} appears in @var{function}.
 
@@ -7909,6 +7936,22 @@ on function locations unmodified by other options (such as @code{-label}
 or @code{-line}) refer to the line that begins the body of the function.
 In C, for example, this is the line with the open brace.
 
+For C@t{++}, @var{function} is interpreted as specifying all functions
+named @var{function} ignoring missing leading specifiers (namespaces
+and classes).
+
+For example, assuming a program with symbols named @code{A::B::func}
+and @code{B::func}, both commands @code{break -function func} and
+@code{break -function B::func} set a breakpoint on both symbols.
+
+@item -qualified @var{function}
+Like @code{-function}, but the value specifies a fully qualified name
+of a function.
+
+For example, assuming a C@t{++} program with symbols named
+@code{A::B::func} and @code{B::func}, the @code{break -qualified
+B::func} command sets a breakpoint on @code{B::func}, only.
+
 @item -label @var{label}
 The value specifies the name of a label.  When the function
 name is not specified, the label is searched in the function of the currently
@@ -14992,6 +15035,49 @@ the same notation that is used to declare such symbols in C@t{++}: type
 also use the @value{GDBN} command-line word completion facilities to list the
 available choices, or to finish the type list for you.
 @xref{Completion,, Command Completion}, for details on how to do this.
+
+@item @r{Breakpoints in functions with ABI tags}
+
+The GNU C@t{++} compiler introduced the notion of ABI ``tags'', which
+correspond to changes in the ABI of a type, function, or variable that
+would not otherwise be reflected in a mangled name.  See
+@url{https://developers.redhat.com/blog/2015/02/05/gcc5-and-the-c11-abi/}
+for more detail.
+
+The ABI tags are visible in C@t{++} demangled names.  For example, a
+function that returns a std::string:
+
+@smallexample
+std::string function(int);
+@end smallexample
+
+@noindent
+when compiled for the C++11 ABI is marked with the @code{cxx11} ABI
+tag, and @value{GDBN} displays the symbol like this:
+
+@smallexample
+function[abi:cxx11](int)
+@end smallexample
+
+You can set a breakpoint on such functions simply as if they had no
+tag.  For example:
+
+@smallexample
+(gdb) b function(int)
+Breakpoint 2 at 0x40060d: file main.cc, line 10.
+(gdb) info breakpoints
+Num     Type           Disp Enb Address    What
+1       breakpoint     keep y   0x0040060d in function[abi:cxx11](int)
+                                           at main.cc:10
+@end smallexample
+
+On the rare occasion you need to disambiguate between different ABI
+tags, you can do so by simply including the ABI tag in the function
+name, like:
+
+@smallexample
+(@value{GDBP}) b ambiguous[abi:other_tag](int)
+@end smallexample
 @end table
 
 @node Decimal Floating Point
@@ -16818,6 +16904,7 @@ file-management commands (@pxref{Files, ,Commands to Specify Files}).
 @cindex symbol names
 @cindex names of symbols
 @cindex quoting names
+@anchor{quoting names}
 Occasionally, you may need to refer to symbols that contain unusual
 characters, which @value{GDBN} ordinarily treats as word delimiters.  The
 most frequent case is in referring to static variables in other
diff --git a/gdb/NEWS b/gdb/NEWS
index 112aa2f..eebe89a 100644
--- a/gdb/NEWS
+++ b/gdb/NEWS
@@ -3,6 +3,77 @@
 
 *** Changes since GDB 8.0
 
+* Completion improvements
+
+  ** GDB can now complete function parameters in linespecs and
+     explicit locations without quoting.  When setting breakpoints,
+     quoting around functions names to help with TAB-completion is
+     generally no longer necessary.  For example, this now complete
+     correctly:
+
+      (gdb) b function(in[TAB]
+      (gdb) b function(int)
+
+     Related, GDB is no longer confused with completing functions in
+     C++ anonymous namespaces:
+
+      (gdb) b (anon[TAB]
+      (gdb) b (anonymous namespace)::[TAB][TAB]
+      (anonymous namespace)::a_function()
+      (anonymous namespace)::b_function()
+
+  ** GDB now has much improved linespec and explicit locations TAB
+     completion support, that better understands what you're
+     completing and offers better suggestions.  For example, GDB no
+     longer offers data symbols as possible completions when you're
+     setting a breakpoint.
+
+  ** GDB now TAB-completes label symbol names.
+
+  ** The "complete" command now mimics TAB completion accurately.
+
+* Breakpoints on C++ functions now ignore leading namespaces/classes
+
+  By default, breakpoints on functions/methods are now interpreted as
+  specifying all functions with the given name ignoring missing
+  leading specifiers (namespaces and classes).
+
+  For example, assuming a C++ program with symbols named:
+
+    A::B::func
+    B::func
+
+  both commands "break func" and "break B::func" set a breakpoint on
+  both symbols.  The explicit location option "-function" was changed
+  accordingly.
+
+  To override this, you can specify an explicitly fully qualified
+  name, usign the new explicit location option "-qualified".  For
+  example, using the same C++ program, the "break -qualified B::func"
+  command sets a breakpoint on "B::func", only.
+
+* Breakpoints on functions marked with C++ ABI tags
+
+  GDB can now set breakpoints on functions marked with C++ ABI tags
+  (e.g., [abi:cxx11]).  See here for a description of ABI tags:
+  https://developers.redhat.com/blog/2015/02/05/gcc5-and-the-c11-abi/
+
+  Functions with a C++11 abi tag are demangled/displayed like this:
+
+    function[abi:cxx11](int)
+            ^^^^^^^^^^^
+
+  You can now set a breakpoint on such functions simply as if they had
+  no tag, like:
+
+    (gdb) b function(int)
+
+  Or if you need to disambiguate between tags, like:
+
+    (gdb) b function[abi:other_tag](int)
+
+  Tab completion was adjusted accordingly as well.
+
 *** Changes in GDB 8.0
 
 * GDB now supports access to the PKU register on GNU/Linux. The register is
-- 
2.5.5