Re: [RFA, doc RFA] Avoid calling gdb_realpath if basenames are different

[Doug Evans <dje at google dot com>]

On Fri, Nov 11, 2011 at 12:53 AM, Doug Evans <dje@google.com> wrote:
> On Fri, Nov 11, 2011 at 12:47 AM, Eli Zaretskii <eliz@gnu.org> wrote:
>>> Date: Thu, 10 Nov 2011 15:58:46 -0800
>>> From: Doug Evans <dje@google.com>
>>>
>>> 2011-11-10 ?Doug Evans ?<dje@google.com>
>>>
>>> ? ? ? ? * NEWS: Mention new parameter basenames-may-differ.
>>> ? ? ? ? * dwarf2read.c (dw2_lookup_symtab): Avoid calling gdb_realpath if
>>> ? ? ? ? ! basenames_may_differ.
>>> ? ? ? ? * psymtab.c (lookup_partial_symtab): Ditto.
>>> ? ? ? ? * symtab.c (lookup_symtab): Ditto.
>>> ? ? ? ? (basenames_may_differ): New global.
>>> ? ? ? ? (_initialize_symtab): New parameter basenames-may-differ.
>>> ? ? ? ? * symtab.h (basenames_may_differ): Declare.
>>>
>>> ? ? ? ? doc/
>>> ? ? ? ? * gdb.texinfo (Files): Document basenames-may-differ.
>>
>> Thanks.
>>
>>> +set basenames-may-differ
>>> +show basenames-may-differ
>>> + ?Set whether a source file may have multiple base names.
>>> + ?A "base name" is the name of a file with the directory part removed.
>>> + ?Example: The base name of "/home/user/hello.c" is "hello.c".
>>> + ?When doing file name based lookups, gdb will canonicalize file names
>>> + ?(e.g., expand symlinks) before comparing them, which is an expensive
>>> + ?operation.
>>> + ?If set, gdb will not assume a file is known by one base name, and thus
>>> + ?it cannot optimize file name comparisions by skipping the canonicalization
>>> + ?step if the base names are different.
>>> + ?If not set, all source files must be known by one base name,
>>> + ?and gdb will do file name comparisons more efficiently.
>>
>> I suggest to rearrange the text, so as to put together the parts that
>> describe what happens when the option is set. ?Like this:
>>
>> ?Set whether a source file may have multiple base names.
>> ?(A "base name" is the name of a file with the directory part removed.
>> ?Example: The base name of "/home/user/hello.c" is "hello.c".)
>> ?If set, GDB will canonicalize file names (e.g., expand symlinks)
>> ?before comparing them. ?Canonicalization is an expensive operation,
>> ?but it allows the same file be known by more than one base name.
>> ?If not set (the default), all source files are assumed to have just
>> ?one base name, and gdb will do file name comparisons more efficiently.
>>
>> OK?
>>
>>> +When processing file names provided by the user,
>>> +@value{GDBN} will canonicalize them and remove symbolic links.
>>> +This ensures that @value{GDBN} will find the right file,
>>> +even if the debug information specifies an alternate path.
>>> +However, with large programs this canonicalization can noticeably slow
>>> +down @value{GDBN}. ?To compensate, @value{GDBN} will try to avoid
>>> +this canonicalization wherever possible. ?One way it can do so
>>> +is by first comparing the @samp{base name} of a file.
>>> +The @samp{base name} of a file is simply the file's name without
>>> +any directory information. ?For example, the base name of
>>> +@file{/home/user/hello.c} is @file{hello.c}.
>>> +By doing this @value{GDBN} can skip, for example,
>>> +@file{/usr/include/stdio.h} without having to first canonicalize
>>> +and then compare the directory names.
>>> +This works great, except when the base name of a file
>>> +can have multiple names due to symbolic links.
>>> +For example, if @file{/home/user/bar.c} is a symbolic link to
>>> +@file{/home/user/foo.c} then @value{GDBN} cannot just look at
>>> +the base name of two files, it must canonicalize them, expand
>>> +all symbolic links, and @emph{then} compare the file names
>>> +to see if they match.
>>> +Fortunately, having one file known by two different base names
>>> +does not generally occur in practice.
>>> +Should it occur, however, @value{GDBN} provides an escape hatch
>>> +to allow this to work.
>>> +By setting @code{basenames-may-differ} to @code{true}
>>> +@value{GDBN} will always canonicalize file names before
>>> +comparing them, thus ensuring that one file known by multiple
>>> +base names are treated as the same file.
>>
>> This is written as mostly an apology for having this option. ?That is
>> a wrong angle for describing features in a user manual, because the
>> user generally trusts the developers by default to DTRT. ?So I would
>> reword it
>>
>> ?When processing file names provided by the user, @value{GDBN}
>> ?frequently needs to compare them to the file names recorded in the
>> ?program's debug info. ?Normally, @value{GDBN} compares just the
>> ?@dfn{base names} of the files as strings, which is reasonably fast
>> ?even for very large programs. ?(The base name of a file is the last
>> ?portion of its name, after stripping all the leading directories.)
>> ?This shortcut in comparison is based upon the assumption that files
>> ?cannot have more than one base name. ?This is usually true, but
>> ?references to files that use symlinks or similar filesystem
>> ?facilities violate that assumption. ?If your program records files
>> ?using such facilities, or if you provide file names to @value{GDBN}
>> ?using symlinks etc., you can set @code{basenames-may-differ} to
>> ?@code{true} to instruct @value{GDBN} to completely canonicalize each
>> ?pair of file names it needs to compare. ?This will make file-name
>> ?comparisons accurate, but at a price of a significant slowdown.
>>
>> Do you agree with this wording?
>>
>
> I'm happy if you're happy.
> Thanks for the suggested wording.

Ok to check in?

2011-11-14  Doug Evans  <dje@google.com>

        * NEWS: Mention new parameter basenames-may-differ.
        * dwarf2read.c (dw2_lookup_symtab): Avoid calling gdb_realpath if
        ! basenames_may_differ.
        * psymtab.c (lookup_partial_symtab): Ditto.
        * symtab.c (lookup_symtab): Ditto.
        (basenames_may_differ): New global.
        (_initialize_symtab): New parameter basenames-may-differ.
        * symtab.h (basenames_may_differ): Declare.

        doc/
        * gdb.texinfo (Files): Document basenames-may-differ.

Attachment: gdb-111114-basenames-may-differ-3.patch.txt
Description: Text document