[PATCH v4] gdb/manual: Introduce location specs

[Pedro Alves]

On 2022-05-27 19:42, Pedro Alves wrote:
> On 2022-05-27 19:23, Eli Zaretskii wrote:
>>> Date: Fri, 27 May 2022 18:51:14 +0100
>>> Cc: gdb-patches@sourceware.org
>>> From: Pedro Alves <pedro@palves.net>
>>>
>>>>> Yes.  Well, except "absolute" in the file name.  The file names in the
>>>>> debug info aren't always absolute, they can be something like ../a/b/c/foo.c,
>>>>> and we may not be able to find the source file in the filesystem, so the
>>>>> path the debug info tells us is all we get.
>>>>
>>>> Then the directory should also be part of the attributes, no?
>>>
>>> I thought that in GNU terminology, "file name" already included the directory?
>>> ISTR you saying that we shouldn't use "path" to describe directories sometime ago,
>>> for example.  Maybe I'm misremembering it.
>>
>> A file name includes the directory, but the directory doesn't have to
>> be in the absolute form, as you pointed out.  So the directory
>> relative to which the file name is specified is part of the code
>> location, I think, because there could be file names in a program
>> which have the same name, but live in different subdirectories of a
>> source tree.
> 
> Yes.

BTW, my text says this:

 +The location spec may be incomplete, and @value{GDBN} will do its best
 +to find all the locations in the program that match it.  For example,
 +a location spec may just indicate a line number and a source filename
                                                        ^^^^^^^^^^^^^^^
 +with no directory components, 
  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^

and this example too:

 +@item
 +The location spec specifies a file name, and multiple files in the
 +program share the same name.


IMO, from this it should be obvious that the code location has directory
components that you can match.

The explicit locations section already says for example:

 @table @code
 @item -source @var{filename}
 The value specifies the source file name.  To differentiate between
 files with the same base name, prepend as many directories as is necessary
 to uniquely identify the desired file, e.g., @file{foo/bar/baz.c}.  Otherwise
 @value{GDBN} will use the first file it finds with the given base
 name.   This option requires the use of either @code{-function} or @code{-line}.

I'm not sure we want to go into details like that in the intro section.  Users won't
be able to use any location spec format without reading the corresponding section,
so they'll see this.