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

[Doug Evans <dje@google.com>]

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.